From 7dca5715fee0e4cddc5bb325fffc124e37ce80d1 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 13 Mar 2026 20:29:09 +0100 Subject: [PATCH 1/5] Align environment variable context propagation name restrictions with POSIX.1-2024 --- CHANGELOG.md | 4 ++++ specification/context/env-carriers.md | 13 +++++++------ 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bcd4f0e32cd..dc51c978ddd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ release. ### Context +- Align environment variable context propagation name restrictions with POSIX.1-2024 + and define normalization behavior. + ([#4914](https://github.com/open-telemetry/opentelemetry-specification/issues/4914)) + ### Traces ### Metrics diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 1c5476bf234..5926563056c 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -77,12 +77,13 @@ configuration options to override the default environment variable. Environment variable names used for context propagation: -- SHOULD use uppercase letters, digits, and underscores for maximum - cross-platform compatibility -- MUST NOT include characters forbidden in environment variables per - platform-specific restrictions -- SHOULD follow naming conventions that align with the propagation format - specification they're implementing (e.g., `TRACEPARENT` for W3C trace context) +- SHOULD follow [POSIX.1-2024](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) + by using only ASCII uppercase letters, digits, and the underscore (`_`), and + MUST NOT begin with a digit. +- It is RECOMMENDED that the propagation key is normalized to a valid + environment variable name by uppercasing ASCII letters, replacing all other + disallowed characters with underscore (`_`), and prefixing the name with an + underscore (`_`) if it would otherwise start with an ASCII digit. #### Value Restrictions From 3edc7d0c36551ac4c6b6f1a718e5f8313ca4aae5 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 13 Mar 2026 21:00:14 +0100 Subject: [PATCH 2/5] MUST for deterministic behavior --- specification/context/env-carriers.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 5926563056c..24eab438c3c 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -77,13 +77,14 @@ configuration options to override the default environment variable. Environment variable names used for context propagation: -- SHOULD follow [POSIX.1-2024](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) - by using only ASCII uppercase letters, digits, and the underscore (`_`), and - MUST NOT begin with a digit. -- It is RECOMMENDED that the propagation key is normalized to a valid - environment variable name by uppercasing ASCII letters, replacing all other - disallowed characters with underscore (`_`), and prefixing the name with an - underscore (`_`) if it would otherwise start with an ASCII digit. +- MUST be normalized to a valid environment variable name by uppercasing ASCII + letters, replacing all other disallowed characters with underscore (`_`), and + prefixing the name with an underscore (`_`) if it would otherwise start with + an ASCII digit. + +> [!NOTE] +> This normalization is consistent with the environment variable naming rules +> defined in [POSIX.1-2024](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html). #### Value Restrictions From 842ebb87ae71a2bb1efd704c3f9f5250c8bb9efd Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 13 Mar 2026 21:08:40 +0100 Subject: [PATCH 3/5] clarify --- specification/context/env-carriers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 24eab438c3c..606df635d18 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -77,10 +77,10 @@ configuration options to override the default environment variable. Environment variable names used for context propagation: -- MUST be normalized to a valid environment variable name by uppercasing ASCII - letters, replacing all other disallowed characters with underscore (`_`), and - prefixing the name with an underscore (`_`) if it would otherwise start with - an ASCII digit. +- MUST be normalized by uppercasing ASCII letters, replacing every character + that is not an ASCII uppercase letter, digit, or underscore (`_`) with + underscore (`_`), and prefixing the name with an underscore (`_`) if it would + otherwise start with an ASCII digit. > [!NOTE] > This normalization is consistent with the environment variable naming rules From c7a1196d6b149e9edefa9a6a8e961189582ec3c5 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 13 Mar 2026 21:13:25 +0100 Subject: [PATCH 4/5] make the normalization more clear --- specification/context/env-carriers.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 606df635d18..ef610f6b91a 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -77,10 +77,12 @@ configuration options to override the default environment variable. Environment variable names used for context propagation: -- MUST be normalized by uppercasing ASCII letters, replacing every character - that is not an ASCII uppercase letter, digit, or underscore (`_`) with - underscore (`_`), and prefixing the name with an underscore (`_`) if it would - otherwise start with an ASCII digit. +- MUST be normalized by: + - uppercasing ASCII letters, + - replacing every character that is not an ASCII letter, digit, or underscore + (`_`) with underscore (`_`), + - prefixing the name with an underscore (`_`) if it would otherwise start with + an ASCII digit. > [!NOTE] > This normalization is consistent with the environment variable naming rules From 757c39d13e5cbcb081a9deded9e8020527ba4c40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 13 Mar 2026 21:40:05 +0100 Subject: [PATCH 5/5] Update specification/context/env-carriers.md Co-authored-by: Tyler Yahn --- 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 ef610f6b91a..98808840b9b 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -80,7 +80,7 @@ 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 underscore (`_`), + (`_`) with an underscore (`_`), - prefixing the name with an underscore (`_`) if it would otherwise start with an ASCII digit.