From 6e416e10bc9c53556edbd177119756caa2d7a4f5 Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Fri, 16 Oct 2026 09:04:08 +0200 Subject: [PATCH 1/5] docs(span-links): Add `message_origin` link type for queues Co-Authored-By: Claude Opus 5.5 --- .../sdk/telemetry/traces/span-links.mdx | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) 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. From 3deed2ff1509dd0e7c4d60c2a867536af0bda5b4 Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Wed, 21 Oct 2026 10:36:54 +0200 Subject: [PATCH 2/5] fixup! docs(span-links): Add `message_origin` link type for queues --- develop-docs/sdk/telemetry/traces/span-links.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/span-links.mdx b/develop-docs/sdk/telemetry/traces/span-links.mdx index 4bd65657c8ce2..2c710fe2eea1e 100644 --- a/develop-docs/sdk/telemetry/traces/span-links.mdx +++ b/develop-docs/sdk/telemetry/traces/span-links.mdx @@ -213,9 +213,9 @@ A background revalidation (for example, stale-while-revalidate) starts its own t ### `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. +When a consumer processes a message, the work often runs long after the producer published it, in another process, and with a different sampling decision. +A parent/child relationship does not fit well: a delayed or retried job keeps the producer trace open for a long time, one publish span can fan out to many consumers, and a batch can contain messages from unrelated traces, so it has no single correct parent. +If the consumer starts its own trace, then without a link, the consumer trace has no way to find the code that published the message. 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. From 3b673156758c8b1b05b6219c8157e62fdaea5494 Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Wed, 21 Oct 2026 10:36:55 +0200 Subject: [PATCH 3/5] fixup! docs(span-links): Add `message_origin` link type for queues --- develop-docs/sdk/telemetry/traces/span-links.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/develop-docs/sdk/telemetry/traces/span-links.mdx b/develop-docs/sdk/telemetry/traces/span-links.mdx index 2c710fe2eea1e..6c9970e45a593 100644 --- a/develop-docs/sdk/telemetry/traces/span-links.mdx +++ b/develop-docs/sdk/telemetry/traces/span-links.mdx @@ -217,6 +217,10 @@ When a consumer processes a message, the work often runs long after the producer A parent/child relationship does not fit well: a delayed or retried job keeps the producer trace open for a long time, one publish span can fan out to many consumers, and a batch can contain messages from unrelated traces, so it has no single correct parent. If the consumer starts its own trace, then without a link, the consumer trace has no way to find the code that published the message. +The [Queues module](/sdk/telemetry/traces/modules/queues/#distributed-tracing) continues the producer trace in the consumer where it can. +For the cases above, start a new trace in the consumer and add a `message_origin` link instead. +If the consumer continues the producer trace, do not add the link, because it would point into the same trace. + 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: From 004df77a862127e3ca942280075ed48ae645dce0 Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Wed, 21 Oct 2026 10:36:55 +0200 Subject: [PATCH 4/5] fixup! docs(span-links): Add `message_origin` link type for queues --- develop-docs/sdk/telemetry/traces/span-links.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/span-links.mdx b/develop-docs/sdk/telemetry/traces/span-links.mdx index 6c9970e45a593..6d407d57f2141 100644 --- a/develop-docs/sdk/telemetry/traces/span-links.mdx +++ b/develop-docs/sdk/telemetry/traces/span-links.mdx @@ -234,7 +234,7 @@ span.addLink({ }) ``` -- On publish, store the current span context (`trace_id`, `span_id`, sampling decision) with the message, for example in message metadata or headers. +- On publish, store the context of the publish span (for example, the `queue.publish` span: `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. From ba2727896253359f86dcf2c4b09cb946e706432b Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Wed, 21 Oct 2026 10:36:56 +0200 Subject: [PATCH 5/5] fixup! docs(span-links): Add `message_origin` link type for queues --- develop-docs/sdk/telemetry/traces/span-links.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/span-links.mdx b/develop-docs/sdk/telemetry/traces/span-links.mdx index 6d407d57f2141..4f677b0657297 100644 --- a/develop-docs/sdk/telemetry/traces/span-links.mdx +++ b/develop-docs/sdk/telemetry/traces/span-links.mdx @@ -235,7 +235,7 @@ span.addLink({ ``` - On publish, store the context of the publish span (for example, the `queue.publish` span: `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. +- On process, read the stored context and add the link. A span that processes a batch adds one link for each distinct producer span in the batch. - 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`).