What is Baggage in OpenTelemetry, how does it differ from span attributes, and what risks come with adding fields to it?

## What it is OpenTelemetry's Context is an immutable, propagation-agnostic container. Two things are commonly stored in it: the current span (from which the span context — trace id, span id, flags — is derived) and Baggage. Baggage is a simple ordered set of key/value string pairs, with optional per-entry metadata, defined by the W3C Baggage specification and serialised into a header of that name: ``` baggage: tenant=acme,ring=canary,priority=high ``` It is propagated by its own propagator, usually composed with the trace-context propagator, so a service configured for W3C emits both `traceparent` and `baggage`. The two are independent: baggage can exist without a sampled trace and vice versa. ## Baggage versus span attributes | | Baggage | Span attributes | |---|---|---| | Scope | the whole distributed request, every downstream hop | one span | | Transport | serialised into an HTTP/gRPC/broker header on each call | exported directly to the backend with the span | | Cost | bytes on every hop, plus header-size limits | payload size at export only | | Trust | inbound value may come from an untrusted caller | set by your own code | | Recorded automatically? | **No** | Yes, it is part of the span | That last row is the most common misconception. Putting `tenant=acme` in baggage does not make `tenant` searchable in your tracing backend. Something must read the baggage and set it as an attribute — typically a span processor that copies an allowlisted set of baggage keys onto every span it starts. Many SDKs and distributions ship such a processor, but it is opt-in and key-restricted for good reason. ## When baggage earns its place The legitimate use is *information known early that is needed late, by code that cannot look it up*. Examples: the tenant or customer tier, so a downstream service can label spans or make a shedding decision; a deployment ring or experiment arm, so telemetry can be split by cohort across services; a request priority for load shedding; a synthetic-traffic marker so load-test requests can be excluded from business metrics. The illegitimate uses are all variations of "use it as an RPC parameter". If a downstream service *behaves* differently based on baggage, you have created an implicit, untyped, unversioned API between services that no interface definition documents and no compiler checks. Worse, it is attacker-influenceable at any hop that does not sanitise. Anything load-bearing for correctness or authorisation belongs in the actual request contract; authorisation decisions must never read baggage. ## The risks in detail **Size and cost.** Baggage is added to every outbound request of every service in the path. A 200-byte baggage set on a fan-out of five services and ten calls each is real bandwidth and real header-parsing work, and it interacts badly with servers that cap total header size (a hop can start returning 431 or dropping requests when the accumulated set grows). The W3C specification limits the header to 8192 bytes and 180 entries, and implementations may drop entries when limits are hit — silently, from the perspective of the code that set them. **Cardinality.** If a processor copies baggage onto spans, high-cardinality values such as a user id are merely expensive in the trace store. If anything copies baggage into *metric* labels, high cardinality multiplies time series and can take down the metrics backend. Copy with an explicit allowlist of keys, never wholesale. **Confidentiality.** Baggage goes wherever the request goes, including to third-party APIs if your outbound HTTP client injects context indiscriminately, and into every log line that logs headers. Never put personal data, tokens or secrets in it. Consider restricting injection to internal destinations. **Trust.** Inbound baggage on a public endpoint is user input. Accepting it means an outsider can set `tenant=` or `priority=` values that your own processors will stamp onto spans and metrics — a spoofing and cardinality-bomb vector at once. The perimeter rule is: strip inbound baggage at the edge, or allowlist a small set of keys and validate their values, then set the trustworthy versions yourself from the authenticated principal. ## Governance Because baggage is global and cheap to add, it accretes. Treat the key set as a governed schema: a short documented list with an owner per key, a size budget, a perimeter allowlist enforced in the gateway, and an alert on total baggage header size at ingress. Removing a key later is hard precisely because you cannot see who depends on it — another argument for keeping behaviour out of it.