Copyright © 2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
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 https://www.w3.org/TR/.
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
public-trace-context@w3.org
(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.
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.
The baggage header represents user-defined baggage associated with a trace. Libraries and platforms MAY propagate this header.
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.
Header name: baggage
In order to increase interoperability across multiple protocols and encourage successful integration, implementations SHOULD keep the header name lowercase.
This section uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].
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.3token is defined in [RFC2616], Section 2.2: https://tools.ietf.org/html/rfc2616#section-2.2
The definition of OWS is taken from [RFC7230], Section 3.2.3: https://tools.ietf.org/html/rfc7230#section-3.2.3
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.
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.
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.
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.
180.4096.8192.key1=value1;property1;property2, key2 = value2, key3=value3; propertyKey=propertyValue
Single header:
baggage: userId=alice,serverNode=DF:28,isProduction=falseContext might be split into multiple headers:
baggage: userId=alice
baggage: serverNode=DF%3A28,isProduction=falseValues and names might begin and end with spaces:
baggage: userId = alice
baggage: serverNode = DF%3A28, isProduction = falseFor example, if all of your data needs to be sent to a single node, you could propagate a property indicating that.
baggage: serverNode=DF:28For example, if you need to log the original user ID when making transactions arbitrarily deep into a trace.
baggage: userId=aliceFor example, if you have non-production requests that flow through the same services as production requests.
baggage: isProduction=false