Skip to content

📝 Document baggage propagation behavior on receive - #8519

Draft
ramonsmits wants to merge 2 commits into
otel-docsfrom
otel-docs-baggage
Draft

ramonsmits wants to merge 2 commits into
otel-docsfrom
otel-docs-baggage

Conversation

@ramonsmits

@ramonsmits ramonsmits commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

Stacked on #8443. Documents the receive-side baggage behavior introduced on the NServiceBus otel branch (Particular/NServiceBus#7954).

What is documented

  • NServiceBus writes the current activity's baggage to the baggage header and applies it to the process span on receive, on every transport.
  • Baggage and tracestate are read only from messages that also carry NServiceBus.TraceParent or traceparent.
  • Baggage is applied even when a transport SDK receive span is the parent of the process span, because the Azure Service Bus, RabbitMQ, and Amazon SQS clients do not propagate baggage. A key the SDK span already carries is not added again.
  • Baggage follows the message, not the trace: it is applied also when the receiver starts a new trace.
  • Usage guidance: small cross-cutting values only, never removed along a conversation, reaches every receiver including audit and error queues, W3C limits are not enforced.

Files

  • nservicebus/operations/opentelemetry_traces_core_[10,11).partial.md and [11,).partial.md: new Baggage subsection under Context propagation.
  • nservicebus/messaging/headers.md: annotate the baggage header, add the receive-side rule for 10.3 and later, and remove a stray empty list item.

Describes how NServiceBus applies the baggage header to the process span:
only together with NServiceBus trace context, also when a transport SDK
receive span is the parent (the Azure Service Bus, RabbitMQ, and Amazon
SQS clients do not propagate baggage), without re-adding a key the SDK
span already carries, and regardless of whether a new trace is started.
Adds usage guidance and clarifies the baggage header on the headers page.
…ry Baggage API

Activity.Baggage and OpenTelemetry.Baggage are separate stores. Neither one
reads the other. A user who sets baggage through the OpenTelemetry API gets no
baggage header on the message, because NServiceBus reads Activity.Baggage.

Links the community OpenTelemetry .NET instrumentation reference for the
difference between the two APIs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant