Start with the trace boundary
For this architecture worksheet, assume that sending, broker activity, and job execution can occur at separate times and under different active operations. Given that premise, treat message metadata as a designed correlation channel rather than expecting ordinary request parentage to express every relationship.
In OpenTelemetry’s general model, a sender writes context into a carrier and a receiver reads it back; the receiver can then start a span beneath the sending span.
For queued work, direct producer-to-consumer correlation depends on carrying a context created for the message itself, even if the transport already has its own tracing.
Producer-to-consumer trace map
Use this map as an architecture worksheet. The parent-versus-link choice is a design decision at the consumer edge, not a property the queue decides for you.
| Stage | Recommended responsibility | Relationship decision |
|---|---|---|
| Producer | Create send telemetry and inject the job’s correlation metadata before publishing. | Preserve the message-origin context with the payload. |
| Queue or broker | Deliver the payload and metadata according to the chosen protocol. | Do not assume broker activity establishes the application job’s hierarchy. |
| Consumer delivery | Extract, validate, and classify incoming metadata when the application receives the job. | Choose one parent only when that accurately represents the work. |
| Processing | Create receive or processing telemetry around application-visible work. | Otherwise attach a link for every represented message. |
| Settlement | Record acknowledgement, rejection, or similar completion separately when useful. | Links back to message contexts are optional for settlement telemetry. |
A Receive or Process operation may cover one item, many items, or an empty poll. When messages are represented, the messaging guidance calls for a link to the context associated with each message.
Do not create receive or processing telemetry merely because a client library has prefetched an item. Wait until the application is actually given that item.
Choose a relationship model
Make links the baseline for asynchronous consumers. The messaging conventions prefer links because one operation may handle a batch, a message may fan out to multiple consumers, and consumer work can begin while another span is already active.
For a strictly one-job handler, using the message-origin context as the processing span’s parent is an available alternative. If an instrumentation selects that behavior, its documentation should say so, and a setting may be appropriate where deployments need to choose.
A workable policy is: use a parent only for a verified single-message path with no competing ambient operation; use links for batches, fan-out, scheduler-triggered handlers, and uncertain ownership. This is an architectural recommendation based on representational clarity, not a mandate for every client library.
Make the trust boundary explicit
Trace metadata arriving from outside a trusted boundary can be invalid or intentionally fabricated. Decide whether the consumer drops it, cleans it, or accepts it before extracted context can affect local telemetry.
Propagation may include trace and span identifiers as well as baggage. Baggage should not carry secrets, cryptographic material, or personally identifying data because it can cross process boundaries.
Apply the same review on egress: restrict propagation toward destinations where internal trace data should not be revealed. The correct allowlist depends on the queue’s producers, consumers, and any onward routing.
Context checklist for implementation
Use this checklist during design review; it separates required decisions from assumptions about a particular queue client.
- Identify the exact message headers or properties that can hold injected context.
- At consumer delivery, parse metadata and apply the trust policy before choosing parentage or links.
- Define how a single delivery, a batch, an empty poll, retry, and redelivery appear in telemetry.
- Delay receive/process spans until application delivery rather than client-side prefetch.
- Decide whether settlement actions need separate telemetry and optional message-context links.
- Review baggage and outbound destinations for confidentiality exposure.
- Pin the instrumentation and semantic-convention versions used by the implementation.
Limits and alternatives
The messaging semantic conventions are still designated Development. Existing instrumentation that emits version 1.24.0 or earlier is advised not to switch its convention version by default before the conventions stabilize.
Consequently, validate the current specification, the installed instrumentation, and the queue client’s metadata support before locking in field names or emitted span structure. This article does not establish behavior for a specific broker, SDK, retry policy, or instrumentation package.
For asynchronous or aggregated work, links can preserve relationships to several message contexts where parentage allows only one. A team might still choose a parent for a single-message path when that presentation matches its operating model. A hybrid is another design option, but it needs an explicit rule so operators know how to read the resulting traces.