docs(trace-propagation): Clarify strict trace continuation rules#16793
docs(trace-propagation): Clarify strict trace continuation rules#16793szokeasaurusrex merged 10 commits intomasterfrom
Conversation
Clarify which strictTraceContinuation requirements always apply and which depend on the option value. Define incoming org ID comparison outcomes by case so continuation behavior is explicit and matches the examples. Keep behavior unchanged while tightening wording. Replace the inline DSN parsing example with a link to the DSN parsing spec, and add a maintainer requirement that SDK docs for orgId recommend setting orgId for self-hosted and local Relay deployments.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
stephanie-anderson
left a comment
stephanie-anderson
left a comment
There was a problem hiding this comment.
I think this is over optimized for LLMs and makes reading it harder for humans. Especially the context that we wanna avoid 3rd party traces to be continued is super important information, that is deleted with this PR.
|
@stephanie-anderson Besides the 3rd party traces removal, which I am happy to add back, what exactly makes this spec now harder for you to read? I opened this PR because I found it difficult to understand the spec as originally written. I find this suggestion to be easier to understand, as it is a bit more concise, and also I think the bulleted list is a bit better. Though, I will admit it still is not super human friendly. It was not at all my intention to optimize for LLMs above humans here 😂 I am trying to optimize for human understandability 😄 |
|
I tried to improve readability by splitting stuff out into subsections. I find this easier to understand, and I especially find it easier to quickly skim which combinations of incoming and SDK's own org IDs result in continuing vs not continuing the trace, and how this all depends on the Also I added back the note about third-party services 😄 What do you think? |
|
@szokeasaurusrex thanks! I'll have a look in a bit - how time sensitive is this? |
Not time sensitive. I just found it difficult to understand the docs as I was reviewing the PR @giortzisg opened for the Rust SDK, and wanted to see if I could make them a bit easier to understand 😄 |
stephanie-anderson
requested review from
stephanie-anderson
and removed request for
stephanie-anderson
| ### 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. |
There was a problem hiding this comment.
| 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. | |
| The `strictTraceContinuation` option controls whether to continue a trace when only one side of a trace has an org ID (**either the incoming trace or the receiving SDK but not both**.) This commonly occurs when an incoming trace originates from a third-party service instrumented with Sentry. |
There was a problem hiding this comment.
This seems a bit vaguer to me than what I already have written
|
|
||
| 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). |
There was a problem hiding this comment.
| - `orgId`: optional override of the organization ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). | |
| - `orgId`: optional override of the org ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). |
coolguyzone
left a comment
coolguyzone
left a comment
There was a problem hiding this comment.
LGTM, thanks for clarifying!
Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
stephanie-anderson
left a comment
stephanie-anderson
left a comment
There was a problem hiding this comment.
Thank you, @szokeasaurusrex!
szokeasaurusrex
deleted the
szokeasaurusrex/fix-strict-trace-continuation
branch
) ## DESCRIBE YOUR PR This PR clarifies the [`strictTraceContinuation` specification](https://develop.sentry.dev/sdk/foundations/trace-propagation/#stricttracecontinuation) wording. I found the original version difficult to understand, and it was also unclear which parts of the spec depended on the `strictTraceContinuation` value, and which did not. [Link to preview. ](https://develop-docs-git-szokeasaurusrex-fix-strict-trace-continuation.sentry.dev/sdk/foundations/trace-propagation/#strict-trace-continuation) ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): - [ ] Other deadline: - [x] None: Not urgent, can wait up to 1 week+ --------- Co-authored-by: Stephanie Anderson <stephanie.anderson@sentry.io> Co-authored-by: Johannes Daxböck <johannes.daxboeck@sentry.io> Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
4 participants
DESCRIBE YOUR PR
This PR clarifies the
strictTraceContinuationspecification wording. I found the original version difficult to understand, and it was also unclear which parts of the spec depended on thestrictTraceContinuationvalue, and which did not.Link to preview.
IS YOUR CHANGE URGENT?