diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 29935c3ee890f..01f99c1d95551 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`. + +