self-hosted
self-hosted copied to clipboard
Add New Trace Explorer + Span-based Metrics
Problem Statement
This is not necessarily "span metrics" per se, since this issue is for enabling the EAP (Event Analytics Platform) Spans feature, which right now holds the span metrics functionality. I don't know what this feature will hold in the future, but let's just see.
Product documentation: https://docs.sentry.io/product/explore/new-trace-explorer/ Product announcements: https://blog.sentry.io/find-and-fix-performance-bottlenecks-with-sentrys-trace-explorer/ Usage for JavaScript SDK users: https://github.com/getsentry/sentry-javascript/discussions/13136
Solution Brainstorm
The way we'll tell you how to configure this should be versioned (learned this the hard way from User Feedback feature). Grab the version you're currently on (or if yours is higher than any of these, choose the highest one).
Setup Guide for 25.2.0
Date of writing: 2025-02-28
Make sure you've enabled this: https://github.com/getsentry/self-hosted/issues/3272 -- after you add trace-view related config, you don't need to run ./install.sh first, you can continue adding these configurations below.
On your sentry/sentry.conf.py, add these feature flags:
SENTRY_FEATURES.update(
{
feature: True
for feature in (
# .... the default or other feature flags
)
# EAP spans stuff
+ (
"organizations:transaction-metrics-extraction", # Extraction metrics for transactions during ingestion.
"organizations:anomaly-detection-eap", # Enable anomaly detection feature for EAP spans
"organizations:dashboards-eap", # Enable events analytics platform data in dashboards
# NOTE: "insights-use-eap" is optional, you can enable it on your own
#"organizations:insights-use-eap", # Make Insights modules use EAP instead of metrics
"organizations:ingest-spans-in-eap", # Enable tagging span with whether or not we should ingest it in the EAP
# NOTE: "use-eap-spans-for-metrics-explorer" is optional, you can enable it on your own
#"projects:use-eap-spans-for-metrics-explorer", # EAP: extremely experimental flag that makes DDM page use EAP tables
"organizations:indexed-spans-extraction", # Starfish: extract metrics from the spans
"organizations:visibility-explore-view", # Enable the new explore page
"organizations:visibility-explore-admin", # Enable admin features on the new explore page
"organizations:visibility-explore-equations", # Enable equations feature on the new explore page
# NOTE: "visibility-explore-dataset" is optoinal, you cna enable it on your own
#"organizations:visibility-explore-dataset", # Enable the dataset toggle on the new explore page
"organizations:visibility-explore-rpc", # Enable RPC on the new explore page
"organizations:visibility-explore-range-high", # Enable high date range options on new explore page
"organizations:explore-multi-query", # Enable explore multi query page
)
}
)
On your docker-compose.yml, add these new containers:
detect-performance-issues:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset detect-performance-issues --consumer-group detect-performance-issues
profiles: [feature-complete]
process-spans:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset process-spans --consumer-group process-spans
profiles: [feature-complete]
eap-spans-subscription-results:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset eap-spans-subscription-results --consumer-group eap-spans-subscription-results
profiles: [feature-complete]
# !!! NOTICE, READ ME !!!
# Like usual, this snuba consumer uses `rust-consumer` version.
# If you are getting some issues (crash or anything),
# feel free to change `rust-consumer` to `consumer`
# and remove the `--use-rust-processor` flag.
# which is written in Python.
snuba-spans-consumer:
<<: *snuba_defaults
command: rust-consumer --storage spans --consumer-group snuba-spans-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
snuba-eap-spans-consumer:
<<: *snuba_defaults
command: rust-consumer --storage eap_spans --consumer-group snuba-eap-spans-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
Setup Guide for 25.3.0
Date of writing: 2025-03-18
On your sentry/sentry.conf.py, add these feature flags:
SENTRY_FEATURES.update(
{
feature: True
for feature in (
# .... the default or other feature flags
)
# Trace View -- make sure this is all set
+ (
"organizations:trace-view-v1", # This one is mandatory
"organizations:replay-trace-view-v1",
"organizations:trace-drawer-action",
"organizations:trace-spans-format",
)
# Performance Trace Explorer
+ (
"organizations:performance-new-widget-designs",
"organizations:performance-span-histogram-view",
"organizations:performance-spans-new-ui",
"organizations:performance-use-metrics",
"organizations:performance-trace-details",
"organizations:performance-trace-explorer", # This one is the most mandatory of all that
"organizations:performance-trace-explorer-sorting"
"organizations:performance-tracing-without-performance",
)
# Span-based Metrics
+ (
"organizations:transaction-metrics-extraction", # Extraction metrics for transactions during ingestion.
"organizations:anomaly-detection-eap", # Enable anomaly detection feature for EAP spans
"organizations:dashboards-eap", # Enable events analytics platform data in dashboards
# NOTE: "insights-use-eap" is optional, you can enable it on your own
#"organizations:insights-use-eap", # Make Insights modules use EAP instead of metrics
"organizations:ingest-spans-in-eap", # Enable tagging span with whether or not we should ingest it in the EAP
# NOTE: "use-eap-spans-for-metrics-explorer" is optional, you can enable it on your own
#"projects:use-eap-spans-for-metrics-explorer", # EAP: extremely experimental flag that makes DDM page use EAP tables
"organizations:indexed-spans-extraction", # Starfish: extract metrics from the spans
"organizations:visibility-explore-view", # Enable the new explore page
"organizations:visibility-explore-admin", # Enable admin features on the new explore page
"organizations:visibility-explore-equations", # Enable equations feature on the new explore page
# NOTE: "visibility-explore-dataset" is optoinal, you cna enable it on your own
#"organizations:visibility-explore-dataset", # Enable the dataset toggle on the new explore page
"organizations:visibility-explore-rpc", # Enable RPC on the new explore page
"organizations:visibility-explore-range-high", # Enable high date range options on new explore page
"organizations:explore-multi-query", # Enable explore multi query page
)
}
)
On your docker-compose.yml, add these new containers:
detect-performance-issues:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset detect-performance-issues --consumer-group detect-performance-issues
profiles: [feature-complete]
process-spans:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset process-spans --consumer-group process-spans
profiles: [feature-complete]
eap-spans-subscription-results:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset eap-spans-subscription-results --consumer-group eap-spans-subscription-results
profiles: [feature-complete]
# !!! NOTICE, READ ME !!!
# Like usual, this snuba consumer uses `rust-consumer` version.
# If you are getting some issues (crash or anything),
# feel free to change `rust-consumer` to `consumer`
# and remove the `--use-rust-processor` flag.
# which is written in Python.
snuba-spans-consumer:
<<: *snuba_defaults
command: rust-consumer --storage spans --consumer-group snuba-spans-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
snuba-eap-spans-consumer:
<<: *snuba_defaults
command: rust-consumer --storage eap_spans --consumer-group snuba-eap-spans-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
Something I ran into: https://github.com/getsentry/sentry/pull/85848
I am using nightly though so it might not be relevant for 25.3.0 (although I think it is), but it for sure relevant for the next release.
Setup Guide for 25.4.0
Date of writing: 2025-04-17
[!WARNING] This will be a chaotic breaking change. Please read everything carefully, don't blindly copy - paste all this.
Make sure you have enough storage, since this will be dual-writing the spans data to two ClickHouse tables. If you have access to S3 (with cheap ingress/egress fee -- otherwise don't even bother) or MinIO storage, you might want to use that. See https://develop.sentry.dev/self-hosted/experimental/external-storage/ and https://github.com/stayallive/sentry-nodestore-s3
Make sure you have enough RAM and swapfile. On my own server, 8 cores CPU and 16GB RAM and 16 GB swapfile is enough.
On your sentry/sentry.conf.py, add these feature flags:
SENTRY_FEATURES.update(
{
feature: True
for feature in (
# .... the default or other feature flags
# !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!!
# REMOVE "organizations:dynamic-sampling" from the feature flag list!
# !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!!
)
# Trace View -- make sure this is all set
+ (
"organizations:trace-view-v1", # This one is required
"organizations:replay-trace-view-v1", # Optional
"organizations:trace-drawer-action", # Optional
"organizations:trace-spans-format", # Optional
)
# Performance Trace Explorer
+ (
"organizations:performance-trace-explorer", # Required
"organizations:performance-trace-details", # Required
"organizations:performance-trace-explorer-sorting"
"organizations:performance-tracing-without-performance",
"organizations:performance-span-histogram-view", # Probably required
"organizations:performance-spans-new-ui", # Probably mandatory? I'm not sure
"organizations:issue-details-new-performance-trace-view", # Optional. So you can see performance from issue details page
)
# Span-based Metrics
+ (
"organizations:indexed-spans-extraction", # Mandatory! Starfish: extract metrics from the spans
"organizations:visibility-explore-view", # Mandatory! Enable the new explore page
"organizations:ingest-spans-in-eap", # Mandatory! Enable tagging span with whether or not we should ingest it in the EAP
"organizations:performance-issues-spans",
"organizations:performance-transaction-summary-eap",
"organizations:anomaly-detection-eap", # Enable anomaly detection feature for EAP spans
"organizations:insights-use-eap", # Make Insights modules use EAP instead of metrics
"organizations:transaction-metrics-extraction", # Extraction metrics for transactions during ingestion.
"organizations:visibility-explore-admin", # Enable admin features on the new explore page
"organizations:visibility-explore-equations", # Enable equations feature on the new explore page
"organizations:visibility-explore-range-high", # Enable high date range options on new explore page
"organizations:explore-multi-query", # Enable explore multi query page
)
}
)
On your docker-compose.yml, add these new containers:
process-spans:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset process-spans --consumer-group process-spans
profiles: [feature-complete]
process-segments:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset process-segments --consumer-group process-segments
profiles: [feature-complete]
eap-spans-subscription-results:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset eap-spans-subscription-results --consumer-group eap-spans-subscription-results
profiles: [feature-complete]
snuba-subscription-consumer-eap-spans:
<<: *snuba_defaults
command: subscriptions-scheduler-executor --dataset events_analytics_platform --entity eap_spans --auto-offset-reset=latest --no-strict-offset-reset --consumer-group=snuba-eap-spans-subscriptions-consumers --followed-consumer-group=eap_spans_group --schedule-ttl=60 --stale-threshold-seconds=900
profiles: [feature-complete]
# !!! NOTICE, READ ME !!!
# Like usual, this snuba consumer uses `rust-consumer` version.
# If you are getting some issues (crash or anything),
# feel free to change `rust-consumer` to `consumer`
# and remove the `--use-rust-processor` flag.
# which is written in Python.
snuba-spans-consumer:
<<: *snuba_defaults
command: rust-consumer --storage spans --consumer-group snuba-spans-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
snuba-eap-items-span-consumer:
<<: *snuba_defaults
command: rust-consumer --storage eap_items --consumer-group snuba-eap-items-span-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
Then run ./install.sh.
Hi Tony @Zylphrex, since Span-based Metrics via EAP is in General Availability, would you (or someone from your team) willing to take the ownership to implement the feature on self-hosted? Thanks!
Setup Guide for 25.5.0
Date of writing: 2025-05-19
Exactly with 25.4.0, but with one diff:
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -583,7 +583,7 @@ services:
profiles: [feature-complete]
snuba-subscription-consumer-eap-spans:
<<: *snuba_defaults
- command: subscriptions-scheduler-executor --dataset events_analytics_platform --entity eap_spans --auto-offset-reset=latest --no-strict-offset-reset --consumer-group=snuba-eap-spans-subscriptions-consumers --followed-consumer-group=eap_spans_group --schedule-ttl=60 --stale-threshold-seconds=900
+ command: subscriptions-scheduler-executor --dataset events_analytics_platform --entity eap_items_span --auto-offset-reset=latest --no-strict-offset-reset --consumer-group=snuba-eap-spans-subscriptions-consumers --followed-consumer-group=eap_spans_group --schedule-ttl=60 --stale-threshold-seconds=900
profiles: [feature-complete]
Do not apply the patch, it won't work. Modify it manually, then re-run ./install.sh
@aldy505 There's some clean up work underway at the moment. Once all that is complete, we'll be turning on the feature in self hosted.
FYI this does not work on 25.5.1, today I'm trying to figure out why (first of all, this: https://github.com/getsentry/relay/pull/4688).
Setup Guide for 25.5.1
Date of writing: 2025-06-06
Okay so after I made some wrong move on my own instance, I'm finally back. On this release, you might also want to enable #3560 since it uses EAP (Event Analytics Platform) too.
On sentry/sentry.conf.py:
SENTRY_FEATURES.update(
{
feature: True
for feature in (
# .... the default or other feature flags
# !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!!
# REMOVE "organizations:dynamic-sampling" from the feature flag list!
# !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!!
)
# Trace View -- make sure this is all set
+ (
"organizations:trace-view-v1", # This one is required
"organizations:trace-view-load-more", # Optional
"organizations:trace-tabs-ui", # Optional
"organizations:trace-view-linked-traces", # Optional
"organizations:trace-spans-format", # Optional
)
# Performance Trace Explorer
+ (
"organizations:performance-trace-explorer", # Required
"organizations:performance-trace-details", # Required
"organizations:performance-trace-explorer-sorting"
"organizations:performance-tracing-without-performance",
"organizations:performance-span-histogram-view", # Probably required
"organizations:performance-spans-new-ui", # Probably mandatory? I'm not sure
"organizations:issue-details-new-performance-trace-view", # Optional. So you can see performance from issue details page
)
# Span-based Metrics
+ (
"organizations:span-stats",
"organizations:performance-issues-spans",
"organizations:transaction-metrics-extraction", # Extraction metrics for transactions during ingestion.
"organizations:indexed-spans-extraction", # Starfish: extract metrics from the spans
"organizations:visibility-explore-view", # Enable the new explore page
"organizations:visibility-explore-admin", # Enable admin features on the new explore page
"organizations:visibility-explore-equations", # Enable equations feature on the new explore page
"organizations:visibility-explore-progressive-loading",
"organizations:visibility-explore-skip-preflight",
"organizations:visibility-explore-tabs", # Enable merging all the modes into tabs
"organizations:visibility-explore-range-high", # Enable high date range options on new explore page
"organizations:explore-multi-query", # Enable explore multi query page
)
}
)
On your docker-compose.yml:
process-spans:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset process-spans --consumer-group process-spans
profiles: [feature-complete]
process-segments:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset process-segments --consumer-group process-segments
profiles: [feature-complete]
eap-spans-subscription-results:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset eap-spans-subscription-results --consumer-group eap-spans-subscription-results
profiles: [feature-complete]
# !!! NOTICE, READ ME !!!
# Like usual, this snuba consumer uses `rust-consumer` version.
# If you are getting some issues (crash or anything),
# feel free to change `rust-consumer` to `consumer`
# and remove the `--use-rust-processor` flag.
# which is written in Python.
snuba-spans-consumer:
<<: *snuba_defaults
command: rust-consumer --storage spans --consumer-group snuba-spans-consumers --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
snuba-eap-items-span-consumer:
<<: *snuba_defaults
command: rust-consumer --storage eap_items_span --consumer-group eap_items_span_group --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
# This is for logs feature. Might as well enable this.
snuba-eap-items-consumer:
<<: *snuba_defaults
command: rust-consumer --storage eap_items --consumer-group eap_items_group --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
snuba-subscription-consumer-eap-spans:
<<: *snuba_defaults
command: subscriptions-scheduler-executor --dataset events_analytics_platform --entity eap_items_span --auto-offset-reset=latest --no-strict-offset-reset --consumer-group=snuba-eap-spans-subscriptions-consumers --followed-consumer-group=eap_items_span_group --schedule-ttl=60 --stale-threshold-seconds=900
profiles: [feature-complete]
# This container below is for 25.6.0, so get yourself ready.
# subscription-consumer-eap-items:
# <<: *sentry_defaults
# command: run consumer subscription-results-eap-items --consumer-group subscription-results-eap-items
# profiles: [feature-complete]
Then re-run ./install.sh
Setup Guide for 25.5.1
Hi! Looks like following flags were removed
performance-trace-explorer-sortinghttps://github.com/getsentry/sentry/pull/84024/filesorganizations:issue-details-new-performance-trace-viewhttps://github.com/getsentry/sentry/pull/88758/filesorganizations:visibility-explore-adminhttps://github.com/getsentry/sentry/pull/93660/filesorganizations:visibility-explore-progressive-loadinghttps://github.com/getsentry/sentry/pull/93660/filesorganizations:visibility-explore-skip-preflighthttps://github.com/getsentry/sentry/pull/93660/filesorganizations:visibility-explore-tabshttps://github.com/getsentry/sentry/pull/93660/filesorganizations:explore-multi-queryhttps://github.com/getsentry/sentry/pull/93660/files
Just to be clear
Make sure you have enough storage, since this will be dual-writing the spans data to two ClickHouse tables.
Will it be like this forever or it's just a migration period?
Just to be clear
Make sure you have enough storage, since this will be dual-writing the spans data to two ClickHouse tables.
Will it be like this forever or it's just a migration period?
@doc-sheet well, so for a bad news: The current spans ingestion process is being done by snuba-spans:
https://github.com/getsentry/self-hosted/blob/acbdee40df6d4ecf9eb4645ac5b45ec739f537cf/docker-compose.yml#L303C3-L307
Later, we'll move to Event Analytics Platforms (abbreviated as EAP) (see https://github.com/getsentry/self-hosted/pull/3778), in which the idea is to make everything, literally everything from errors, logs (which already uses it), spans, user feedback, uptime, and crons to use it.
When we're fully switched to EAP, the snuba spans consumer will be removed since the ingestion process is being done by eap-items consumer.
If you're using this issue's patch, well... it'd be for at least 1-2 more months.
Setup Guide for 25.7.0
Date of writing: 2025-07-17
On sentry/sentry.conf.py:
SENTRY_FEATURES.update(
{
feature: True
for feature in (
# .... the default or other feature flags
# !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!!
# BRING BACK "organizations:dynamic-sampling", DO NOT REMOVE!
# !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!!
)
# Trace View is not needed anymore
# Performance Trace Explorer
+ (
"organizations:performance-trace-explorer", # Required
"organizations:visibility-explore-view", # Required
"organizations:visibility-explore-aggregate-editor", # Enable aggregates table editor on the new explore page
"organizations:visibility-explore-equations", # Enable equations feature on the new explore page
"organizations:visibility-explore-range-high", # Enable high date range options on new explore page
)
# Event Analytics Platform
+ (
"organizations:span-stats",
"organizations:performance-issues-spans",
"organizations:transaction-metrics-extraction", # Extraction metrics for transactions during ingestion.
"organizations:indexed-spans-extraction", # Starfish: extract metrics from the spans
)
}
)
On your docker-compose.yml, add these:
eap-spans-subscription-results:
<<: *sentry_defaults
command: run consumer --no-strict-offset-reset eap-spans-subscription-results --consumer-group eap-spans-subscription-results
profiles: [feature-complete]
snuba-eap-items-span-consumer:
<<: *snuba_defaults
command: rust-consumer --storage eap_items_span --consumer-group eap_items_span_group --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor
profiles: [feature-complete]
# This is for logs feature. Might as well enable this.
snuba-subscription-consumer-eap-spans:
<<: *snuba_defaults
command: subscriptions-scheduler-executor --dataset events_analytics_platform --entity eap_items_span --auto-offset-reset=latest --no-strict-offset-reset --consumer-group=snuba-eap-spans-subscriptions-consumers --followed-consumer-group=eap_items_span_group --schedule-ttl=60 --stale-threshold-seconds=900
profiles: [feature-complete]
Then re-run ./install.sh
Setup Guide for 25.7.0
Date of writing: 2025-07-17
On
sentry/sentry.conf.py:SENTRY_FEATURES.update( { feature: True for feature in ( # .... the default or other feature flags # !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!! # BRING BACK "organizations:dynamic-sampling", DO NOT REMOVE! # !!!!!!!!!!!! README !!!!!!!!!!!!!!!!!! ) # Trace View is not needed anymore # Performance Trace Explorer + ( "organizations:performance-trace-explorer", # Required "organizations:visibility-explore-view", # Required "organizations:visibility-explore-aggregate-editor". # Enable aggregates table editor on the new explore page "organizations:visibility-explore-equations", # Enable equations feature on the new explore page "organizations:visibility-explore-range-high", # Enable high date range options on new explore page ) # Event Analytics Platform + ( "organizations:span-stats", "organizations:performance-issues-spans", "organizations:transaction-metrics-extraction", # Extraction metrics for transactions during ingestion. "organizations:indexed-spans-extraction", # Starfish: extract metrics from the spans ) } ) On your
docker-compose.yml, add these:eap-spans-subscription-results: <<: *sentry_defaults command: run consumer --no-strict-offset-reset eap-spans-subscription-results --consumer-group eap-spans-subscription-results profiles: [feature-complete] snuba-eap-items-span-consumer: <<: *snuba_defaults command: rust-consumer --storage eap_items_span --consumer-group eap_items_span_group --auto-offset-reset=latest --max-batch-time-ms 1000 --no-strict-offset-reset --use-rust-processor profiles: [feature-complete]
This is for logs feature. Might as well enable this.
snuba-subscription-consumer-eap-spans: <<: *snuba_defaults command: subscriptions-scheduler-executor --dataset events_analytics_platform --entity eap_items_span --auto-offset-reset=latest --no-strict-offset-reset --consumer-group=snuba-eap-spans-subscriptions-consumers --followed-consumer-group=eap_items_span_group --schedule-ttl=60 --stale-threshold-seconds=900 profiles: [feature-complete] Then re-run
./install.sh
There is a dot at
"organizations:visibility-explore-aggregate-editor". # Enable aggregates table editor on the new explore page
if someone run into error
Hi @aldy505, so, those additional containers are no longer needed for the 25.8.0 release?
Hi @aldy505, so, those additional containers are no longer needed for the 25.8.0 release?
No they don't