From ec996725352824a9584829fc365c2a8082f6705d Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 18 Jun 2026 15:38:59 +0200 Subject: [PATCH 01/10] Make environment variable propagation operational guidance non-normative --- CHANGELOG.md | 2 ++ specification/context/env-carriers.md | 43 +++++++++++++++------------ 2 files changed, 26 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b495ab2dcbc..3d4ac8afdbe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. - Specify that environment variable propagation carriers only read and return normalized environment variable names. ([#5144](https://github.com/open-telemetry/opentelemetry-specification/pull/5144)) +- Clarify that environment variable propagation operational guidance is + non-normative and should be documented by language implementations. ### Traces diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index e86278bc210..d5727de6a84 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -95,40 +95,45 @@ that name normalizes to `X_B3_TRACEID`. ### Operational Guidance +Language implementations SHOULD document operational guidance for environment +variable context propagation, including initialization-time extraction, child +process environment handling, and security considerations. + #### Environment Variable Immutability -Once set for a process, environment variables SHOULD be treated as immutable -within that process: +Context-related environment variables are best treated as process-startup input: -- Applications SHOULD read context-related environment variables during +- Applications should read context-related environment variables during initialization. -- Applications SHOULD NOT modify context-related environment variables of the - environment in which the parent process exists. +- Applications should not modify context-related environment variables + of the environment in which the parent process exists. #### Process Spawning When spawning child processes: -- Parent processes SHOULD copy the current environment variables (if - applicable), modify, and inject context when spawning child processes. -- Child processes SHOULD extract context from environment variables at startup. +- Parent processes should copy the current environment variables (if + applicable), modify that copy, and inject context into the copy when spawning + child processes. +- Child processes should extract context from environment variables at + startup. - When spawning multiple child processes with different contexts or baggage, - each child SHOULD receive its own copy of the environment variables with + each child should receives its own copy of the environment variables with appropriate information. -- The onus is on the application owner for receiving the set context from the - SDK and passing it to its own process spawning mechanism. The language - implementations MUST NOT handle spawning processes. +- Application code remains responsible for receiving context from the SDK and + passing it to the application's process spawning mechanism. #### Security Environment variables are generally accessible to all code running within a -process and with the correct permissions, can be accessed from other processes. - -- Implementations SHOULD NOT store sensitive information in environment - variables. -- Applications running in multi-tenant environments SHOULD be aware that - environment variables may be visible to other processes or users with - appropriate permissions. +process. On many systems, they can also be accessed by other processes or users +with appropriate permissions. + +- Context propagation via environment variables is not appropriate for sensitive + information. +- Applications running in multi-tenant environments account for environment + variables being visible to other processes or users with appropriate + permissions. ## Supplementary Guidelines From 6b39376b2b8ef5610a3a0756bdc702e02978ef29 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 18 Jun 2026 15:41:16 +0200 Subject: [PATCH 02/10] add PR number --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d4ac8afdbe..4ca35f4a398 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ release. ([#5144](https://github.com/open-telemetry/opentelemetry-specification/pull/5144)) - Clarify that environment variable propagation operational guidance is non-normative and should be documented by language implementations. + ([#5165](https://github.com/open-telemetry/opentelemetry-specification/pull/5165)) ### Traces From c4d58a36ba40e66452db46f13c9b6be0dd4654e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 18 Jun 2026 15:46:15 +0200 Subject: [PATCH 03/10] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- 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 d5727de6a84..60d73df3a98 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -131,7 +131,7 @@ with appropriate permissions. - Context propagation via environment variables is not appropriate for sensitive information. -- Applications running in multi-tenant environments account for environment +- Applications running in multi-tenant environments should account for environment variables being visible to other processes or users with appropriate permissions. From 50d968fa287fbc03eb0414ed73e77d70e85e3cef Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 18 Jun 2026 15:47:10 +0200 Subject: [PATCH 04/10] fix gramar --- 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 60d73df3a98..6cf38240e8d 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -118,7 +118,7 @@ When spawning child processes: - Child processes should extract context from environment variables at startup. - When spawning multiple child processes with different contexts or baggage, - each child should receives its own copy of the environment variables with + each child should receive its own copy of the environment variables with appropriate information. - Application code remains responsible for receiving context from the SDK and passing it to the application's process spawning mechanism. From b5aac3c3d13cf9c2f6e87326bb064076b7dedbfe Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 18 Jun 2026 15:50:03 +0200 Subject: [PATCH 05/10] fmt --- specification/context/env-carriers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 6cf38240e8d..c98e6cf37aa 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -131,9 +131,9 @@ with appropriate permissions. - Context propagation via environment variables is not appropriate for sensitive information. -- Applications running in multi-tenant environments should account for environment - variables being visible to other processes or users with appropriate - permissions. +- Applications running in multi-tenant environments should account for + environment variables being visible to other processes or users with + appropriate permissions. ## Supplementary Guidelines From a6cbb14974e70cc59d1e790a94dc612248418c46 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 18 Jun 2026 21:09:20 +0200 Subject: [PATCH 06/10] add note that Operational Guidance is non-normative --- specification/context/env-carriers.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index c98e6cf37aa..eb5e6b123a6 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -56,6 +56,11 @@ When using environment variables as carriers: - validating and parsing values - applying any truncation or other format-specific behaviors +Language implementations SHOULD document +[operational guidance](#operational-guidance) for environment variable context +propagation, including initialization-time extraction, child process environment +handling, and security considerations. + ### Key Name Normalization Language implementations MUST ensure that environment variable `Get`, `Set`, @@ -95,9 +100,9 @@ that name normalizes to `X_B3_TRACEID`. ### Operational Guidance -Language implementations SHOULD document operational guidance for environment -variable context propagation, including initialization-time extraction, child -process environment handling, and security considerations. +> [!IMPORTANT] +> This section is non-normative and provides usage guidance only. It does not +> add requirements to the specification. #### Environment Variable Immutability From daa08bdc870548e28e4c13b0a2d9ed7a917d9288 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 18 Jun 2026 21:11:32 +0200 Subject: [PATCH 07/10] shorten --- specification/context/env-carriers.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index eb5e6b123a6..63fcee8830d 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -57,9 +57,8 @@ When using environment variables as carriers: - applying any truncation or other format-specific behaviors Language implementations SHOULD document -[operational guidance](#operational-guidance) for environment variable context -propagation, including initialization-time extraction, child process environment -handling, and security considerations. +[operational guidance](#operational-guidance), including initialization-time +extraction, child process environment handling, and security considerations. ### Key Name Normalization From 920f7e1855ad62702e93560b5c30d3ea62f0c414 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 18 Jun 2026 21:20:02 +0200 Subject: [PATCH 08/10] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- specification/context/env-carriers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 63fcee8830d..5786aa8435b 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -109,8 +109,8 @@ Context-related environment variables are best treated as process-startup input: - Applications should read context-related environment variables during initialization. -- Applications should not modify context-related environment variables - of the environment in which the parent process exists. +- Applications should not modify context-related environment variables in the + environment in which the parent process exists. #### Process Spawning From 14062f119c1ed4069f95f8ef50c07df4ef02e07e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 22 Jun 2026 21:45:22 +0200 Subject: [PATCH 09/10] Update specification/context/env-carriers.md Co-authored-by: Tyler Yahn --- specification/context/env-carriers.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index ca4dee7f67e..23f16e601c3 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -60,6 +60,9 @@ Language implementations SHOULD document [operational guidance](#operational-guidance), including initialization-time extraction, child process environment handling, and security considerations. +Language implementations MUST NOT spawn child processes as part of environment +variable context propagation. + ### Key Name Normalization Language implementations MUST ensure that environment variable `Get`, `Set`, From 43ef5ec8b50e1a40d0973e39c5df96befc527fba Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 22 Jun 2026 21:58:05 +0200 Subject: [PATCH 10/10] Avoid RFC 2119 wording --- specification/context/env-carriers.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 23f16e601c3..0dd1d22524b 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -112,23 +112,23 @@ that name normalizes to `X_B3_TRACEID`. Context-related environment variables are best treated as process-startup input: -- Applications should read context-related environment variables during +- Applications typically read context-related environment variables during initialization. -- Applications should not modify context-related environment variables in the +- Applications avoid modifying context-related environment variables in the environment in which the parent process exists. #### Process Spawning When spawning child processes: -- Parent processes should copy the current environment variables (if - applicable), modify that copy, and inject context into the copy when spawning - child processes. -- Child processes should extract context from environment variables at - startup. -- When spawning multiple child processes with different contexts or baggage, - each child should receive its own copy of the environment variables with - appropriate information. +- A typical parent process flow copies the current environment variables (if + applicable), modifies that copy, and injects context into the copy when + spawning child processes. +- Child-process startup is the point where context is extracted from + environment variables. +- For multiple child processes with different contexts or baggage, separate + environment variable copies keep the appropriate information isolated per + child process. - Application code remains responsible for receiving context from the SDK and passing it to the application's process spawning mechanism. @@ -140,9 +140,8 @@ with appropriate permissions. - Context propagation via environment variables is not appropriate for sensitive information. -- Applications running in multi-tenant environments should account for - environment variables being visible to other processes or users with - appropriate permissions. +- Multi-tenant environments have extra exposure risk when environment variables + are visible to other processes or users with appropriate permissions. ## Supplementary Guidelines