Propagation format for distributed trace context: Baggage

W3C First Public Working Draft

This version:
Latest published version:
Latest editor's draft:
Sergey Kanzhelev (Google)
Morgan McLean (Google)
Alois Reitbauer (Dynatrace)
GitHub w3c/baggage
File a bug
Commit history
Pull requests
We are on Slack.


Distributed tracing is a set of tools and practices to monitor the health and reliability of a distributed application. A distributed application is an application that consists of multiple components that are deployed and operated separately. It is also known as micro-service.

The main concept behind distributed tracing is event correlation. Event correlation is a way to correlate events from one component to the events from another. It allows to find the cause-and-effect relationship between these events. For instance – find which user action in a browser caused a failure in the business logic layer.

To correlate events between components, these components need to exchange and store a piece of information called context. Typically context consists of an originating event identifier, an originating component identity and other event properties. Context has two parts. The first part is a trace context. Trace context consists of properties crucial for event correlation. The second part is baggage. Baggage carries user-defined properties. These properties may be helpful for correlation scenarios. But they are not required and components may choose to not carry or store them.

Unifying the format of distributed tracing context as well as aligning on semantic meaning of the values is the main objective of this working group. The goal is to share this with the community so that various tracing and diagnostics products can operate together.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at

This is the First Public Working Draft (FPWD). There are a few implementations of this protocol available. Experimental interoperability scenarios were run and have demonstrated promising results. The specification will be progressed into Candidate Recommendation stage after that, drafts for binary, AMQP and MQTT protocols will be written to make sure the concepts and structure defined in this specification can be ported to other protocols.

This document was published by the Distributed Tracing Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to (archives) with baggage at the start of your email's subject .

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 1 August 2017 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 15 September 2020 W3C Process Document.

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Overview

The baggage header represents user-defined baggage associated with a trace. Libraries and platforms MAY propagate this header.

3. Baggage HTTP Header Format

The baggage header is used to propagate user-supplied key-value pairs through a distributed request. A received header MAY be altered to change or add information and it MUST be passed on to all downstream requests.

Multiple baggage headers are allowed. Values can be combined in a single header according to RFC 7230.

See rationale document for details of decisions made for this format.

3.1 Header Name

Header name: baggage

In order to increase interoperability across multiple protocols and encourage successful integration, implementations SHOULD keep the header name lowercase.

3.2 Header Content

This section uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].

3.2.1 Definition

list        =  list-member 0*179( OWS "," OWS list-member )
list-member =  key OWS "=" OWS value *( OWS ";" OWS property )
property    =  key OWS "=" OWS value
property    =/ key OWS
key         =  token ; as defined in RFC 2616, Section 2.2
value       =  %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
               ; US-ASCII characters excluding CTLs,
               ; whitespace, DQUOTE, comma, semicolon,
               ; and backslash
OWS         =  *( SP / HTAB ) ; optional white space, as defined in RFC 7230, Section 3.2.3

token is defined in [RFC2616], Section 2.2:

The definition of OWS is taken from [RFC7230], Section 3.2.3: list

List of key-value pairs with optional properties attached. It can not be guaranteed that keys are unique. Consumers MUST be able to handle duplicate keys while producers SHOULD try to deduplicate the list. key

ASCII string according to the token format, defined in RFC2616, Section 2.2. Leading and trailing whitespaces (OWS) are allowed but MUST be trimmed when converting the header into a data structure. value

A value contains a URL encoded UTF-8 string. Leading and trailing whitespaces (OWS) are allowed but MUST be trimmed when converting the header into a data structure. property

Additional metadata MAY be appended to values in the form of property set, represented as semi-colon ; delimited list of keys and/or key-value pairs, e.g. ;k1=v1;k2;k3=v3. The semantic of such properties is opaque to this specification. Leading and trailing OWS is allowed but MUST be trimmed when converting the header into a data structure.

3.2.2 Limits

  1. Maximum number of name-value pairs: 180.
  2. Maximum number of bytes per a single name-value pair: 4096.
  3. Maximum total length of all name-value pairs: 8192.

3.2.3 Example

key1=value1;property1;property2, key2 = value2, key3=value3; propertyKey=propertyValue

3.3 Examples of HTTP headers

Single header:

baggage: userId=alice,serverNode=DF:28,isProduction=false

Context might be split into multiple headers:

baggage: userId=alice
baggage: serverNode=DF%3A28,isProduction=false

Values and names might begin and end with spaces:

baggage: userId =   alice
baggage: serverNode = DF%3A28, isProduction = false

3.3.1 Example use case

For example, if all of your data needs to be sent to a single node, you could propagate a property indicating that.

baggage: serverNode=DF:28

For example, if you need to log the original user ID when making transactions arbitrarily deep into a trace.

baggage: userId=alice

For example, if you have non-production requests that flow through the same services as production requests.

baggage: isProduction=false

A. References

A.1 Normative references

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:
Hypertext Transfer Protocol -- HTTP/1.1. R. Fielding; J. Gettys; J. Mogul; H. Frystyk; L. Masinter; P. Leach; T. Berners-Lee. IETF. June 1999. Draft Standard. URL:
Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL:
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL:
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: