From ed065ef72a53d67b0c0c10e5512133a255a2b77f Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 9 Jun 2026 12:08:05 +0200 Subject: [PATCH 1/6] env var carriers to only read and return normalized names --- CHANGELOG.md | 2 ++ specification/context/env-carriers.md | 48 +++++++++++++++------------ 2 files changed, 29 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9544e77dee9..61c1f4cf042 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ release. - Clarify that environment variable propagation carriers normalize requested keys, carrier keys, and returned keys. ([#5102](https://github.com/open-telemetry/opentelemetry-specification/pull/5102)) +- Specify that environment variable propagation carriers only read and return + normalized environment variable names. ### Traces diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 4d730e43aa5..eca3f1dd465 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -58,29 +58,35 @@ When using environment variables as carriers: ### Key Name Normalization -Environment variable names used for context propagation: - -- MUST be normalized by: - - uppercasing ASCII letters, - - replacing every character that is not an ASCII letter, digit, or underscore - (`_`) 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. +Environment variable carriers MUST normalize key names used for context +propagation. To normalize a key name, carriers MUST: + +- uppercase ASCII letters, +- replace every character that is not an ASCII letter, digit, or underscore + (`_`) with an underscore (`_`), +- prefix the name with an underscore (`_`) if it would otherwise start with an + ASCII digit. + +A normalized environment variable name is an environment variable name that is +unchanged by applying this normalization. Equivalently, a normalized environment +variable name matches the regular expression `[A-Z_][A-Z0-9_]*`. + +Environment variable names that do not match this pattern are non-normalized. + +Carriers MUST use normalized key names consistently in `Get`, `Set`, and +`Keys` operations: + +- `Set` MUST write values using the normalized form of the key provided by the + propagator. +- `Get` MUST normalize the key requested by the propagator and MUST use the + normalized key name to read from the carrier. +- `Keys` MUST return only key names that are already normalized. 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`. +variable carrier MUST normalize the requested key to `X_B3_TRACEID` and read +the `X_B3_TRACEID` environment variable. It MUST NOT read a non-normalized +environment variable named `x-b3-traceid`, even though that name normalizes to +`X_B3_TRACEID`. > [!NOTE] > This normalization is consistent with the environment variable naming rules From 14a33b26a2d4c08e96daf65b080b187a70b12cc3 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 9 Jun 2026 12:08:41 +0200 Subject: [PATCH 2/6] add PR number --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 61c1f4cf042..07e30bf5037 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ release. ([#5102](https://github.com/open-telemetry/opentelemetry-specification/pull/5102)) - Specify that environment variable propagation carriers only read and return normalized environment variable names. + ([#5144](https://github.com/open-telemetry/opentelemetry-specification/pull/5144)) ### Traces From 14f0c6ed0373137412d236851d8c16e7fa56c96c Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 9 Jun 2026 12:17:13 +0200 Subject: [PATCH 3/6] add start/end anchors in regex --- specification/context/env-carriers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index eca3f1dd465..8064a2ce757 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -69,7 +69,7 @@ propagation. To normalize a key name, carriers MUST: A normalized environment variable name is an environment variable name that is unchanged by applying this normalization. Equivalently, a normalized environment -variable name matches the regular expression `[A-Z_][A-Z0-9_]*`. +variable name matches the regular expression `^[A-Z_][A-Z0-9_]*$`. Environment variable names that do not match this pattern are non-normalized. From 7d481957c939fabf695d37a1571529b1c10c7821 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Wed, 10 Jun 2026 14:42:07 +0200 Subject: [PATCH 4/6] improve Supplementary Guidelines --- specification/context/env-carriers.md | 28 ++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 8064a2ce757..845358b78d2 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -135,15 +135,25 @@ process and with the correct permissions, can be accessed from other processes. > This section is non-normative and provides implementation > guidance only. It does not add requirements to the specification. -Language implementations of OpenTelemetry have flexibility in how they implement -environment variable context propagation. Language implementations can use the -existing `TextMapPropagator` directly with environment-specific carriers. -Typically implementations follow this pattern by providing: - -- `EnvironmentGetter` - creates an in-memory copy of the current environment - variables and reads context from that copy. -- `EnvironmentSetter` - writes context to a dictionary/map and provides the - dictionary/map to the application owner for them to use when spawning processes. +Language implementations of OpenTelemetry have flexibility in how they expose +environment variable context propagation. The existing `TextMapPropagator` can +be used with environment-specific carriers, environment-specific +[`Getter`](api-propagators.md#getter-argument) and +[`Setter`](api-propagators.md#setter-argument) implementations, or carrier types +that implement these operations themselves. Whichever component performs `Get`, +`Set`, or `Keys` for environment variables is responsible for the normalization +behavior described above. Language-specific helper components are only expected +to operate on the carrier shapes supported by that language implementation. +Implementations commonly provide one or more of the following: + +- `EnvironmentGetter` or equivalent - creates an in-memory copy of the current + environment variables and reads context from that copy. +- `EnvironmentSetter` or equivalent - writes context to a dictionary/map and + provides the dictionary/map to the application owner for them to use when + spawning processes. +- An environment-specific carrier type - implements environment variable `Get`, + `Set`, or `Keys` operations directly when the language combines carrier and + accessor APIs. Examples: From 06a55d5736d4174353b29ddeeba77c1ae2475dd8 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Wed, 10 Jun 2026 14:44:48 +0200 Subject: [PATCH 5/6] fix Key Name Normalization section --- specification/context/env-carriers.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 845358b78d2..18c866d3f3e 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -58,8 +58,9 @@ When using environment variables as carriers: ### Key Name Normalization -Environment variable carriers MUST normalize key names used for context -propagation. To normalize a key name, carriers MUST: +Language implementations MUST ensure that environment variable `Get`, `Set`, +and `Keys` operations use normalized key names for context propagation. To +normalize a key name, implementations MUST: - uppercase ASCII letters, - replace every character that is not an ASCII letter, digit, or underscore @@ -73,8 +74,8 @@ variable name matches the regular expression `^[A-Z_][A-Z0-9_]*$`. Environment variable names that do not match this pattern are non-normalized. -Carriers MUST use normalized key names consistently in `Get`, `Set`, and -`Keys` operations: +These requirements apply to whichever component implements the operation in a +language, such as a carrier, `Getter`, `Setter`, or other language-specific API: - `Set` MUST write values using the normalized form of the key provided by the propagator. @@ -82,11 +83,11 @@ Carriers MUST use normalized key names consistently in `Get`, `Set`, and normalized key name to read from the carrier. - `Keys` MUST return only key names that are already normalized. -For example, if a propagator requests the key `x-b3-traceid`, the environment -variable carrier MUST normalize the requested key to `X_B3_TRACEID` and read -the `X_B3_TRACEID` environment variable. It MUST NOT read a non-normalized -environment variable named `x-b3-traceid`, even though that name normalizes to -`X_B3_TRACEID`. +For example, if a propagator requests the key `x-b3-traceid`, the +environment-specific `Get` operation MUST normalize the requested key to +`X_B3_TRACEID` and read the `X_B3_TRACEID` environment variable. It MUST NOT +read a non-normalized environment variable named `x-b3-traceid`, even though +that name normalizes to `X_B3_TRACEID`. > [!NOTE] > This normalization is consistent with the environment variable naming rules From c9f2860e14de01cc69185dc478e141b6f38d67b5 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Wed, 10 Jun 2026 14:52:40 +0200 Subject: [PATCH 6/6] tidy --- specification/context/env-carriers.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 18c866d3f3e..e86278bc210 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -147,11 +147,10 @@ behavior described above. Language-specific helper components are only expected to operate on the carrier shapes supported by that language implementation. Implementations commonly provide one or more of the following: -- `EnvironmentGetter` or equivalent - creates an in-memory copy of the current - environment variables and reads context from that copy. -- `EnvironmentSetter` or equivalent - writes context to a dictionary/map and - provides the dictionary/map to the application owner for them to use when - spawning processes. +- `Getter` - creates an in-memory copy of the current environment variables and + reads context from that copy. +- `Setter` - writes context to a dictionary/map and provides the dictionary/map + to the application owner for them to use when spawning processes. - An environment-specific carrier type - implements environment variable `Get`, `Set`, or `Keys` operations directly when the language combines carrier and accessor APIs.