Skip to content

Commit dc33969

Browse files
pellaredcodeboten
andauthored
Remove misleading implementation guidance for context propagation via environment variables (#5003)
Per #4961 (comment) and other similar feedback ## Changes This PR removes the non-normative guidance that presented a dedicated `EnvironmentContextPropagator` as a first-class alternative for environment variable context propagation. The supplementary guidance now describes the carrier-based pattern directly: - use the existing `TextMapPropagator` with environment-specific carriers (`EnvironmentGetter` and `EnvironmentSetter`) - reference the existing C++, Go, Java, and Python implementation (I also created a PR for Swift that follows the same pattern open-telemetry/opentelemetry-swift-core#47) The previous (removed) “Approach 1” guidance suggested that a dedicated environment-variable-specific propagator was a viable recommendation. Based on the discussion in #4961, that approach is seen as misleading/buggy: - the environment variable carrier should remain format-agnostic - propagator-specific behavior belongs in the propagator, not in the carrier - the Swift example did not reflect the direction we want to recommend here This change keeps the document aligned with the carrier-based model used by the referenced implementations. ## Side note I think we can look into stabilization of this document after this PR is merged. I plan to create a stabilization issue and update the compliance matrix. --------- Co-authored-by: Alex Boten <223565+codeboten@users.noreply.github.com>
1 parent f41d2af commit dc33969

File tree

2 files changed

+5
-32
lines changed

2 files changed

+5
-32
lines changed

CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ release.
1414
([#4914](https://github.com/open-telemetry/opentelemetry-specification/issues/4914))
1515
- Decouple the responsibilities of the environment variable propagation carrier.
1616
([#4961](https://github.com/open-telemetry/opentelemetry-specification/issues/4961))
17+
- Remove misleading implementation approach the environment variable propagation.
18+
([#5003](https://github.com/open-telemetry/opentelemetry-specification/issues/5003))
1719

1820
### Traces
1921

specification/context/env-carriers.md

Lines changed: 3 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,6 @@
1515
+ [Process Spawning](#process-spawning)
1616
+ [Security](#security)
1717
- [Supplementary Guidelines](#supplementary-guidelines)
18-
* [Approach 1: Providing a dedicated `EnvironmentContextPropagator`](#approach-1-providing-a-dedicated-environmentcontextpropagator)
19-
* [Approach 2: Using the carriers directly through `Setters` and `Getters`](#approach-2-using-the-carriers-directly-through-setters-and-getters)
20-
* [Common Behaviors](#common-behaviors)
2118

2219
<!-- tocstop -->
2320

@@ -117,23 +114,9 @@ process and with the correct permissions, can be accessed from other processes.
117114
> guidance only. It does not add requirements to the specification.
118115
119116
Language implementations of OpenTelemetry have flexibility in how they implement
120-
environment variable context propagation. Two main approaches have been
121-
identified as viable.
122-
123-
### Approach 1: Providing a dedicated `EnvironmentContextPropagator`
124-
125-
SDKs can create a dedicated propagator for environment variables. For example,
126-
the [OTel Swift][swift] implements a custom `EnvironmentContextPropagator` that
127-
handles the environment-specific logic internally, in essence decorating the
128-
`TextMapPropagator`.
129-
130-
[swift]: https://github.com/open-telemetry/opentelemetry-swift-core/blob/c84cdc1760e20fc3a448c4e8aaae490f7d48ac67/Sources/OpenTelemetrySdk/Trace/Propagation/EnvironmentContextPropagator.swift
131-
132-
### Approach 2: Using the carriers directly through `Setters` and `Getters`
133-
134-
Language implementations can use the existing `TextMapPropagator` interface directly with
135-
environment-specific carriers. Go and Python SDKs follow this pattern by
136-
providing:
117+
environment variable context propagation. Language implementations can use the
118+
existing `TextMapPropagator` directly with environment-specific carriers.
119+
Typically implementations follow this pattern by providing:
137120

138121
- `EnvironmentGetter` - creates an in-memory copy of the current environment
139122
variables and reads context from that copy.
@@ -151,15 +134,3 @@ Examples:
151134
[gi]: https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/propagators/envcar
152135
[ji]: https://github.com/open-telemetry/opentelemetry-java/tree/main/api/incubator/src/main/java/io/opentelemetry/api/incubator/propagation
153136
[pi]: https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-api/src/opentelemetry/propagators/_envcarrier.py
154-
155-
### Common Behaviors
156-
157-
Both approaches achieve the same outcome while offering different developer
158-
experiences. Language implementations may choose either approach based on their
159-
language's idioms and ecosystem conventions. The behaviors in both approaches
160-
are the same in that they:
161-
162-
1. **Extract context**: Read from environment variables and delegate to the
163-
configured `TextMapPropagator` (e.g. W3C, B3) for parsing
164-
2. **Inject context**: Return a dictionary/map of environment variables that
165-
application owners can pass to their process spawning libraries

0 commit comments

Comments
 (0)