From 28080fbe7eb4917ab1210128cd40dffe49b3461a Mon Sep 17 00:00:00 2001 From: "Daniel Szoke (via Pi Coding Agent)" Date: Thu, 5 Mar 2026 11:22:13 +0000 Subject: [PATCH 1/3] docs(trace-propagation): Clarify strict trace continuation rules Clarify which strictTraceContinuation requirements always apply and which depend on the option value. Define incoming org ID comparison outcomes by case so continuation behavior is explicit and matches the examples. Keep behavior unchanged while tightening wording. Replace the inline DSN parsing example with a link to the DSN parsing spec, and add a maintainer requirement that SDK docs for orgId recommend setting orgId for self-hosted and local Relay deployments. --- .../foundations/trace-propagation/index.mdx | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 06c6ba49cac4d..e6724f3ebcf62 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -130,21 +130,27 @@ This option replaces the non-standardized `tracingOrigins` option which was prev ### strictTraceContinuation -This **MUST** be a boolean value. Default is `false`. This option controls trace continuation from unknown 3rd party services that happen to be instrumented by a Sentry SDK. +This **MUST** be a boolean value. Default is `false`. This option controls continuation when org identity is incomplete. -If the SDK is able to parse an org ID from the configured DSN, it **MUST** be propagated as a baggage entry with the key `sentry-org_id`. Given a DSN of `https://1234@o1.ingest.us.sentry.io/1`, the org ID is `1`, based on `o1`. +SDKs **MUST** support an optional `orgId: ` setting. If set, `orgId` **MUST** take precedence over org ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). -Additionally, the SDK **MUST** be configurable with an optional `orgId: ` setting that takes precedence over the parsed value from the DSN. This option **SHOULD** be set when running a self-hosted version of Sentry or if a non-standard Sentry DSN is used, such as when using a local Relay. +SDK documentation for the `orgId` option **SHOULD** recommend setting `orgId` for self-hosted Sentry and local Relay deployments. -On incoming traces, the SDK **MUST** compare the `sentry-org_id` baggage value against its own parsed value from the DSN or org setting. Only if both match, the trace is continued. If there is no match, neither the trace ID, the parent sampling decision nor the baggage **SHOULD** be taken into account. The SDK **SHOULD** behave like it is the head of trace in this case. +If the SDK has an org ID (from `orgId` or DSN parsing), it **MUST** propagate that value in baggage as `sentry-org_id`. -This behavior can be disabled by setting `strictTraceContinuation: false` in the SDK init call. Initially, SDKs **MUST** introduce this option with a default value of `false`. Once the majority of SDKs have introduced this option, the default value will change to `true` (in a major version bump), making it opt-out. +On incoming traces, the SDK **MUST** compare incoming `sentry-org_id` with its own org ID: -Regardless of `strictTraceContinuation` being set to `true` or `false`, if the SDK is either configured with an `org` or was able to parse the value from the DSN, incoming traces containing an `org` value in the baggage that does not match the one from the receiving SDK, the trace is not continued. +- If both values are present and differ, the SDK **MUST NOT** continue the trace, regardless of `strictTraceContinuation`. +- If exactly one value is present, the SDK **MUST NOT** continue when `strictTraceContinuation` is `true`, and **SHOULD** continue when it is `false`. +- If both values are present and equal, or both are absent, the SDK **SHOULD** continue the trace. + +When the SDK does not continue a trace, the incoming trace ID, parent sampling decision, and incoming baggage **SHOULD** be ignored. In this case, the SDK **SHOULD** behave as the head of a trace. + +Initially, SDKs **MUST** introduce this option with default `false`. Once the majority of SDKs support this option, the default will change to `true` in a major version, making strict mode opt-out. #### Examples -| Baggage `sentry-org` | SDK `org` | `strictTraceContinuation` | Result | +| Baggage `sentry-org_id` | SDK org ID | `strictTraceContinuation` | Result | | --- | --- | :---: | --- | | 1 | 1 | false | continue trace | | none | 1 | false | continue trace | From fa294ca17192f28486b2b6495bd9d53943d558ae Mon Sep 17 00:00:00 2001 From: Daniel Szoke Date: Thu, 5 Mar 2026 12:34:13 +0100 Subject: [PATCH 2/3] fixup! a bit clearer wording --- develop-docs/sdk/foundations/trace-propagation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index e6724f3ebcf62..73a45935f4b39 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -130,7 +130,7 @@ This option replaces the non-standardized `tracingOrigins` option which was prev ### strictTraceContinuation -This **MUST** be a boolean value. Default is `false`. This option controls continuation when org identity is incomplete. +This **MUST** be a boolean value. Default is `false`. This option controls whether to continue a trace when either the incoming trace or the receiving SDK has an org ID, but not both. SDKs **MUST** support an optional `orgId: ` setting. If set, `orgId` **MUST** take precedence over org ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). From 12a31712ebf50b0e3fc6029310fa87e461f9c8de Mon Sep 17 00:00:00 2001 From: Daniel Szoke Date: Thu, 5 Mar 2026 14:38:03 +0100 Subject: [PATCH 3/3] fixup! Hopefully clearer? --- .../foundations/trace-propagation/index.mdx | 33 ++++++++++++++----- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 73a45935f4b39..6143a290808fd 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -128,17 +128,36 @@ This option replaces the non-standardized `tracingOrigins` option which was prev -### strictTraceContinuation +### Strict Trace Continuation -This **MUST** be a boolean value. Default is `false`. This option controls whether to continue a trace when either the incoming trace or the receiving SDK has an org ID, but not both. +The `strictTraceContinuation` option controls whether to continue a trace when **either the incoming trace or the receiving SDK has an org ID, but not both**. This scenario typically would happen if the incoming trace originates from a third-party service instrumented with Sentry. -SDKs **MUST** support an optional `orgId: ` setting. If set, `orgId` **MUST** take precedence over org ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). +#### Required Configuration Options -SDK documentation for the `orgId` option **SHOULD** recommend setting `orgId` for self-hosted Sentry and local Relay deployments. +SDKs **MUST** support the following configuration options: -If the SDK has an org ID (from `orgId` or DSN parsing), it **MUST** propagate that value in baggage as `sentry-org_id`. +- `strictTraceContinuation`: **MUST** be a boolean value. Default is `false`. +- `orgId`: optional override of the organization ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). + - SDK documentation for the `orgId` option **SHOULD** recommend setting `orgId` for self-hosted Sentry and local Relay setups. -On incoming traces, the SDK **MUST** compare incoming `sentry-org_id` with its own org ID: + + +Once most SDKs support the `strictTraceContinuation` option, we intend to migrate the default value to `true`. As this change is breaking, it will occur in a major. + + + +#### The SDK's Organization ID + +The SDK **MUST** determine its organization ID as follows: +- If `orgId` is present, the SDK's organization ID is the value passed to `orgId`. +- Otherwise, the SDK's organization ID is the organization ID [in the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). +- If `orgId` is absent and the DSN cannot be parsed, then the organization ID is missing. + +If the SDK has an organization ID, the SDK **MUST** propagate the organization ID in baggage as `sentry-org_id`. + +#### Continuing Traces + +On incoming traces, the SDK **MUST** compare the incoming `sentry-org_id` with its own organization ID, as defined above. - If both values are present and differ, the SDK **MUST NOT** continue the trace, regardless of `strictTraceContinuation`. - If exactly one value is present, the SDK **MUST NOT** continue when `strictTraceContinuation` is `true`, and **SHOULD** continue when it is `false`. @@ -146,8 +165,6 @@ On incoming traces, the SDK **MUST** compare incoming `sentry-org_id` with its o When the SDK does not continue a trace, the incoming trace ID, parent sampling decision, and incoming baggage **SHOULD** be ignored. In this case, the SDK **SHOULD** behave as the head of a trace. -Initially, SDKs **MUST** introduce this option with default `false`. Once the majority of SDKs support this option, the default will change to `true` in a major version, making strict mode opt-out. - #### Examples | Baggage `sentry-org_id` | SDK org ID | `strictTraceContinuation` | Result |