From 4baa2807bf5f6f7da4f7c884801d00d8acb323ff Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 18 May 2026 14:04:54 +0200 Subject: [PATCH 1/5] Clarify environment carrier key normalization --- CHANGELOG.md | 3 +++ specification/context/env-carriers.md | 10 ++++++++++ 2 files changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a540179de44..2a153c22bc0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,9 @@ release. ### Context +- Clarify that environment variable propagation carriers normalize both + requested keys and carrier keys when extracting context. + ### Traces ### Metrics diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 25660a4a76b..5478a34a8b2 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -66,6 +66,16 @@ 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 both get and set operations: + - when injecting context, the carrier MUST write values using the normalized + form of the key provided by the propagator, + - when extracting context, the carrier MUST normalize the key requested by the + propagator and the key names present in the carrier before matching them. + +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 From 4b989c47b2da6eb1505b2e983cb6280ee62f5584 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 18 May 2026 14:10:56 +0200 Subject: [PATCH 2/5] Clarify environment carrier key normalization behavior --- CHANGELOG.md | 4 ++-- specification/context/env-carriers.md | 6 ++++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a153c22bc0..6a827462180 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,8 @@ release. ### Context -- Clarify that environment variable propagation carriers normalize both - requested keys and carrier keys when extracting context. +- Clarify that environment variable propagation carriers normalize requested + keys, carrier keys, and returned keys. ### Traces diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 5478a34a8b2..bb9ea2e246f 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -66,11 +66,13 @@ 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 both get and set operations: +- MUST be normalized consistently by get, set, and keys operations: - when injecting context, the carrier MUST write values using the normalized form of the key provided by the propagator, - when extracting context, the carrier MUST normalize the key requested by the - propagator and the key names present in the carrier before matching them. + propagator and the key names present in the carrier before matching them, + - 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 From 0a04d6b34b4284e9f6555872c8524593d46b6b06 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 18 May 2026 14:48:00 +0200 Subject: [PATCH 3/5] add PR number --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a827462180..e709e5dbf11 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ 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)) ### Traces From f2db014cf5865b9fce3e77f481ca735e47ba95d6 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 18 May 2026 15:03:56 +0200 Subject: [PATCH 4/5] refer to propagator operation names --- specification/context/env-carriers.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index bb9ea2e246f..46f45bc2985 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -66,11 +66,12 @@ 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 MUST write values using the normalized - form of the key provided by the propagator, - - when extracting context, the carrier MUST normalize the key requested by the - propagator and the key names present in the carrier before matching them, +- 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, - when listing keys, the carrier `Keys` function MUST return normalized key names. From 2e506cfa1a2f78e83a11423ba07550373ca3f345 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 19 May 2026 16:52:06 +0200 Subject: [PATCH 5/5] Update specification/context/env-carriers.md --- specification/context/env-carriers.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 46f45bc2985..28260191aa6 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -71,7 +71,9 @@ Environment variable names used for context propagation: 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, + 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.