forked from w3c/trace-context
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
189 lines (168 loc) · 8.63 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>Trace Context</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove' defer></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
implementationReportURI: "https://w3c.github.io/trace-context/implementations",
/* previousMaturity: "CR",
previousPublishDate : "2019-08-13",
crEnd: "2019-10-08",*/
editors: [{
name: "Sergey Kanzhelev",
company: "Google",
companyURL: "https://google.com",
w3cid: "103966"
},
{
name: "Daniel Dyla",
company: "Dynatrace",
companyURL: "https://dynatrace.com",
w3cid: "117848"
},
{
name: "Yuri Shkuro",
company: "Meta",
w3cid: "104074"
},
{
name: "J. Kalyana Sundaram",
company: "Microsoft",
w3cid: "129894"
},
{
name: "Bastian Krol",
company: "Dash0",
w3cid: "127244"
}],
formerEditors: [{
name: "Nik Molnar",
w3cid: "104238"
},
{
name: "Alois Reitbauer",
w3cid: "48276"
},
{
name: "Morgan McLean",
w3cid: "104128"
},
{
name: "Bogdan Drutu",
w3cid: "104091"
},
{
name: "Daniel Khan",
w3cid: "90530"
}],
github: {
repoURL: "https://github.com/w3c/trace-context/",
branch: "main",
},
edDraftURI: "https://w3c.github.io/trace-context/",
shortName: "trace-context",
level: 3,
format: "markdown",
subjectPrefix: "trace-context",
group: "distributed-tracing",
wgPublicList: "public-trace-context",
otherLinks: [{
key: 'Discussions',
data: [{
value: 'We are on Slack.',
href: 'https://w3cdistributedtracing.slack.com/'
}]
}],
localBiblio: {
"BIT-FIELD": {
title: "8-bit field",
href: "https://en.wikipedia.org/wiki/Bit_field",
publisher: "Wikipedia"
}
}
};
</script>
</head>
<body>
<section id='abstract' data-include="spec/01-abstract.md" data-include-format='markdown'></section>
<section id='sotd' data-include="spec/02-sotd.md" data-include-format='markdown'></section>
<section id='conformance'></section>
<section>
<h2>Overview</h2>
<section>
<h3>Problem Statement</h3>
<p>Distributed tracing is a methodology implemented by tracing tools to follow, analyze and debug a transaction across multiple software components. Typically, a [=distributed trace=] traverses more than one component which requires it to be uniquely identifiable across all participating systems. Trace context propagation passes along this unique identification. Today, trace context propagation is implemented individually by each tracing vendor. In multi-vendor environments, this causes interoperability problems, like:</p>
<ul>
<li>Traces that are collected by different tracing vendors cannot be correlated as there is no shared unique identifier.</li>
<li>Traces that cross boundaries between different tracing vendors can not be propagated as there is no uniformly agreed set of identification that is forwarded.</li>
<li>Vendor specific metadata might be dropped by intermediaries.</li>
<li>Cloud platform vendors, intermediaries and service providers, cannot guarantee to support trace context propagation as there is no standard to follow.</li>
</ul>
<p>In the past, these problems did not have a significant impact as most applications were monitored by a single tracing vendor and stayed within the boundaries of a single platform provider. Today, an increasing number of applications are highly distributed and leverage multiple middleware services and cloud platforms.</p>
<p>This transformation of modern applications calls for a distributed tracing context propagation standard.</p>
</section>
<section id="solution">
<h3>Solution</h3>
<p>The trace context specification defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as <em>trace context</em>. Trace context solves the problems described above by</p>
<ul>
<li>providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together.</li>
<li>providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction.</li>
<li>providing an industry standard that intermediaries, platforms, and hardware providers can support.</li>
</ul>
<p>A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis. The interoperability provided by trace context is a prerequisite to manage modern micro-service based applications.</p>
<p>The current version of the Trace Context specification is targeted for implementations by applications and services, including web applications running within a browser. Web Browsers or User Agents are not currently in scope as a target implementation.</p>
</section>
<section>
<h3>Design Overview</h3>
<p>Trace context is split into two individual propagation fields supporting interoperability and vendor-specific extensibility:</p>
<ul>
<li>`traceparent` describes the position of the incoming request in its trace graph in a portable, fixed-length format. Its design focuses on fast parsing. Every tracing tool MUST properly set `traceparent` even when it only relies on vendor-specific information in `tracestate`</li>
<li>`tracestate` extends `traceparent` with vendor-specific data represented by a set of name/value pairs. Storing information in `tracestate` is optional.</li>
</ul>
<p>Tracing tools can provide two levels of compliant behavior interacting with trace context:</p>
<ul>
<li>At a minimum they MUST propagate the `traceparent` and `tracestate` headers and guarantee traces are not broken. This behavior is also referred to as forwarding a trace.</li>
<li>In addition they MAY also choose to participate in a trace by modifying the `traceparent` header and relevant parts of the `tracestate` header containing their proprietary information. This is also referred to as participating in a trace.</li>
</ul>
<p>A tracing tool can choose to change this behavior for each individual request to a component it is monitoring.</p>
</section>
</section>
<section data-include="spec/20-http_request_header_format.md" data-include-format='markdown'></section>
<section data-include="spec/21-http_response_header_format.md" data-include-format='markdown'></section>
<section class="informative" data-include="spec/30-processing-model.md" data-include-format='markdown'></section>
<section data-include="spec/40-other-protocols.md" data-include-format='markdown'></section>
<section data-include="spec/50-privacy.md" data-include-format='markdown'></section>
<section data-include="spec/51-security.md" data-include-format='markdown'></section>
<section class="informative" data-include="spec/60-trace-id-format.md" data-include-format='markdown'></section>
<section class="informative" data-include="spec/61-span-id-format.md" data-include-format='markdown'></section>
<section class="appendix" data-include="spec/60-acknowledgments.md" data-include-format='markdown'></section>
<section class="informative">
<h1>Glossary</h1>
<dl>
<dt><dfn data-lt="distributed traces">Distributed trace</dfn></dt>
<dd>
A distributed trace is a set of events, triggered as a result
of a single logical operation, consolidated across various
components of an application. A distributed trace contains
events that cross process, network and security boundaries.
A distributed trace may be initiated when someone presses a
button to start an action on a website - in this example, the
trace will represent calls made between the downstream services
that handled the chain of requests initiated by this button
being pressed.
</dd>
</dl>
<dl>
<dt><dfn data-lt="opaque">Opaque value</dfn></dt>
<dd>
An opaque value refers to a value that can only be understood
or processed in any way by the distributed trace participant that generated
this value. Any other participant must treat it as a blob of bytes.
</dd>
</dl>
</section>
</body>
</html>