From 3c07c99747b5567500d6c44886928324ae223c62 Mon Sep 17 00:00:00 2001 From: "Daniel Szoke (via Pi Coding Agent)" Date: Thu, 16 Jul 2026 11:36:44 +0200 Subject: [PATCH] docs(sdk): Clarify strict trace continuation requirements This PR proposes clarifying strict trace continuation so its behavior is only specified when the SDK knows its own organization ID. When both the SDK and incoming trace lack an organization ID, the trace may have come from a poorly configured or older third-party SDK, not the same organization. Strict trace continuation therefore has no useful defined behavior without SDK organization awareness. Users who enable the option likely intend to verify the trace's organization, so SDKs should warn when the organization ID is missing and may prevent that configuration where appropriate. Separate the baseline organization-ID continuation rules from strict trace continuation. The default rules continue traces unless both known organization IDs differ; strict mode additionally rejects traces that omit an organization ID when the SDK has one. Keeping these concepts separate makes the specification easier to reason about and avoids treating an SDK without organization awareness as a valid strict-continuation use case. Resolves [SDK-1365](https://linear.app/getsentry/issue/SDK-1365/update-develop-docs-for-strict-trace-continuation-proposal) --- .../foundations/trace-propagation/index.mdx | 92 ++++++++++++------- 1 file changed, 58 insertions(+), 34 deletions(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 29935c3ee890f6..01f99c1d95551e 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -2,7 +2,7 @@ title: Trace Propagation description: How SDKs propagate trace context between services via headers, metadata, and environment variables. spec_id: sdk/foundations/trace-propagation -spec_version: 1.9.0 +spec_version: 1.10.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/state-management/scopes version: ">=1.0.0" spec_changelog: + - version: 1.10.0 + date: 2026-07-16 + summary: Clarified trace continuation and strict trace continuation behavior - version: 1.9.0 date: 2026-02-24 summary: Consolidated into foundations/trace-propagation @@ -126,59 +129,80 @@ This option replaces the non-standardized `tracingOrigins` option which was prev - - -### Strict Trace Continuation + -The `strictTraceContinuation` option controls whether to continue a trace when **either the incoming trace or the receiving SDK has an organization ID, but not both**. This scenario typically would happen if the incoming trace originates from a third-party service instrumented with Sentry. - -#### Required Configuration Options +### Trace Continuation SDKs **MUST** support the following configuration options: -- `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. - - -Once most SDKs support the `strictTraceContinuation` option, we intend to migrate the default value to `true`. As this change is breaking, it will be part of a major release. - - - #### 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 `orgId` is absent and the DSN cannot be parsed, the SDK 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 +When the SDK organization ID is missing, SDKs **MAY** warn users and recommend configuring `orgId`. + +#### Default Continuation Behavior -On incoming traces, the SDK **MUST** compare the incoming `sentry-org_id` with its own organization ID, as defined above. +On incoming traces, the SDK **MUST** compare the incoming `sentry-org_id` with its own organization ID. -- 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. +- If both values are present and differ, the SDK **MUST NOT** continue the trace. +- In all other cases, the SDK **SHOULD** continue the trace. + +| Incoming `sentry-org_id` | SDK organization ID | Result | +| --- | --- | --- | +| `1` | `1` | ✅ Continue trace | +| none | `1` | ✅ Continue trace | +| `1` | `2` | ❌ Start new trace | +| any | none | ✅ Continue 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. -#### Examples - -| Baggage `sentry-org_id` | SDK organization ID | `strictTraceContinuation` | Result | -| --- | --- | :---: | --- | -| 1 | 1 | false | continue trace | -| none | 1 | false | continue trace | -| 1 | none | false | continue trace | -| none | none | false | continue trace | -| 1 | 2 | false | start new trace | -| 1 | 1 | true | continue trace | -| none | 1 | true | start new trace | -| 1 | none | true | start new trace | -| none | none | true | continue trace | -| 1 | 2 | true | start new trace | + + + + +### Strict Trace Continuation + +The `strictTraceContinuation` option makes trace continuation stricter when the SDK has an organization ID. With strict trace continuation enabled, the SDK **MUST NOT** continue an incoming trace unless its `sentry-org_id` matches the SDK organization ID. + + + +Strict trace continuation changes the default continuation behavior when the SDK has an organization ID but the incoming trace does not. A matching organization ID always allows continuation, and differing organization IDs always prevent continuation. + + + +`strictTraceContinuation` **MUST** be a boolean value. The default is `false`. + +When `strictTraceContinuation` is `true` and the SDK has an organization ID: + +- If the incoming `sentry-org_id` matches the SDK organization ID, the SDK **SHOULD** continue the trace. +- If the incoming `sentry-org_id` is missing or differs from the SDK organization ID, the SDK **MUST NOT** continue the trace. + +When `strictTraceContinuation` is `true` but the SDK organization ID is missing, trace continuation behavior is unspecified. SDKs **SHOULD** warn users about this configuration. SDKs **MAY** prevent users from enabling `strictTraceContinuation` without an organization ID in a platform-appropriate way. + +The following table compares the default trace continuation behavior (with `strictTraceContinuation` set to `false`) against the strict trace continuation behavior. + +| Incoming `sentry-org_id` | SDK organization ID | Default Trace Continuation | Strict Trace Continuation | +| --- | --- | --- | --- | +| `1` | `1` | ✅ Continue trace | ✅ Continue trace | +| none | `1` | ✅ Continue trace | ❌ Start new trace | +| `1` | `2` | ❌ Start new trace | ❌ Start new trace | +| any | none | ✅ Continue trace | ❓ Unspecified | + + + +Once most SDKs support the `strictTraceContinuation` option, we intend to migrate the default value to `true`. As this change is breaking, it will be part of a major release. When this default changes, SDKs **SHOULD** warn users if the SDK organization ID is missing and recommend configuring `orgId`. + +