In distributed tracing, Baggage is application-defined key/value context that can travel with a request between services. It has a different job from a trace ID or span ID, which identifies work in a trace. A team might carry an experiment label or internal routing context, but the application that creates a value determines what it means. Calling it “tracing metadata” does not make it harmless or non-sensitive.

Conceptual diagram of key/value baggage traveling with a service request and being checked at a trust boundary

Baggage is request context, not trace identity

Distributed tracing links work across services with traces and spans so teams can inspect flow and latency. Baggage is a separate set of key/value pairs that may accompany that flow. OpenTelemetry describes it as application-defined properties associated with a request or workflow; the W3C HTTP header format represents members in a baggage header. The keys and values do not identify a trace or carry universally assigned meaning.

A value such as experiment=blue might help a service select or observe an internal path. A downstream consumer is not guaranteed to understand that key, and its name cannot prove that the value contains no personal data. Treating trace context and baggage as separate data lets teams set different lifetimes, access rules, and propagation policies for trace correlation and application context.

Header syntax and propagation limits

The W3C format draft describes a comma-separated list of members. Keys follow token syntax, and values outside the allowed baggage-octet range are percent-encoded. Duplicate keys can occur, while optional properties may have application-specific meaning. This does not promise that every receiver interprets arbitrary values consistently. Character encoding, duplicate handling, and parser behavior should be tested across implementations.

The draft guarantees propagation of all members when the header has no more than 64 members and is no larger than 8192 bytes. Above those limits, an implementation may drop members; it must not propagate a partial member. These are not storage limits for sensitive data or a promise of unlimited forwarding. Operators should also check the actual header limits imposed by their proxies and libraries.

Set allow and removal rules at trust boundaries

Baggage can originate in user input or an upstream service, so treat it as untrusted input. The W3C security text calls for validation and sanitization and cautions about forwarding across trust boundaries. Its privacy text notes that values may include identifying data and that keys and values have no assigned semantics. At a boundary where trust changes—such as an external partner, browser, or log collector—define allowed keys, length and format rules, and removal behavior. A minimal default is safer than forwarding everything.

Trace which component can set each key and whether each hop can add or overwrite values. At an external boundary, consider copying only explicitly needed members and removing the rest. Avoid tokens, email addresses, account identifiers, or raw search terms when exposure would be harmful. Check whether complete headers are copied into logs or error reports. The OpenTelemetry API also describes clearing baggage before sending data to an untrusted process.

A deployment checklist

  • Record an owner and purpose for every key, then check whether its values can contain personal or authentication data.
  • Define an allowlist and removal rule at each service boundary; test whether unexpected keys survive to the next hop.
  • Exercise member-count and byte-size limits, percent encoding, duplicate keys, and partial or malformed header input in parsers and proxies.
  • Trace copies into logs, metrics, and error reports, including their retention periods.

Expert perspective: manage convenience metadata as a data flow

The key observability decision is whether baggage should be forwarded automatically like trace correlation, or treated as application data that requires review at each boundary. A key named tenant, user, or region has no uniform meaning across organizations. A value that seems harmless inside a service may become identifying when sent to an external analytics provider. Record the schema owner, purpose, permitted recipients, and retention or deletion policy, and repeat privacy review when these change.

The W3C format, security, and privacy materials cited here are Editor’s Draft source files; this article does not present them as requirements of a finalized W3C Recommendation. Confirm the adopted document status and the versions of the OpenTelemetry SDKs and proxies in use before setting implementation policy.

Sources and references