From 9c371ab4dca5b0610e8eb2f532ad75883c266475 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Mar 2026 15:13:36 +0100 Subject: [PATCH 1/3] docs: Add strict trace continuation docs for Capacitor and React Native - Remove `categorySupported` restriction from `strictTraceContinuation` and `orgId` options so they show for all JS platforms (not just server/serverless) - Create Capacitor distributed tracing include with strict trace continuation section - Add strict trace continuation section to React Native distributed tracing include --- .../common/configuration/options.mdx | 4 +- .../how-to-use/javascript.capacitor.mdx | 54 +++++++++++++++++++ .../how-to-use/react-native.mdx | 30 +++++++++++ 3 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 platform-includes/distributed-tracing/how-to-use/javascript.capacitor.mdx diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 9761465d6983a..1c9e97e4ea325 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -18,7 +18,7 @@ sidebar_order: 1 - + The organization ID for your Sentry project. @@ -436,7 +436,7 @@ If you want to disable trace propagation, you can set this option to `[]`. - + If set to `true`, the SDK will only continue a trace if the organization ID of the incoming trace found in the `baggage` header matches the organization ID of the current Sentry client. diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.capacitor.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.capacitor.mdx new file mode 100644 index 0000000000000..c67ea38598c22 --- /dev/null +++ b/platform-includes/distributed-tracing/how-to-use/javascript.capacitor.mdx @@ -0,0 +1,54 @@ +If you're using the current version of our Capacitor SDK, distributed tracing will work out of the box. + +To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues, define your `tracePropagationTargets`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + tracePropagationTargets: ["https://myproject.org", /^\/api\//], +}); +``` + +### Strict Trace Continuation + +When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry. +By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service, +as it can lead to unwanted traces, increased billing, and skewed performance data. + +To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization. +Otherwise, it starts a new trace. + +```javascript {4} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + // Ensure that only traces from your own organization are continued + strictTraceContinuation: true, +}); +``` + +The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option: + +```javascript {5} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + strictTraceContinuation: true, + // Manually provide your organization ID (overrides organization ID parsed from DSN) + orgId: 12345, +}); +``` + +### Disabling Distributed Tracing + +If you want to disable distributed tracing and ensure no Sentry trace headers are sent, you can configure your SDK like this: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Overwrite the defaults to ensure no trace headers are sent + tracePropagationTargets: [], +}); +``` diff --git a/platform-includes/distributed-tracing/how-to-use/react-native.mdx b/platform-includes/distributed-tracing/how-to-use/react-native.mdx index cbad4b0a41058..2284ba7d0a1f3 100644 --- a/platform-includes/distributed-tracing/how-to-use/react-native.mdx +++ b/platform-includes/distributed-tracing/how-to-use/react-native.mdx @@ -8,3 +8,33 @@ Sentry.init({ ``` If you're using version `5.9.x` or below, you'll need to have our tracing feature enabled in order for distributed tracing to work. + +### Strict Trace Continuation + +When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry. +By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service, +as it can lead to unwanted traces, increased billing, and skewed performance data. + +To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization. +Otherwise, it starts a new trace. + +```javascript {4} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + // Ensure that only traces from your own organization are continued + strictTraceContinuation: true, +}); +``` + +The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option: + +```javascript {5} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + strictTraceContinuation: true, + // Manually provide your organization ID (overrides organization ID parsed from DSN) + orgId: 12345, +}); +``` From dafdee87918b9d376aed243036e33cdf74885f20 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Mar 2026 15:15:53 +0100 Subject: [PATCH 2/3] docs: Scope PR to Capacitor only, remove React Native changes --- .../how-to-use/react-native.mdx | 30 ------------------- 1 file changed, 30 deletions(-) diff --git a/platform-includes/distributed-tracing/how-to-use/react-native.mdx b/platform-includes/distributed-tracing/how-to-use/react-native.mdx index 2284ba7d0a1f3..cbad4b0a41058 100644 --- a/platform-includes/distributed-tracing/how-to-use/react-native.mdx +++ b/platform-includes/distributed-tracing/how-to-use/react-native.mdx @@ -8,33 +8,3 @@ Sentry.init({ ``` If you're using version `5.9.x` or below, you'll need to have our tracing feature enabled in order for distributed tracing to work. - -### Strict Trace Continuation - -When your application receives requests, they might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry. -By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the requests are from a third-party service, -as it can lead to unwanted traces, increased billing, and skewed performance data. - -To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK checks the incoming request for Sentry trace information and only continues the trace if it belongs to the same Sentry organization. -Otherwise, it starts a new trace. - -```javascript {4} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - // Ensure that only traces from your own organization are continued - strictTraceContinuation: true, -}); -``` - -The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option: - -```javascript {5} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - strictTraceContinuation: true, - // Manually provide your organization ID (overrides organization ID parsed from DSN) - orgId: 12345, -}); -``` From b00eba406d5abd6ffa2c09dcb7cd39216c409ed4 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 19 May 2026 10:25:51 +0200 Subject: [PATCH 3/3] revert: Drop options.mdx changes, already handled on master MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit orgId categorySupported was already removed in #17724. strictTraceContinuation stays server/serverless-only, aligned with RN approach — the feature is documented in the distributed tracing guide. Co-Authored-By: Claude Opus 4.6 --- .../common/configuration/options.mdx | 105 ++++++++++++++++-- 1 file changed, 97 insertions(+), 8 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 1c9e97e4ea325..cee6e0d4f9a50 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -12,8 +12,13 @@ sidebar_order: 1 ## Core Options - The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. - Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization). + + **Note:** Electron `main` process only. + + +The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. +Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization). + @@ -23,9 +28,13 @@ sidebar_order: 1 The organization ID for your Sentry project. The SDK will try to extract the organization ID from the DSN. If it cannot be found, or if you need to override it, -you can provide the ID with this option. The organization ID is used for trace propagation and features like `strictTraceContinuation`. +you can provide the ID with this option. The organization ID is used for trace propagation. + + + +It is also used for features like strict trace continuation. -The organization ID is used for features like strict trace continuation. + @@ -36,6 +45,9 @@ Turns debug mode on or off. If debug is enabled SDK will attempt to print out us + + **Note:** Electron `main` process only. + Sets the release. Release names are strings, but some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in [the releases documentation](/product/releases/) or the sandbox. @@ -57,6 +69,9 @@ Sets the release. Release names are strings, but some formats are detected by Se + + **Note:** Electron `main` process only. + Sets the environment. Defaults to `development` or `production` depending on whether the application is packaged. @@ -74,6 +89,20 @@ Sets the URL that will be used to transport captured events. This can be used to + + + + +Controls whether the SDK proxies envelopes through the Sentry Lambda extension at `http://localhost:9000/envelope`. The extension keeps running across Lambda's freeze/thaw boundary, so events queued just before a freeze still get delivered. + +Defaults to `true` when the SDK detects it's running inside the [Sentry Lambda Layer](/platforms/javascript/guides/aws-lambda/install/layer/). Has no effect outside the layer — set [`tunnel`](#tunnel) explicitly instead, for example, when [installing the extension into a container image](/platforms/javascript/guides/aws-lambda/install/container-image/). + +Set to `false` to opt out, for example, when using a custom `tunnel` or when running behind an HTTP proxy that intercepts `localhost`. + + + + + Set this option to `true` to send default PII data to Sentry. Among other things, enabling this will enable automatic IP address collection on events. @@ -88,6 +117,10 @@ This variable controls the total amount of breadcrumbs that should be captured. + + Enabled per Electron process. + + When enabled, stack traces are automatically attached to all messages logged. Stack traces are always attached to exceptions; however, when this option is set, stack traces are also sent with messages. This option, for instance, means that stack traces appear next to all messages captured with `Sentry.captureMessage()`. Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events. @@ -105,12 +138,17 @@ Most SDKs will attempt to auto-discover this value. +**Note:** Electron `main` process only. + When not set to `false`, the SDK tracks sessions linked to the lifetime of the Electron main process. + + **Note:** Electron `main` process only. + Data to be set to the initial scope. Initial scope can be defined either as an object or a callback function, as shown below. @@ -196,6 +234,10 @@ See + + Controls breadcrumb capture in the Electron process where callback is set. + + This function is called with a breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object. The callback gets a second argument (called a "hint") which contains the original object from which the breadcrumb was created to further customize what the breadcrumb should look like. @@ -203,7 +245,11 @@ The callback gets a second argument (called a "hint") which contains the origina -The JavaScript SDK uses a transport to send events to Sentry. On modern browsers, most transports use the browsers' fetch API to send events. Transports will drop an event if it fails to send due to a lack of connection. + + The JavaScript SDK uses a transport to send events to Sentry. On modern + browsers, most transports use the browsers' fetch API to send events. + Transports will drop an event if it fails to send due to a lack of connection. + In the browser, a `fetch`-based transport is used by default. @@ -213,6 +259,12 @@ The JavaScript SDK uses a transport to send events to Sentry. On modern browsers On the server, a `https`-based transport is used by default. + + In the Electron `main` process, the default transport handles queuing events + when the users device is offline. In Electron `renderer` processes, the + default transport forwards events to the main process. + + @@ -249,8 +301,8 @@ Options used to configure the transport. This is an object with the following po The Electron SDK provides built-in offline support that queues events when the app is offline and automatically sends them once the connection is restored. These options let you configure the following behavior: -- `maxAgeDays`: The maximum number of envelopes to keep in the queue. -- `maxQueueSize`: The maximum number of days to keep an envelope in the queue. +- `maxAgeDays`: The maximum number of days to keep an envelope in the queue. +- `maxQueueSize`: The maximum number of envelopes to keep in the queue. - `flushAtStartup`: Whether the offline store should flush shortly after application startup. Defaults to `false`. - `shouldSend`: Called before the SDK attempts to send an envelope to Sentry. If this function returns false, `shouldStore` will be called to determine if the envelope should be stored. Defaults to `() => true`. - `shouldStore`: Called before an event is stored. Return `false` to drop the envelope rather than store it. Defaults to `() => true`. @@ -283,6 +335,7 @@ This means the SDK detected that the library hasn't been wrapped for automatic p +**Note:** Electron `main` process only. Inter-process communication mode to receive event and scope updates from renderer processes. @@ -331,6 +384,12 @@ If the callback is not set, or it returns `undefined`, the default naming scheme Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. + + In the Electron `main` process `sampleRate` applies to events captured all + processes. In Electron `renderer` processes, the `sampleRate` only applies to + that process. + + @@ -339,6 +398,12 @@ This function is called with an SDK-specific message or error event object, and By the time `beforeSend` is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect. + + In the Electron `main` process `beforeSend` is called for events captured in + all processes. In Electron `renderer` processes, `beforeSend` only applies to + that process. + + @@ -357,6 +422,12 @@ Available options: + + In the Electron `main` process `ignoreErrors` applies to events captured in + all processes. In Electron `renderer` processes, `ignoreErrors` applies only + to that process. + + @@ -393,6 +464,11 @@ For example, the Sentry Nuxt SDK does not attach an error handler as it's captur ## Tracing Options + + **Note:** For Electron, tracing options apply to the process where these + options are set. + + A number between `0` and `1`, controlling the percentage chance a given transaction will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. Either this or `tracesSampler` must be defined to enable tracing. @@ -436,7 +512,7 @@ If you want to disable trace propagation, you can set this option to `[]`. - + If set to `true`, the SDK will only continue a trace if the organization ID of the incoming trace found in the `baggage` header matches the organization ID of the current Sentry client. @@ -526,8 +602,21 @@ See De + + +When set to `true`, `gen_ai` spans are sent as standalone envelope items instead of being bundled in the transaction payload. This prevents AI spans with large inputs and outputs from being dropped due to transaction payload size limits. + +Enable this option if you are using AI Agent Monitoring or the Conversations feature. + + + ## Logs Options + + **Note:** For Electron, log options apply to the process where these options + are set. + + Set this option to `true` to enable log capturing in Sentry. Only when this is enabled will the `logger` APIs actually send logs to Sentry.