From f34b5f5a7ae9d2a5d76a488c43a0ce1d8a0c93b7 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Tue, 26 May 2026 15:58:06 +0200 Subject: [PATCH 1/2] update configuration pages for stream mode --- .../javascript/common/configuration/apis.mdx | 28 +++++-- .../common/configuration/filtering.mdx | 43 ++++++++++- .../common/configuration/options.mdx | 76 ++++++++++++++++--- .../before-send-span/javascript.mdx | 19 ++++- 4 files changed, 146 insertions(+), 20 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/apis.mdx b/docs/platforms/javascript/common/configuration/apis.mdx index 1620d53177e76..90389c6798b36 100644 --- a/docs/platforms/javascript/common/configuration/apis.mdx +++ b/docs/platforms/javascript/common/configuration/apis.mdx @@ -134,10 +134,10 @@ Sentry.withScope((scope) => { }); ``` - - `beforeSend` and `beforeSendTransaction` are guaranteed to be run last, after all other event processors, (which means they get the final version of the event right before it's sent, hence the name). Event processors added with `addEventProcessor` are run in an undetermined order, which means changes to the event may still be made after the event processor runs. + + `beforeSend`, `beforeSendTransaction`, and `beforeSendSpan` are guaranteed to be run last, after all other event processors, (which means they get the final version of the event right before it's sent, hence the name). Event processors added with `addEventProcessor` are run in an undetermined order, which means changes to the event may still be made after the event processor runs. - There can only be a single `beforeSend` / `beforeSendTransaction` processor, but you can add multiple event processors via `addEventProcessor()`. + There can only be a single `beforeSend` / `beforeSendTransaction` / `beforeSendSpan` processor, but you can add multiple event processors via `addEventProcessor()`. @@ -507,6 +507,12 @@ Sentry.setContext("character", { ## Tracing + + +If you're using stream mode, the Tracing APIs work the same way unless noted otherwise. + + + ', description: 'Attributes to add to the span.' }, { name: 'startTime', type: 'number', description: 'The timestamp to use for the span start. If not provided, the current time will be used.' }, { name: 'op', type: 'string', description: 'The operation name for the span. This is used to group spans in the UI' }, - { name: 'forceTransaction', type: 'boolean', description: 'If true, the span will be forced to be sent as a transaction, even if it is not the root span.' }, + { name: 'forceTransaction', type: 'boolean', description: 'If true, the span will be forced to be sent as a transaction, even if it is not the root span. \n// Not available in stream mode. Use `parentSpan: null` instead to make this span show up as service span.' }, { name: 'parentSpan', type: 'Span | null', description: 'The parent span for the new span. If not provided, the current span will be used.' }, { name: 'onlyIfParent', type: 'boolean', description: 'If true, the span will only be created if there is an active span.' }, ] @@ -570,7 +576,7 @@ See Tracing Instrumentation', description: 'Attributes to add to the span.' }, { name: 'startTime', type: 'number', description: 'The timestamp to use for the span start. If not provided, the current time will be used.' }, { name: 'op', type: 'string', description: 'The operation name for the span. This is used to group spans in the UI' }, - { name: 'forceTransaction', type: 'boolean', description: 'If true, the span will be forced to be sent as a transaction, even if it is not the root span.' }, + { name: 'forceTransaction', type: 'boolean', description: 'If true, the span will be forced to be sent as a transaction, even if it is not the root span. \n// Not available in stream mode. Use `parentSpan: null` instead to make this span show up as service span.' }, { name: 'parentSpan', type: 'Span | null', description: 'The parent span for the new span. If not provided, the current span will be used.' }, { name: 'onlyIfParent', type: 'boolean', description: 'If true, the span will only be created if there is an active span.' }, ] @@ -607,7 +613,7 @@ See Tracing Instrumentation', description: 'Attributes to add to the span.' }, { name: 'startTime', type: 'number', description: 'The timestamp to use for the span start. If not provided, the current time will be used.' }, { name: 'op', type: 'string', description: 'The operation name for the span. This is used to group spans in the UI' }, - { name: 'forceTransaction', type: 'boolean', description: 'If true, the span will be forced to be sent as a transaction, even if it is not the root span.' }, + { name: 'forceTransaction', type: 'boolean', description: 'If true, the span will be forced to be sent as a transaction, even if it is not the root span. \n// Not available in stream mode. Use `parentSpan: null` instead to make this span show up as service span.' }, { name: 'parentSpan', type: 'Span | null', description: 'The parent span for the new span. If not provided, the current span will be used.' }, { name: 'onlyIfParent', type: 'boolean', description: 'If true, the span will only be created if there is an active span.' }, ] @@ -787,8 +793,16 @@ Sentry.reportPageLoaded(); These utilities can be used for more advanced tracing use cases. - + Convert a span to a JSON object. + + The shape of the returned object depends on your tracing mode: + + - In transaction mode (default), `spanToJSON` returns a `SpanJSON` object. + - In stream mode, it returns a `StreamedSpanJSON` object. + +See `beforeSendSpan` for more information about these objects. + + The options in this section are only available in transaction mode. If you're + using stream mode, go to + [Filtering Spans](#filtering-spans). + + To prevent certain transactions from being reported to Sentry, use the or configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. ### Using @@ -137,14 +143,45 @@ See beforeSendT ## Filtering Spans -Use the configuration option which allows you to provide a function to modify a span. -This function is called for the root span and all child spans. If you want to drop the root span, including its child spans, use [`beforeSendTransaction`](#using-beforesendtransaction) instead. -Please note that you cannot use `beforeSendSpan` to drop a span, you can only modify it and filter data on it. +### Using + +Use the configuration option, which lets you provide a function to modify a span. +This function is called for the transaction (service span in stream mode) and all child spans. +If you want to drop the transaction/service span, including its child spans: + +- Use [`beforeSendTransaction`](#using-beforesendtransaction) in transaction mode. +- Use [`ignoreSpans`](#using-ignore-spans) in stream mode. + +Please note that you cannot use `beforeSendSpan` to drop a span; you can only modify it and filter data on it. See beforeSendSpan for details. +## Using + +You can use the option to filter out spans that match a certain pattern by providing a list of strings or regular expressions. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. + +You can also provide an object with `name`, `op`, and `attributes` properties to match on multiple conditions. At least one property must be provided. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + ignoreSpans: [ + "partial/match", + /^Exact Transaction Name$/, + { + name: /^GET \//, + attributes: { + "http.route": "/api/status", + }, + }, + ], +}); +``` + +See ignoreSpans for details. + ## Filtering Breadcrumbs You can filter breadcrumbs by using the `beforeBreadcrumb` configuration option: diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index cee6e0d4f9a50..e94f9bfeb0ee4 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -464,6 +464,12 @@ For example, the Sentry Nuxt SDK does not attach an error handler as it's captur ## Tracing Options + + +If you're using stream mode, tracing options work the same way as described but apply to service spans instead of transactions. + + + **Note:** For Electron, tracing options apply to the process where these options are set. @@ -528,15 +534,33 @@ This is useful to prevent traces of unknown third-party services from being cont This function is called with a transaction event object, and can return a modified transaction event object, or `null` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending. +Not available in stream mode. Instead, use [`ignoreSpans`](#ignoreSpans) to drop spans, or [`beforeSendSpan`](#beforeSendSpan) to modify spans. + -This function is called with a serialized span object, and can return a modified span object. This might be useful for manually stripping PII from spans. -This function is called for root spans as well as for all child spans. -If you want to drop the root span, including all of its child spans, use [`beforeSendTransaction`](#beforeSendTransaction) instead. +This function is called with a serialized span object and can return a modified span object. Use it, for example, to manually strip PII from spans or filter data from spans before they're sent to Sentry. It runs for all spans, including transactions and their child spans. + +Note that `beforeSendSpan` can only modify span data, meaning you cannot use it to drop spans. Use [`ignoreSpans`](#ignoreSpans) to drop spans, or [`beforeSendTransaction`](#beforeSendTransaction) to drop transactions. + +The `span` you receive as an argument is a serialized object, not a `Span` class instance. + +If you're using stream mode, wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` — otherwise the SDK falls back to transaction mode. -Please note that the `span` you receive as an argument is a serialized object, not a `Span` class instance. + + +In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and has different property names: + +| Transaction Mode (`SpanJSON`) | Stream Mode (`StreamedSpanJSON`) | +| ---------------------------------- | ----------------------------------- | +| `span.description` | `span.name` | +| `span.data` (processed attributes) | `span.attributes` (raw attributes) | +| `span.timestamp` (end time) | `span.end_timestamp` | +| `span.status` (optional string) | `span.status` (`'ok'` or `'error'`) | +| `span.op` | `span.attributes['sentry.op']` | + + @@ -544,16 +568,29 @@ Please note that the `span` you receive as an argument is a serialized object, n - +Not available in stream mode. Use [`ignoreSpans`](#ignoreSpans) instead. - + -A list of strings or regex patterns matching span names that shouldn't be sent to Sentry. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. You can also provide an object with a `name` and `op` property to match both the span name and the operation name. Note that at least `name` or `op` must be provided. + -If a root span matches any of the specified patterns, the entire local trace will be dropped. If a child span matches, its children will be reparented to the dropped span's parent span. +A list of strings or regex patterns matching spans that shouldn't be sent to Sentry. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. You can also provide an object with `name`, `op`, and `attributes` properties to match on multiple conditions. At least one property must be provided. +If a matching span is a transaction or service span, the entire local trace will be dropped. If a child span matches, its children will be reparented to the dropped span's parent span. By default, no spans are ignored. +In stream mode, `ignoreSpans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped. + + + +In transaction mode, `ignoreSpans` is evaluated at transaction end rather than at span start. Review your existing rules to make sure the attributes you're matching on are passed when the span is created. + +If you're auto-instrumenting and don't know what the initial name of a span is when it starts, enable SDK debug logging during development by setting `debug: true` when initializing the SDK. + + + + + Here are some predefined matches for common spans to get you started: ```javascript @@ -577,12 +614,24 @@ Sentry.init({ name: /.+\.(png|svg|jpe?g|gif|bmp|tiff?|webp|avif|heic?|ico).*$/, }, + // Drop spans whose name contains "healthcheck" + "healthcheck", + + // Drop spans matching name and attribute conditions + { + name: /^GET \//, + attributes: { + "http.route": "/api/status", + }, + }, + // Measure spans { op: "measure" }, ], }); ``` + @@ -610,6 +659,15 @@ Enable this option if you are using AI + + +Controls how spans are sent to Sentry: + +- In transaction mode (`'static'`, the default), all spans are collected in memory and sent to Sentry as a single transaction once the root span ends. +- In stream mode (`'stream'`), spans are sent in batches as they finish. + + + ## Logs Options @@ -662,7 +720,7 @@ A number between `0` and `1` that sets the percentage of how many sessions shoul Determines how profiling sessions are controlled. It has two modes: - `'manual'` (default): You control when profiling starts and stops using the `startProfiler()` and `stopProfiler()` functions. In this mode, profile sampling is only affected by `profileSessionSampleRate`. Read more about these functions in the profiling API documentation. -- `'trace'`: Profiling starts and stops automatically with transactions, as long as tracing is enabled. The profiler runs as long as there is at least one sampled transaction. In this mode, profiling is affected by both `profileSessionSampleRate` and your tracing sample rate (`tracesSampleRate` or `tracesSampler`). +- `'trace'`: Profiling starts and stops automatically with transactions (or service span if you're using stream mode), as long as tracing is enabled. The profiler runs as long as there is at least one sampled transaction. In this mode, profiling is affected by both `profileSessionSampleRate` and your tracing sample rate (`tracesSampleRate` or `tracesSampler`). diff --git a/platform-includes/configuration/before-send-span/javascript.mdx b/platform-includes/configuration/before-send-span/javascript.mdx index 980af85371be7..5659486333715 100644 --- a/platform-includes/configuration/before-send-span/javascript.mdx +++ b/platform-includes/configuration/before-send-span/javascript.mdx @@ -1,4 +1,4 @@ -```javascript +```javascript {tabTitle:Transaction Mode (Default)} Sentry.init({ dsn: "___PUBLIC_DSN___", beforeSendSpan(span) { @@ -14,3 +14,20 @@ Sentry.init({ }, }); ``` + +```javascript {tabTitle:Stream Mode} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + beforeSendSpan(span) { + if (span.name === "should be renamed") { + span.name = "renamed span"; + span.attributes = { + ...span.attributes, + myExtraAttribute: true, + }; + } + + return span; + }, +}); +``` From c6f9ee735963ce86a8b964418ca1ae8705c496b7 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Wed, 27 May 2026 10:37:02 +0200 Subject: [PATCH 2/2] pr feedback --- .../javascript/common/configuration/filtering.mdx | 4 ++-- .../platforms/javascript/common/configuration/options.mdx | 8 +++++++- .../configuration/before-send-span/javascript.mdx | 4 ++-- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/filtering.mdx b/docs/platforms/javascript/common/configuration/filtering.mdx index 8cab567539c16..005f908fbda3d 100644 --- a/docs/platforms/javascript/common/configuration/filtering.mdx +++ b/docs/platforms/javascript/common/configuration/filtering.mdx @@ -150,7 +150,7 @@ This function is called for the transaction (service span in stream mode) and al If you want to drop the transaction/service span, including its child spans: - Use [`beforeSendTransaction`](#using-beforesendtransaction) in transaction mode. -- Use [`ignoreSpans`](#using-ignore-spans) in stream mode. +- Use [`ignoreSpans`](#using-ignore-spans) in stream mode and wrap it with `Sentry.withStreamedSpan()`. Please note that you cannot use `beforeSendSpan` to drop a span; you can only modify it and filter data on it. @@ -158,7 +158,7 @@ Please note that you cannot use `beforeSendSpan` to drop a span; you can only mo See beforeSendSpan for details. -## Using +### Using You can use the option to filter out spans that match a certain pattern by providing a list of strings or regular expressions. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index e94f9bfeb0ee4..5bbc310aa96f0 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -562,6 +562,12 @@ In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and + + + + + + @@ -720,7 +726,7 @@ A number between `0` and `1` that sets the percentage of how many sessions shoul Determines how profiling sessions are controlled. It has two modes: - `'manual'` (default): You control when profiling starts and stops using the `startProfiler()` and `stopProfiler()` functions. In this mode, profile sampling is only affected by `profileSessionSampleRate`. Read more about these functions in the profiling API documentation. -- `'trace'`: Profiling starts and stops automatically with transactions (or service span if you're using stream mode), as long as tracing is enabled. The profiler runs as long as there is at least one sampled transaction. In this mode, profiling is affected by both `profileSessionSampleRate` and your tracing sample rate (`tracesSampleRate` or `tracesSampler`). +- `'trace'`: Profiling starts and stops automatically with transactions (or service spans if you're using stream mode), as long as tracing is enabled. The profiler runs as long as there is at least one sampled transaction. In this mode, profiling is affected by both `profileSessionSampleRate` and your tracing sample rate (`tracesSampleRate` or `tracesSampler`). diff --git a/platform-includes/configuration/before-send-span/javascript.mdx b/platform-includes/configuration/before-send-span/javascript.mdx index 5659486333715..13b5f9623a3f7 100644 --- a/platform-includes/configuration/before-send-span/javascript.mdx +++ b/platform-includes/configuration/before-send-span/javascript.mdx @@ -18,7 +18,7 @@ Sentry.init({ ```javascript {tabTitle:Stream Mode} Sentry.init({ dsn: "___PUBLIC_DSN___", - beforeSendSpan(span) { + beforeSendSpan: Sentry.withStreamedSpan((span) => { if (span.name === "should be renamed") { span.name = "renamed span"; span.attributes = { @@ -28,6 +28,6 @@ Sentry.init({ } return span; - }, + }), }); ```