0
# Context Propagation
1

2
Context propagation functionality providing W3C-compliant propagators for distributed tracing and baggage propagation with support for compositional propagator patterns.
3

4
## Capabilities
5

6
### W3C Trace Context Propagator
7

8
W3C Trace Context specification-compliant propagator for distributed tracing context sharing via HTTP headers.
9

10
```typescript { .api }
11
/**
12
 * Propagates SpanContext through W3C Trace Context format
13
 * Based on https://www.w3.org/TR/trace-context/
14
 */
15
class W3CTraceContextPropagator implements TextMapPropagator {
16
  /**
17
   * Inject trace context into carrier using traceparent and tracestate headers
18
   * @param context - OpenTelemetry context containing span information
19
   * @param carrier - Object to inject headers into (typically HTTP headers)
20
   * @param setter - Function to set header values in the carrier
21
   */
22
  inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
23

24
  /**
25
   * Extract trace context from carrier headers
26
   * @param context - OpenTelemetry context to enhance with extracted span context
27
   * @param carrier - Object containing headers (typically HTTP request headers) 
28
   * @param getter - Function to retrieve header values from the carrier
29
   * @returns Context with extracted span context
30
   */
31
  extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
32

33
  /**
34
   * Get list of header fields used by this propagator
35
   * @returns Array of header field names
36
   */
37
  fields(): string[];
38
}
39

40
const TRACE_PARENT_HEADER: string;
41
const TRACE_STATE_HEADER: string;
42

43
/**
44
 * Parse traceparent header value into SpanContext
45
 * @param traceParent - Traceparent header value in format: version-traceId-spanId-flags
46
 * @returns SpanContext object or null if parsing fails
47
 */
48
function parseTraceParent(traceParent: string): SpanContext | null;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { W3CTraceContextPropagator, TRACE_PARENT_HEADER } from "@opentelemetry/core";
55
import { trace } from "@opentelemetry/api";
56

57
const propagator = new W3CTraceContextPropagator();
58
const headers: Record<string, string> = {};
59

60
// Inject current trace context into HTTP headers
61
const span = trace.getActiveSpan();
62
if (span) {
63
  const context = trace.setSpan(trace.context.active(), span);
64
  propagator.inject(context, headers, {
65
    set: (carrier, key, value) => carrier[key] = value
66
  });
67
  
68
  console.log(headers[TRACE_PARENT_HEADER]); // e.g., "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
69
}
70

71
// Extract trace context from incoming HTTP headers
72
const incomingHeaders = {
73
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
74
  "tracestate": "congo=t61rcWkgMzE"
75
};
76

77
const extractedContext = propagator.extract(trace.context.active(), incomingHeaders, {
78
  get: (carrier, key) => carrier[key]
79
});
80

81
const spanContext = trace.getSpanContext(extractedContext);
82
console.log(spanContext?.traceId); // "4bf92f3577b34da6a3ce929d0e0e4736"
83
```
84

85
### W3C Baggage Propagator
86

87
W3C Baggage specification-compliant propagator for sharing key-value pairs across distributed services.
88

89
```typescript { .api }
90
/**
91
 * Propagates Baggage through W3C Baggage format
92
 * Based on https://w3c.github.io/baggage/
93
 */
94
class W3CBaggagePropagator implements TextMapPropagator {
95
  /**
96
   * Inject baggage into carrier using baggage header
97
   * @param context - OpenTelemetry context containing baggage
98
   * @param carrier - Object to inject headers into
99
   * @param setter - Function to set header values in the carrier
100
   */
101
  inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
102

103
  /**
104
   * Extract baggage from carrier headers
105
   * @param context - OpenTelemetry context to enhance with extracted baggage
106
   * @param carrier - Object containing headers
107
   * @param getter - Function to retrieve header values from the carrier
108
   * @returns Context with extracted baggage
109
   */
110
  extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
111

112
  /**
113
   * Get list of header fields used by this propagator
114
   * @returns Array of header field names
115
   */
116
  fields(): string[];
117
}
118

119
/**
120
 * Parse baggage header string into key-value pairs
121
 * @param value - Baggage header value
122
 * @returns Record of key-value pairs
123
 */
124
function parseKeyPairsIntoRecord(value?: string): Record<string, string>;
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
import { W3CBaggagePropagator } from "@opentelemetry/core";
131
import { propagation } from "@opentelemetry/api";
132

133
const baggagePropagator = new W3CBaggagePropagator();
134
const headers: Record<string, string> = {};
135

136
// Create baggage and inject into headers
137
const baggage = propagation.createBaggage({
138
  "user.id": { value: "12345" },
139
  "session.id": { value: "abcdef" }
140
});
141

142
const contextWithBaggage = propagation.setBaggage(propagation.active(), baggage);
143
baggagePropagator.inject(contextWithBaggage, headers, {
144
  set: (carrier, key, value) => carrier[key] = value
145
});
146

147
console.log(headers.baggage); // "user.id=12345,session.id=abcdef"
148

149
// Extract baggage from incoming headers
150
const incomingHeaders = {
151
  "baggage": "user.id=12345,session.id=abcdef,theme=dark"
152
};
153

154
const extractedContext = baggagePropagator.extract(propagation.active(), incomingHeaders, {
155
  get: (carrier, key) => carrier[key]
156
});
157

158
const extractedBaggage = propagation.getBaggage(extractedContext);
159
console.log(extractedBaggage?.getEntry("user.id")?.value); // "12345"
160
```
161

162
### Composite Propagator
163

164
Combines multiple propagators into a single propagator for unified context injection and extraction.
165

166
```typescript { .api }
167
/**
168
 * Configuration object for composite propagator
169
 */
170
interface CompositePropagatorConfig {
171
  /**
172
   * List of propagators to run. Propagators run in list order.
173
   * If a propagator later in the list writes the same context key
174
   * as a propagator earlier in the list, the later one will "win".
175
   */
176
  propagators?: TextMapPropagator[];
177
}
178

179
/**
180
 * Combines multiple propagators into a single propagator
181
 */
182
class CompositePropagator implements TextMapPropagator {
183
  /**
184
   * Construct a composite propagator from a list of propagators
185
   * @param config - Configuration object for composite propagator
186
   */
187
  constructor(config?: CompositePropagatorConfig);
188

189
  /**
190
   * Run each of the configured propagators with the given context and carrier.
191
   * Propagators are run in the order they are configured.
192
   * @param context - Context to inject
193
   * @param carrier - Carrier into which context will be injected
194
   * @param setter - Function to set values in carrier
195
   */
196
  inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
197

198
  /**
199
   * Run each of the configured propagators with the given context and carrier.
200
   * Propagators are run in the order they are configured.
201
   * @param context - Context to add values to
202
   * @param carrier - Carrier from which to extract context
203
   * @param getter - Function to get values from carrier
204
   * @returns Enhanced context with extracted values
205
   */
206
  extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
207

208
  /**
209
   * Get combined list of header fields from all configured propagators
210
   * @returns Array of header field names
211
   */
212
  fields(): string[];
213
}
214
```
215

216
**Usage Examples:**
217

218
```typescript
219
import {
220
  CompositePropagator,
221
  W3CTraceContextPropagator,
222
  W3CBaggagePropagator
223
} from "@opentelemetry/core";
224

225
// Create composite propagator with multiple propagators
226
const compositePropagator = new CompositePropagator({
227
  propagators: [
228
    new W3CTraceContextPropagator(),
229
    new W3CBaggagePropagator(),
230
  ],
231
});
232

233
// Use composite propagator for both trace context and baggage
234
const headers: Record<string, string> = {};
235

236
compositePropagator.inject(currentContext, headers, {
237
  set: (carrier, key, value) => carrier[key] = value
238
});
239

240
// Headers now contain both traceparent and baggage
241
console.log(headers.traceparent); // "00-..."
242
console.log(headers.baggage);     // "key1=value1,key2=value2"
243

244
// Extract from headers containing multiple propagation formats
245
const incomingHeaders = {
246
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
247
  "baggage": "user.id=12345,session.id=abcdef"
248
};
249

250
const extractedContext = compositePropagator.extract(
251
  propagation.active(), 
252
  incomingHeaders, 
253
  { get: (carrier, key) => carrier[key] }
254
);
255

256
// Context now contains both span context and baggage
257
const spanContext = trace.getSpanContext(extractedContext);
258
const baggage = propagation.getBaggage(extractedContext);
259
```