Skip to content

Commit 289d789

Browse files
authored
Clarify environment carrier key normalization behavior (open-telemetry#5102)
Towards open-telemetry#5040 ## Changes Clarifies the environment variable propagation carrier key normalization requirements: - `Set` writes values using normalized key names. - `Get` normalizes both the requested propagator key and carrier keys before matching. - `Keys` returns normalized key names. ## Motivation The existing text defined how key names are normalized, but it did not explicitly say where that normalization applies. This PR clarifies that normalization is part of the carrier behavior for writing, reading, and listing keys. This follows the robustness principle: carriers write the normalized representation, while getters can still accept a non-normalized environment variable key if it normalizes to the requested propagation key. For example, a non-normalized `traceparent` environment variable can still be used by the propagation getter when matching `TRACEPARENT`. This retrospects open-telemetry#4944 (comment) now that implementations are in place. ## Implementation references - Go: open-telemetry/opentelemetry-go-contrib#8761 - .NET: open-telemetry/opentelemetry-dotnet#7174 - Java: open-telemetry/opentelemetry-java#8233 - Python: open-telemetry/opentelemetry-python#5119 - Swift: open-telemetry/opentelemetry-swift-core#47 Related Java discussion: open-telemetry/opentelemetry-java#8233 (comment)
1 parent 04c76c2 commit 289d789

2 files changed

Lines changed: 19 additions & 0 deletions

File tree

CHANGELOG.md

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

1010
### Context
1111

12+
- Clarify that environment variable propagation carriers normalize requested
13+
keys, carrier keys, and returned keys.
14+
([#5102](https://github.com/open-telemetry/opentelemetry-specification/pull/5102))
15+
1216
### Traces
1317

1418
### Metrics

specification/context/env-carriers.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,21 @@ Environment variable names used for context propagation:
6666
(`_`) with an underscore (`_`),
6767
- prefixing the name with an underscore (`_`) if it would otherwise start with
6868
an ASCII digit.
69+
- MUST be normalized consistently by `Get`, `Set`, and `Keys` operations:
70+
- when injecting context, the carrier `Set` operation MUST write values using
71+
the normalized form of the key provided by the propagator,
72+
- when extracting context, the carrier `Get` operation MUST normalize the key
73+
requested by the propagator and the key names present in the carrier before
74+
matching them. If multiple carrier key names normalize to the same key name,
75+
the carrier is ambiguous and in that case, the value returned by `Get` is
76+
unspecified,
77+
- when listing keys, the carrier `Keys` function MUST return normalized key
78+
names.
79+
80+
For example, if a propagator requests the key `x-b3-traceid`, the environment
81+
variable carrier MUST match it to the carrier key `X_B3_TRACEID`. It MUST also
82+
match it to a carrier key such as `x-b3-traceid`, because both key names
83+
normalize to `X_B3_TRACEID`.
6984

7085
> [!NOTE]
7186
> This normalization is consistent with the environment variable naming rules

0 commit comments

Comments
 (0)