Skip to content

docs(trace-propagation): Clarify strict trace continuation rules #16793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
szokeasaurusrex wants to merge 5 commits into
base: master
Choose a base branch
from
+31 −8
Open

docs(trace-propagation): Clarify strict trace continuation rules #16793

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
28080fb
docs(trace-propagation): Clarify strict trace continuation rules
szokeasaurusrex Mar 5, 2026
fa294ca
fixup! a bit clearer wording
szokeasaurusrex Mar 5, 2026
12a3171
fixup! Hopefully clearer?
szokeasaurusrex Mar 5, 2026
5f6174e
Merge branch 'master' into szokeasaurusrex/fix-strict-trace-continuation
stephanie-anderson Mar 5, 2026
40c2965
Merge branch 'master' into szokeasaurusrex/fix-strict-trace-continuation
dingsdax Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 31 additions & 8 deletions develop-docs/sdk/foundations/trace-propagation/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,23 +128,46 @@ This option replaces the non-standardized `tracingOrigins` option which was prev

<SpecSection id="strict-trace-continuation" status="stable" since="1.3.0">

### strictTraceContinuation
### Strict Trace Continuation

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.
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.

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`.
#### Required Configuration Options

Additionally, the SDK **MUST** be configurable with an optional `orgId: <org-id>` 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.
SDKs **MUST** support the following configuration options:

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.
- `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.

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.
<Alert level="info">

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.
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.

</Alert>

#### 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`.
- If both values are present and equal, or both are absent, the SDK **SHOULD** continue the trace.
Copy link
Member Author

@szokeasaurusrex szokeasaurusrex Mar 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the "or both are absent" part correct?

The original spec was a bit unclear on this point. However, the examples in the table indicate that traces should be continued when both org IDs are absent, which is why I included this line.


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` | SDK `org` | `strictTraceContinuation` | Result |
| Baggage `sentry-org_id` | SDK org ID | `strictTraceContinuation` | Result |
| --- | --- | :---: | --- |
| 1 | 1 | false | continue trace |
| none | 1 | false | continue trace |
Expand Down
Loading