> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenTelemetry Baggage
> Explains OpenTelemetry baggage propagation, differences from span attributes, usage examples, security risks, and best practices for contextual key value metadata across services
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.
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.
## Python example — set baggage and inject into outgoing headers
Steps:
1. Use the baggage API to set key-value pairs into a context.
2. Use the propagation API to inject the context into outgoing HTTP headers.
```python theme={null}
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.
```python theme={null}
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):
```json theme={null}
{
"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.
## 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.
## 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/](https://www.w3.org/TR/baggage/)
* OpenTelemetry Propagation: [https://opentelemetry.io/docs/reference/specification/context/api/](https://opentelemetry.io/docs/reference/specification/context/api/)
* OpenTelemetry Python docs: [https://opentelemetry.io/docs/instrumentation/python/](https://opentelemetry.io/docs/instrumentation/python/)