Skip to content

Commit e711f74

Browse files
adrielpadrielp
authored
[spec] add environment variables as context propagators specification (#4454)
1 parent 89c6196 commit e711f74

File tree

4 files changed

+162
-0
lines changed

4 files changed

+162
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ release.
99

1010
### Context
1111

12+
- Add context propagation through Environment Variables specification.
13+
([#4454](https://github.com/open-telemetry/opentelemetry-specification/pull/4454))
14+
1215
### Traces
1316

1417
### Metrics
@@ -20,6 +23,9 @@ release.
2023

2124
### Baggage
2225

26+
- Add context (baggage) propagation through Environment Variables specification.
27+
([#4454](https://github.com/open-telemetry/opentelemetry-specification/pull/4454))
28+
2329
### Resource
2430

2531
### Profiles

‎specification/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ path_base_for_github_subdir:
2828
- API Specification
2929
- [Context](context/README.md)
3030
- [Propagators](context/api-propagators.md)
31+
- [Environment Variable Carriers](context/env-carriers.md)
3132
- [Baggage](baggage/api.md)
3233
- [Tracing](trace/api.md)
3334
- [Metrics](metrics/api.md)

‎specification/baggage/api.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,10 @@ The API layer or an extension package MUST include the following `Propagator`s:
183183
See [Propagators Distribution](../context/api-propagators.md#propagators-distribution)
184184
for how propagators are to be distributed.
185185

186+
See [Environment Variable Carriers](../context/env-carriers.md) for how propagation should
187+
be handled when using environment variables as a carrier mechanism between
188+
processes.
189+
186190
Note: The W3C baggage specification does not currently assign semantic meaning
187191
to the optional metadata.
188192

‎specification/context/env-carriers.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Environment Variables as Context Propagation Carriers
2+
3+
**Status**: [Experimental](../document-status.md)
4+
5+
<details>
6+
<summary>Table of Contents</summary>
7+
8+
<!-- toc -->
9+
10+
- [Overview](#overview)
11+
- [Propagator Mechanisms](#propagator-mechanisms)
12+
* [Environment Variable Names](#environment-variable-names)
13+
* [Format Restrictions](#format-restrictions)
14+
+ [Name Restrictions](#name-restrictions)
15+
+ [Value Restrictions](#value-restrictions)
16+
+ [Size Limitations](#size-limitations)
17+
* [Operational Guidance](#operational-guidance)
18+
+ [Environment Variable Immutability](#environment-variable-immutability)
19+
+ [Process Spawning](#process-spawning)
20+
+ [Security](#security)
21+
+ [Case Sensitivity](#case-sensitivity)
22+
23+
<!-- tocstop -->
24+
25+
</details>
26+
27+
## Overview
28+
29+
Environment variables provide a mechanism to propagate context and baggage
30+
information across process boundaries when network protocols are not
31+
applicable. This specification extends the [API Propagators](../context/api-propagators.md)
32+
to define how the
33+
[TextMapPropagator](../context/api-propagators.md#textmap-propagator) can be
34+
used with environment variables.
35+
36+
Common systems where context propagation via environment variables is useful
37+
include:
38+
39+
- Batch processing systems
40+
- CI/CD environments
41+
- Command-line tools
42+
43+
## Propagator Mechanisms
44+
45+
Propagating context via environment variables involves reading and writing to
46+
environment variables. A `TextMapPropagator` SHOULD be used alongside its
47+
normal `Get`, `Set`, `Extract`, and `Inject` functionality as described in the [API
48+
Propagators](../context/api-propagators.md) specification.
49+
50+
### Environment Variable Names
51+
52+
It is RECOMMENDED to use the [W3C Trace
53+
Context](https://www.w3.org/TR/trace-context/) and [W3C
54+
Baggage](https://www.w3.org/TR/baggage/) specifications mapped to environment
55+
variable names for consistent context propagation.
56+
57+
When using the W3C Trace Context and Baggage propagators with environment
58+
variables, the following translated standard environment variable names SHOULD
59+
be used:
60+
61+
| Context Information | Environment Variable | W3C Header Equivalent |
62+
|---------------------|----------------------|-----------------------|
63+
| Trace Context | `TRACEPARENT` | `traceparent` |
64+
| Trace State | `TRACESTATE` | `tracestate` |
65+
| Baggage | `BAGGAGE` | `baggage` |
66+
67+
Implementations MAY support additional propagation formats and SHOULD provide
68+
configuration options to override the default environment variable.
69+
70+
### Format Restrictions
71+
72+
#### Name Restrictions
73+
74+
Environment variable names used for context propagation:
75+
76+
- SHOULD use uppercase letters, digits, and underscores for maximum
77+
cross-platform compatibility
78+
- MUST NOT include characters forbidden in environment variables per
79+
platform-specific restrictions
80+
- SHOULD follow naming conventions that align with the propagation format
81+
specification they're implementing (e.g., `TRACEPARENT` for W3C trace context)
82+
83+
#### Value Restrictions
84+
85+
Environment variable values used for context propagation:
86+
87+
- MUST only use characters that are valid in HTTP header fields per [RFC
88+
9110](https://tools.ietf.org/html/rfc9110)
89+
- MUST follow the format requirements of the specific propagation protocol
90+
(e.g., W3C Trace Context specification for `TRACEPARENT` values)
91+
- SHOULD NOT contain sensitive information
92+
93+
#### Size Limitations
94+
95+
Implementations SHOULD follow platform-specific environment variable size
96+
limitations:
97+
98+
- Windows: Maximum 32,767 characters for name=value pairs according to
99+
[Microsoft Documentation](https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-setenvironmentvariable)
100+
- UNIX: System-dependent limits exist and are typically lower than Windows.
101+
102+
When truncation is required due to size limitations, implementations MUST
103+
truncate whole entries. Truncation SHOULD start at the end of the entry list.
104+
Implementers MUST document how graceful truncation is handled and SHOULD
105+
provide the link to the corresponding specification (e.g., [W3C tracestate
106+
Truncation guidance][w3c-truncation]).
107+
108+
[w3c-truncation]: https://www.w3.org/TR/trace-context/#tracestate-limits
109+
110+
### Operational Guidance
111+
112+
#### Environment Variable Immutability
113+
114+
Once set for a process, environment variables SHOULD be treated as immutable
115+
within that process:
116+
117+
- Applications SHOULD read context-related environment variables during
118+
initialization.
119+
- Applications SHOULD NOT modify context-related environment variables of the
120+
environment in which the parent process exists.
121+
122+
#### Process Spawning
123+
124+
When spawning child processes:
125+
126+
- Parent processes SHOULD copy the current environment variables (if
127+
applicable), modify, and inject context when spawning child processes.
128+
- Child processes SHOULD extract context from environment variables at startup.
129+
- When spawning multiple child processes with different contexts or baggage,
130+
each child SHOULD receive its own copy of the environment variables with
131+
appropriate information.
132+
133+
#### Security
134+
135+
Environment variables are generally accessible to all code running within a
136+
process and with the correct permissions, can be accessed from other processes.
137+
138+
- Implementations SHOULD NOT store sensitive information in environment
139+
variables.
140+
- Applications running in multi-tenant environments SHOULD be aware that
141+
environment variables may be visible to other processes or users with
142+
appropriate permissions.
143+
144+
#### Case Sensitivity
145+
146+
Environment variable names are case-sensitive on UNIX and case-insensitive on
147+
Windows.
148+
149+
- For maximum compatibility, implementations MUST:
150+
- Use uppercase names consistently (`TRACEPARENT` not `TraceParent`).
151+
- Use the canonical case when setting environment variables.

0 commit comments

Comments
 (0)