diff --git a/develop-docs/sdk/telemetry/traces/span-links.mdx b/develop-docs/sdk/telemetry/traces/span-links.mdx index 5fca4c0d459bd..4bd65657c8ce2 100644 --- a/develop-docs/sdk/telemetry/traces/span-links.mdx +++ b/develop-docs/sdk/telemetry/traces/span-links.mdx @@ -148,6 +148,7 @@ Any string can be used, but these types have predefined meanings: | "previous_trace" | Linking e.g. a navigation span to the previous page load span. | Used to query linked traces. Shows a button to go to linked previous trace in the trace explorer. | | "next_trace" | Linking e.g. a page load span to the next navigation span. | Used to query linked traces. Shows a button to go to linked next trace in the trace explorer. | | "cache_origin" | Linking a span that reads a cached value to the trace that produced that value (e.g. server-side rendering). | Used to navigate from a cache-hit span to the origin trace. | +| "message_origin" | Linking a span that processes a queue message to the span that published the message (e.g. a queue job). | Used to navigate from a consumer span to the producer trace. | ### `previous_trace` @@ -210,6 +211,31 @@ The origin trace may be negatively sampled. The link is still added, with `sampl A background revalidation (for example, stale-while-revalidate) starts its own trace rather than continuing the serving trace, and becomes the origin for future cache hits. +### `message_origin` + +When a consumer processes a message from a queue, the producer that published the message ran in an earlier trace, often in another process and with a different sampling decision. +If the consumer starts its own trace instead of continuing the producer's trace, then without a link, the consumer trace has no way to find the code that published the message. +One producer trace can also publish messages for many consumers. + +A `message_origin` link connects the span that processes a message (for example, a `queue.process` span) to the span that published it (for example, a `queue.publish` span). "Origin" here means the producer span, not the consumer. + +Add the link to the span that processes the message: + +```ts +span.addLink({ + context: producerSpanContext, // propagated with the message + attributes: { + 'sentry.link.type': 'message_origin' + } +}) +``` + +- On publish, store the current span context (`trace_id`, `span_id`, sampling decision) with the message, for example in message metadata or headers. +- On process, read the stored context and add the link. Each consumer span carries one `message_origin` link. +- If the message has no stored context, emit the consumer span **without** a link. + +The producer trace may be negatively sampled. The link is still added, with `sampled: false` from the stored span context (same behavior as `previous_trace`). + ## Usage Example Adding span links should be possible at span start time, as well as when holding a reference to the span.