docs(span-links): Add develop docs for span links #12829
Merged
Conversation
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
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
2 Skipped Deployments
|
6 tasks
Lms24
approved these changes
Feb 25, 2025
| --- | ||
|
|
||
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. It's also useful in settings with producer/consumer patterns. | ||
| We are able to display a user journey in our tracing views to make debugging of issues easier as developers get more context on what happened before a specific issue. |
There was a problem hiding this comment.
l:
Suggested change
| We are able to display a user journey in our tracing views to make debugging of issues easier as developers get more context on what happened before a specific issue. | |
| By using span links, we are able to display a user journey in our tracing views to make debugging of issues easier as developers get more context on what happened before a specific issue. |
|
|
||
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. It's also useful in settings with producer/consumer patterns. | ||
| We are able to display a user journey in our tracing views to make debugging of issues easier as developers get more context on what happened before a specific issue. | ||
| Without somehow linking spans together, we are limited to the duration of one trace (id), which is handled differently and kept alive for different times across our various SDKs. |
There was a problem hiding this comment.
l: I would omit this from the intro as this already is quite specific towards previous/next trace links. I'd rather keep the intro short and more general.
Suggested change
| Without somehow linking spans together, we are limited to the duration of one trace (id), which is handled differently and kept alive for different times across our various SDKs. |
| title: Span Links | ||
| --- | ||
|
|
||
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. It's also useful in settings with producer/consumer patterns. |
There was a problem hiding this comment.
l: slight wording correction and added one more example
Suggested change
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. It's also useful in settings with producer/consumer patterns. | |
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. They're also useful in settings with producer/consumer patterns or batch operations. |
| ### Type Definitions | ||
|
|
||
| SDKs should follow the OpenTelemetry spec for the Link interface as defined by the platform. | ||
| Non-OTel SDKs should orient themselves on OTel, resulting in the following interface: |
There was a problem hiding this comment.
Suggested change
| Non-OTel SDKs should orient themselves on OTel, resulting in the following interface: | |
| Non-OTel SDKs should orient themselves on OTel, resulting in the following interface, or a related version that applies to the terminology and philosophy of the respective SDK: |
Comment on lines
+60
to
+61
| ``` | ||
|
|
There was a problem hiding this comment.
l: let's add a sentence for non-Potel/Span-centric SDKs
Suggested change
| ``` | |
| SDKs that don't offer span-centric APIs but e.g. transaction APIs, should ensure that their respective start APIs (e.g. `startTransaction`) also offers a possibility to add links. |
There was a problem hiding this comment.
I added this in line 52 :)
|
|
||
|
|
||
|
|
||
| #### Dealing with Negative Sample Rates |
There was a problem hiding this comment.
l: Did you want to write something here or was this a leftover?
Suggested change
| #### Dealing with Negative Sample Rates |
There was a problem hiding this comment.
This is a leftover. This is covered in Negatively Sampled Traces
|
|
||
| Optionally, the serialized link object can contain further fields from OTel like `traceState`, `isRemote` or `droppedAttributesCount` which will be just forwarded unless we find a use case for them. | ||
|
|
||
| The OTel fields `spanId`, `traceId`, and `traceFlags` should be excluded from the links objects in the envelope to avoid duplicate data (e.g. `trace_id`). |
There was a problem hiding this comment.
l: just to make it a bit more obvious:
Suggested change
| The OTel fields `spanId`, `traceId`, and `traceFlags` should be excluded from the links objects in the envelope to avoid duplicate data (e.g. `trace_id`). | |
| The OTel fields `spanId`, `traceId`, and `traceFlags` should be excluded from the links objects in the envelope to avoid duplicate data (e.g. `trace_id` vs. `traceId`). |
|
|
||
| ## Link Types | ||
|
|
||
| Links don't require a special meaning or type. When necessary, use the "sentry.link.type" attribute on the link to define the link type. |
There was a problem hiding this comment.
l: wdyt about this? Just a slight rewording to make the intention more clear of the sentry.link.type attribute:
Suggested change
| Links don't require a special meaning or type. When necessary, use the "sentry.link.type" attribute on the link to define the link type. | |
| Links don't require a special meaning or type but if necessary (e.g. for identifying special links in the product), set the `sentry.link.type` attribute on the link to define the link type. |
Comment on lines
214
to
221
| ## Ingest/Relay | ||
|
|
||
| Relay should forward the span links in the format that is required for further processing and storage. | ||
| Importantly, we must not require span links to be defined. They are completely optional. | ||
|
|
||
| As a further requirement, Relay needs to handle passing along span links in the root span as well as in any child span (see [envelope item payload](#envelope-item-payload)). | ||
|
|
||
| The expected type and structure of the links array and its contents is specified in Relay. This further includes specifying the type of the sentry.link.type attribute value to be a string. |
There was a problem hiding this comment.
l: I reworded this to state what Relay currently does as opposed to what it should, as we already defined this in Relay. Since we mention that the schema is specified, I also added a link to it.
Suggested change
| ## Ingest/Relay | |
| Relay should forward the span links in the format that is required for further processing and storage. | |
| Importantly, we must not require span links to be defined. They are completely optional. | |
| As a further requirement, Relay needs to handle passing along span links in the root span as well as in any child span (see [envelope item payload](#envelope-item-payload)). | |
| The expected type and structure of the links array and its contents is specified in Relay. This further includes specifying the type of the sentry.link.type attribute value to be a string. | |
| ## Ingest/Relay | |
| Relay forwards the span links in the format that is required for further processing and storage. | |
| Importantly, Relay doesn't require span links to be defined. They are completely optional. | |
| Relay handles passing span links in the root span as well as in any child span (see [envelope item payload](#envelope-item-payload)). | |
| The expected type and structure of the links array and its contents is [specified in Relay](https://github.com/getsentry/relay/blob/master/relay-event-schema/src/protocol/span.rs#L753). |
coolguyzone
reviewed
Feb 25, 2025
| title: Span Links | ||
| --- | ||
|
|
||
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. It's also useful in settings with producer/consumer patterns. |
There was a problem hiding this comment.
Suggested change
| Span links associate one span with one or more spans. The most important application of linking traces are frontend applications. It's also useful in settings with producer/consumer patterns. | |
| Span links associate one span with one or more other spans. This is mostly useful in frontend applications; it can also be useful in settings with producer/consumer patterns. |
coolguyzone
reviewed
Feb 25, 2025
| - Links are added on a span level, as defined and specified by [OpenTelemetry](https://opentelemetry.io/docs/specs/otel/trace/api/#link). | ||
| - In addition to linking to span IDs, a span link also holds meta information about the link, collected via attributes. | ||
| - Span links MUST only link to other spans. We do not support linking a span to an error or other Sentry events. | ||
| - For SDKs still having public APIs around transactions, their respective Transaction interface and `startTransaction` function(s) should support the same APIs |
There was a problem hiding this comment.
Suggested change
| - For SDKs still having public APIs around transactions, their respective Transaction interface and `startTransaction` function(s) should support the same APIs | |
| - For SDKs still having public APIs around transactions, their respective Transaction interface and `startTransaction` function(s) should support the same APIs. |
codyde
added a commit
that referenced
this pull request
Feb 27, 2025
* master: (45 commits) feat: Mention that the cookie-sync extension works for previews (#12858) ref(flags): update unleashIntegration param (#12795) ref(sveltekit): Adjust Cloudflare setup to only use SvelteKit SDK (#12801) docs(python): Clarify how to init SDK in `async` app (#12854) move content about error capturing to "Capturing Errors and Events" from "Manual Setup" (Next.js) (#12786) docs(span-links): Add develop docs for span links (#12829) feat(java): add Reactor integration docs (#12686) Add Quarkus to community maintained SDKs (#12834) Adding unsupported hot reload (#12683) Fix broken links (#12844) feat(python): Clarification regarding start_transaction (#12835) docs(flutter): Fix event serverName reset in samples (#12832) ref(insights): move performance docs under insights (#12720) Bump API schema to 2e61347a (#12836) fix(apple): Usages of sendDefaultPii (#12833) Add `sendDefaultPii: true` to React Native init code snippets (#12812) Only show Browser vs React Native source maps alert for browser sdks (#12816) Add Data Collected page for React Native (#12811) Fix React Native Onboarding Option Buttons (#12813) Add Hono guide (#12710) ...
limbonaut
pushed a commit
that referenced
this pull request
Feb 28, 2025
* docs(span-links): Add develop docs for span links * review suggestions
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
DESCRIBE YOUR PR
Adds develop docs for span links based on this RFC: https://github.com/getsentry/rfcs/blob/main/text/0141-linking-traces.md
Rendered docs: https://develop-docs-gvlk6i9b9.sentry.dev/sdk/telemetry/traces/span-links/
Tracking issue: getsentry/sentry-javascript#14991
IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes: