Skip to content

docs(sdk): Adjust and clarify strict trace continuation spec #18744

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 1 commit into
base: master
Choose a base branch
from
Open

docs(sdk): Adjust and clarify strict trace continuation spec #18744

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
92 changes: 58 additions & 34 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 @@ -2,14 +2,17 @@
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
version: ">=1.0.0"
- 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
Comment on lines +5 to +15

@szokeasaurusrex szokeasaurusrex Jul 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

The clanker added these changes, is it necessary to write this manually, or is there some automation to update the changelog here?

- version: 1.9.0
date: 2026-02-24
summary: Consolidated into foundations/trace-propagation
Expand Down Expand Up @@ -126,59 +129,80 @@ This option replaces the non-standardized `tracingOrigins` option which was prev

</SpecSection>

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

### Strict Trace Continuation
<SpecSection id="trace-continuation" status="stable" since="1.10.0">

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.

<Alert level="info">

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.

</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 `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 |
</SpecSection>

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

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

<Alert level="info">

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.

</Alert>

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

@sentry sentry Bot Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Bug: The strict-trace-continuation spec changes behavior but retains the since="1.3.0" tag, creating ambiguity about when the behavior changed and what is expected.
Severity: MEDIUM

Suggested Fix

Clarify in the changelog and the specification that the behavior for strictTraceContinuation=true (when the SDK has no organization ID) changed between v1.3.0 and v1.10.0. Provide clear migration guidance for SDK authors. Consider updating the since tag or adding a note about the version in which the behavior was changed to "unspecified".

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: develop-docs/sdk/foundations/trace-propagation/index.mdx#L198

Potential issue: The specification for `strictTraceContinuation` has been updated to
mark certain behaviors as "unspecified". However, the documentation retains the
`since="1.3.0"` version tag, even though the behavior defined in v1.3.0 has been altered
in this new version (v1.10.0). This creates a specification drift, making it unclear to
SDK implementers that the behavior has changed. Existing SDKs following the v1.3.0 spec
may now be technically non-compliant, and new implementers may be confused about
backward compatibility expectations.

Did we get this right? 👍 / 👎 to inform future reviews.

| any | none | ✅ Continue trace | ❓ Unspecified |

<Alert level="info">

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

</Alert>

</SpecSection>

Expand Down
Loading