diff --git a/CHANGELOG.md b/CHANGELOG.md index d6cb1481647..ce79321801f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ release. ### Context +- Clarify that environment variable propagation carriers normalize requested + keys, carrier keys, and returned keys. + ([#5102](https://github.com/open-telemetry/opentelemetry-specification/pull/5102)) + ### Traces ### Metrics diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index c388496c158..4d730e43aa5 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -66,6 +66,21 @@ Environment variable names used for context propagation: (`_`) with an underscore (`_`), - prefixing the name with an underscore (`_`) if it would otherwise start with an ASCII digit. +- MUST be normalized consistently by `Get`, `Set`, and `Keys` operations: + - when injecting context, the carrier `Set` operation MUST write values using + the normalized form of the key provided by the propagator, + - when extracting context, the carrier `Get` operation MUST normalize the key + requested by the propagator and the key names present in the carrier before + matching them. If multiple carrier key names normalize to the same key name, + the carrier is ambiguous and in that case, the value returned by `Get` is + unspecified, + - when listing keys, the carrier `Keys` function MUST return normalized key + names. + +For example, if a propagator requests the key `x-b3-traceid`, the environment +variable carrier MUST match it to the carrier key `X_B3_TRACEID`. It MUST also +match it to a carrier key such as `x-b3-traceid`, because both key names +normalize to `X_B3_TRACEID`. > [!NOTE] > This normalization is consistent with the environment variable naming rules