OpenTelemetry Baggage

In this lesson we cover OpenTelemetry Baggage: what it is, how it differs from span attributes, common use cases, code examples for setting and reading baggage, and security and best-practice guidance. Baggage is a small set of contextual key-value pairs that travel with requests across service boundaries via headers. Downstream services can read those keys to enable business-level routing, personalization, or to copy values into span attributes for observability.

Observability signals — quick recap

Signal	Purpose	Typical examples
Traces	End-to-end execution paths for requests	Request spans, latency
Metrics	Aggregated numeric measurements	CPU, throughput, error rates
Logs	Event-level diagnostic messages	Exceptions, debug events
Baggage	Small contextual metadata propagated across services	`user_id`, `cart_id`, `promo_code`

Baggage commonly carries non-sensitive values such as user_id (non-identifying), region, tier=gold, product_id, cart_id, or promotion codes like SUMMER10. A frontend service can capture a promo code and propagate it so downstream services can use it for personalized messaging or business logic.

Baggage vs. span attributes

Baggage: propagated across services using request headers (W3C Baggage format). It is intended to be read by all services that participate in context propagation.
Span attributes: local to a span and used to enrich trace data for that single span. They are stored in your observability backend but are not automatically forwarded downstream.

The image compares "Baggage" and "Span Attributes," showing how product ID, cart ID, and promo code are represented in HTTP request headers and span attributes, with similar values formatted differently in each context.

Span attributes are visible in tracing backends but not automatically propagated. If downstream services need specific values (for example, to send a promotional email), propagate them via baggage headers; the downstream service may decide to copy those values into span attributes for observability or use them in application logic. The diagram below shows baggage being set in Service A, flowing via headers through Service B, and being consumed or copied into span attributes in Service C.

The image depicts a diagram illustrating "Baggage in Action" within a microservices architecture, showing the flow of request context and attributes between Service A, Service B, and Service C.

Python example — set baggage and inject into outgoing headers

Steps:

Use the baggage API to set key-value pairs into a context.
Use the propagation API to inject the context into outgoing HTTP headers.

from opentelemetry import baggage, propagate

# start from an existing context (None is acceptable)
ctx = None
ctx = baggage.set_baggage("product_id", "SKU-12345", context=ctx)
ctx = baggage.set_baggage("cart_id", "cart-42", context=ctx)
ctx = baggage.set_baggage("promo_code", "SUMMER10", context=ctx)

# Inject baggage into outgoing HTTP headers (carrier is a dict here)
headers = {}
propagate.inject(headers, context=ctx)
# headers now contains a W3C Baggage header like:
# baggage: product_id=SKU-12345,cart_id=cart-42,promo_code=SUMMER10

Python example — extract baggage from incoming headers and copy into span attributes

On the receiving side, extract the context from incoming headers, read baggage values, and optionally copy them into span attributes for better observability.

from opentelemetry import baggage, propagate, trace

# incoming request headers (a dict-like carrier)
headers = {
    # e.g. 'baggage': 'product_id=SKU-12345,cart_id=cart-42,promo_code=SUMMER10'
}

# Extract context from incoming headers
ctx = propagate.extract(headers)

# Read baggage values from the extracted context
product = baggage.get_baggage("product_id", context=ctx)
cart = baggage.get_baggage("cart_id", context=ctx)
promo = baggage.get_baggage("promo_code", context=ctx)

# Copy baggage into a span for observability or use in business logic
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("downstream.process", context=ctx) as span:
    span.set_attribute("commerce.product.id", product or "")
    span.set_attribute("commerce.cart.id", cart or "")
    span.set_attribute("commerce.promo.code", promo or "")

Resulting span attributes (example):

{
  "commerce.product.id": "SKU-12345",
  "commerce.cart.id": "cart-42",
  "commerce.promo.code": "SUMMER10"
}

Once a downstream service has the promo code in its context, it can trigger actions (for example, send an email that references the promo code) or propagate the baggage further downstream.

Real-world use cases

Category	Example baggage keys	Purpose
Correlation	`correlation_id`	Link related business operations across services (distinct from trace ID)
Commerce	`cart_id`, `product_id`, `transaction_id`	Route or enrich commerce flows
Routing / Personalization	`region`, `origin`, `tier`	Use for routing decisions or personalized responses
Analytics	`non-identifying_user_attr`	Aggregate business metrics without exposing PII

Security considerations

Baggage travels in HTTP headers and is visible to every intermediate and downstream service. Because baggage does not provide integrity or confidentiality guarantees by default:

Values can be modified or tampered with by intermediaries.
Sensitive data can be exposed if baggage leaves trusted networks.
Avoid putting PII, credentials, tokens, or sensitive secrets into baggage.

Baggage is not a secure transport. Avoid putting sensitive or identifying data in baggage, and exercise caution when propagating baggage beyond trusted boundaries.

The image lists security considerations regarding baggage, highlighting issues like visibility via headers, lack of integrity checks, risk of sensitive data exposure, and the need for caution beyond trusted boundaries.

Best practices

Keep baggage small to limit header size and avoid network overhead.
Standardize key names and conventions across teams to reduce collisions and simplify downstream processing.
Never include PII, credentials, or tokens in baggage.
Monitor performance and header sizes when enabling baggage propagation.

Define a small, consistent set of baggage keys and document their intended use. This keeps cross-team usage predictable and reduces the risk of accidental sensitive data propagation.

The image lists three best practices: keeping baggage small, standardizing keys for consistency, and avoiding sensitive data, accompanied by relevant icons. There's also a thumbs-up badge illustration.

Key takeaways

Baggage carries small contextual metadata along with requests and complements traces, metrics, and logs.
Use baggage to enable richer cross-service observability and business-level processing when appropriate.
Keep baggage minimal, standardized, and free of sensitive data to avoid performance and security issues.

Further lessons will dive deeper into context and propagation mechanisms, including W3C standards and language-specific propagation implementations.

Links and references

W3C Baggage: https://www.w3.org/TR/baggage/
OpenTelemetry Propagation: https://opentelemetry.io/docs/reference/specification/context/api/
OpenTelemetry Python docs: https://opentelemetry.io/docs/instrumentation/python/

Watch Video

Span Resource

Context Propagation

​Observability signals — quick recap

​Baggage vs. span attributes

​Python example — set baggage and inject into outgoing headers

​Python example — extract baggage from incoming headers and copy into span attributes

​Real-world use cases

​Security considerations

​Best practices

​Key takeaways

​Links and references

Watch Video

Observability signals — quick recap

Baggage vs. span attributes

Python example — set baggage and inject into outgoing headers

Python example — extract baggage from incoming headers and copy into span attributes

Real-world use cases

Security considerations

Best practices

Key takeaways

Links and references