From 9061660143eeba02ea70bf8ac53ed3324eef7f38 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Tue, 10 Jun 2025 09:45:16 -0400 Subject: [PATCH 1/8] [spec] add supplementary guidance around context propagation using environment variables as carriers --- CHANGELOG.md | 8 +++++ specification/context/env-carriers.md | 45 +++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index aabb68ba04b..6ac0397702c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ release. ### Context +- Add Supplementary Guidance for environment variables as context carrier + specification. + ([#4484](https://github.com/open-telemetry/opentelemetry-specification/pull/4484)) + ### Traces ### Metrics @@ -17,6 +21,10 @@ release. ### Baggage +- Add Supplementary Guidance for environment variables as context carrier + specification. + ([#4484](https://github.com/open-telemetry/opentelemetry-specification/pull/4484)) + ### Resource ### Profiles diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 188c2881b87..b0f8d8572fd 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -5,6 +5,8 @@
Table of Contents + + - [Overview](#overview) @@ -129,6 +131,9 @@ When spawning child processes: - When spawning multiple child processes with different contexts or baggage, each child SHOULD receive its own copy of the environment variables with appropriate information. +- The onus is on the end-user for receiving the set context from the SDK and + passing it to it's own process spawning mechanism. The SDK SHOULD NOT handle + spawning processes for the end-user. #### Security @@ -149,3 +154,43 @@ Windows. - For maximum compatibility, implementations MUST: - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`). - Use the canonical case when setting environment variables. + +## Supplementary Guidelines + +> **IMPORTANT**: This section is non-normative and provides implementation +> guidance only. It does not add requirements to the specification. + +Language SDKs have flexibility in how they implement environment variable +context propagation. Two main approaches have been identified as viable. + +### Approach 1: Providing a dedicated `EnvironmentContextPropagator` + +SDKs can create a dedicated propagator for environment variables. For example, +the [Swift SDK][swift] implements a custom `EnvironmentContextPropagator` that +handles the environment-specific logic internally, in essence decorating the +`TextMapPropagator`. + +### Approach 2: Using the carriers directly through `Setters` and `Getters` + +SDKs can use the existing `TextMapPropagator` interface directly with +environment-specific carriers. Go and Python SDKs 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 end-user for them to use when spawning processes. + +### Common Behaviors + +Both approaches achieve the same outcome while offering different developer +experiences. SDK implementers may choose either approach based on their +language's idioms and ecosystem conventions. The behaviors in both approaches +are the same in that they: + +1. **Extract context**: Read from environment variables and delegate to the + configured `TextMapPropagator` (e.g., W3C, B3) for parsing +2. **Inject context**: Return a dictionary/map of environment variables that + users can pass to their process spawning libraries + +[swift]: https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Trace/Propagation/EnvironmentContextPropagator.swift From 558d3b42f0a7123170f55e64e15d9612fab9dca0 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Tue, 10 Jun 2025 09:52:18 -0400 Subject: [PATCH 2/8] chore: update changelog and run toc --- CHANGELOG.md | 4 ++-- specification/context/env-carriers.md | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ac0397702c..8211739d52c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ release. - Add Supplementary Guidance for environment variables as context carrier specification. - ([#4484](https://github.com/open-telemetry/opentelemetry-specification/pull/4484)) + ([#4548](https://github.com/open-telemetry/opentelemetry-specification/pull/4548)) ### Traces @@ -23,7 +23,7 @@ release. - Add Supplementary Guidance for environment variables as context carrier specification. - ([#4484](https://github.com/open-telemetry/opentelemetry-specification/pull/4484)) + ([#4548](https://github.com/open-telemetry/opentelemetry-specification/pull/4548)) ### Resource diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index b0f8d8572fd..1f8001e52a2 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -21,6 +21,10 @@ + [Process Spawning](#process-spawning) + [Security](#security) + [Case Sensitivity](#case-sensitivity) +- [Supplementary Guidelines](#supplementary-guidelines) + * [Approach 1: Providing a dedicated `EnvironmentContextPropagator`](#approach-1-providing-a-dedicated-environmentcontextpropagator) + * [Approach 2: Using the carriers directly through `Setters` and `Getters`](#approach-2-using-the-carriers-directly-through-setters-and-getters) + * [Common Behaviors](#common-behaviors) From a451875105166babf0f28d2b98da6ab581197638 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Fri, 20 Jun 2025 12:47:03 -0400 Subject: [PATCH 3/8] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- 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 1f8001e52a2..bc2dc3b5d6d 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -164,19 +164,19 @@ Windows. > **IMPORTANT**: This section is non-normative and provides implementation > guidance only. It does not add requirements to the specification. -Language SDKs have flexibility in how they implement environment variable +Language implementations of OpenTelemetry have flexibility in how they implement environment variable context propagation. Two main approaches have been identified as viable. ### Approach 1: Providing a dedicated `EnvironmentContextPropagator` SDKs can create a dedicated propagator for environment variables. For example, -the [Swift SDK][swift] implements a custom `EnvironmentContextPropagator` that +the [OTel Swift][swift] implements a custom `EnvironmentContextPropagator` that handles the environment-specific logic internally, in essence decorating the `TextMapPropagator`. ### Approach 2: Using the carriers directly through `Setters` and `Getters` -SDKs can use the existing `TextMapPropagator` interface directly with +Language implementations can use the existing `TextMapPropagator` interface directly with environment-specific carriers. Go and Python SDKs follow this pattern by providing: @@ -188,7 +188,7 @@ providing: ### Common Behaviors Both approaches achieve the same outcome while offering different developer -experiences. SDK implementers may choose either approach based on their +experiences. Language implementations may choose either approach based on their language's idioms and ecosystem conventions. The behaviors in both approaches are the same in that they: From c41663adf330d6c242ea10ca49ad8329091f2d93 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Thu, 26 Jun 2025 09:31:21 -0400 Subject: [PATCH 4/8] Update specification/context/env-carriers.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- 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 cdddb70f38d..915b4990b18 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -136,8 +136,8 @@ When spawning child processes: each child SHOULD receive its own copy of the environment variables with appropriate information. - The onus is on the end-user for receiving the set context from the SDK and - passing it to it's own process spawning mechanism. The SDK SHOULD NOT handle - spawning processes for the end-user. + passing it to it's own process spawning mechanism. The language implementations MUST NOT handle + spawning processes. #### Security From b2fa7afd58acdcf49a5b988b3c28e2e55d8f2928 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Thu, 26 Jun 2025 09:43:46 -0400 Subject: [PATCH 5/8] chore: make adjustments to application owners --- 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 915b4990b18..a1c4c3eb892 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -135,9 +135,9 @@ When spawning child processes: - When spawning multiple child processes with different contexts or baggage, each child SHOULD receive its own copy of the environment variables with appropriate information. -- The onus is on the end-user for receiving the set context from the SDK and - passing it to it's own process spawning mechanism. The language implementations MUST NOT handle - spawning processes. +- The onus is on the application owner for receiving the set context from the + SDK and passing it to it's own process spawning mechanism. The language + implementations MUST NOT handle spawning processes. #### Security @@ -164,8 +164,9 @@ Windows. > **IMPORTANT**: 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. Two main approaches have been identified as viable. +Language implementations of OpenTelemetry have flexibility in how they implement +environment variable context propagation. Two main approaches have been +identified as viable. ### Approach 1: Providing a dedicated `EnvironmentContextPropagator` @@ -183,7 +184,7 @@ 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 end-user for them to use when spawning processes. + dictionary/map to the application owner for them to use when spawning processes. ### Common Behaviors @@ -195,6 +196,6 @@ are the same in that they: 1. **Extract context**: Read from environment variables and delegate to the configured `TextMapPropagator` (e.g., W3C, B3) for parsing 2. **Inject context**: Return a dictionary/map of environment variables that - users can pass to their process spawning libraries + application owners can pass to their process spawning libraries [swift]: https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Trace/Propagation/EnvironmentContextPropagator.swift From 35fc92360f2ae9774a56cbf4cc3c152382d4c7c3 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Tue, 1 Jul 2025 09:25:35 -0400 Subject: [PATCH 6/8] Update specification/context/env-carriers.md Co-authored-by: Liudmila Molkova --- 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 a1c4c3eb892..876ba7f1b1b 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -136,7 +136,7 @@ When spawning child processes: each child SHOULD receive 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 it's own process spawning mechanism. The language + SDK and passing it to its own process spawning mechanism. The language implementations MUST NOT handle spawning processes. #### Security From 82c616faae46fa06561030567b518308b3f91c00 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Thu, 3 Jul 2025 10:40:50 -0400 Subject: [PATCH 7/8] chore: minor changes based on feedback --- CHANGELOG.md | 4 ++-- specification/context/env-carriers.md | 12 +++++++++--- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 01c227622d2..23a27cd2a00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ release. ### Context -- Add Supplementary Guidance for environment variables as context carrier +- Add Supplementary Guidelines for environment variables as context carrier specification. ([#4548](https://github.com/open-telemetry/opentelemetry-specification/pull/4548)) @@ -36,7 +36,7 @@ release. ### Baggage -- Add Supplementary Guidance for environment variables as context carrier +- Add Supplementary Guidelines for environment variables as context carrier specification. ([#4548](https://github.com/open-telemetry/opentelemetry-specification/pull/4548)) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index e7d7e74cdf3..701f2d8cabd 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -5,8 +5,6 @@
Table of Contents - - - [Overview](#overview) @@ -186,6 +184,14 @@ providing: - `EnvironmentSetter` - writes context to a dictionary/map and provides the dictionary/map to the application owner for them to use when spawning processes. +Examples: + +- [OpenTelemetry Prototype Go Implementation][gi] +- [OpenTelemetry Prototype Python Implementation][pi] + +[gi]: https://github.com/open-telemetry/opentelemetry-go/pull/6778 +[pi]: https://github.com/open-telemetry/opentelemetry-python/pull/4609 + ### Common Behaviors Both approaches achieve the same outcome while offering different developer @@ -194,7 +200,7 @@ language's idioms and ecosystem conventions. The behaviors in both approaches are the same in that they: 1. **Extract context**: Read from environment variables and delegate to the - configured `TextMapPropagator` (e.g., W3C, B3) for parsing + configured `TextMapPropagator` (e.g. W3C, B3) for parsing 2. **Inject context**: Return a dictionary/map of environment variables that application owners can pass to their process spawning libraries From b8861986eba145ad990421b77b606842c25c6115 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Thu, 3 Jul 2025 10:44:01 -0400 Subject: [PATCH 8/8] chore: fix markdown --- 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 701f2d8cabd..77ba64a6f20 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -184,7 +184,7 @@ providing: - `EnvironmentSetter` - writes context to a dictionary/map and provides the dictionary/map to the application owner for them to use when spawning processes. -Examples: +Examples: - [OpenTelemetry Prototype Go Implementation][gi] - [OpenTelemetry Prototype Python Implementation][pi]