docs(sdk): Adjust and clarify strict trace continuation spec#18744
Open
szokeasaurusrex wants to merge 1 commit into
Open
docs(sdk): Adjust and clarify strict trace continuation spec#18744szokeasaurusrex wants to merge 1 commit into
szokeasaurusrex wants to merge 1 commit into
Conversation
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)
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
szokeasaurusrex
commented
Jul 16, 2026
Comment on lines
+5
to
+15
| 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 |
Member
Author
There was a problem hiding this comment.
The clanker added these changes, is it necessary to write this manually, or is there some automation to update the changelog here?
szokeasaurusrex
changed the title
szokeasaurusrex
marked this pull request as ready for review
July 22, 2026 16:25
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
| | --- | --- | --- | --- | | ||
| | `1` | `1` | ✅ Continue trace | ✅ Continue trace | | ||
| | none | `1` | ✅ Continue trace | ❌ Start new trace | | ||
| | `1` | `2` | ❌ Start new trace | ❌ Start new trace | |
Contributor
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
Tip
View the relevant portion of the docs preview.
Resolves SDK-1365