From dc81e8f8245e2a717032b0d5f8228d5abd70b397 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 19 Jun 2026 07:38:41 +0200 Subject: [PATCH 1/7] Cleanup implementation guidelines for environment variable propagation carriers --- CHANGELOG.md | 3 +++ specification/context/env-carriers.md | 19 +++++-------------- 2 files changed, 8 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b495ab2dcbc..30750af1500 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ 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)) +- Cleanup implementation guidelines for environment variable propagation + carriers. + ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) ### Traces diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index e86278bc210..f23a2f7d0eb 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -14,7 +14,7 @@ + [Environment Variable Immutability](#environment-variable-immutability) + [Process Spawning](#process-spawning) + [Security](#security) -- [Supplementary Guidelines](#supplementary-guidelines) +- [Implementation Guidelines](#implementation-guidelines) @@ -130,11 +130,11 @@ process and with the correct permissions, can be accessed from other processes. environment variables may be visible to other processes or users with appropriate permissions. -## Supplementary Guidelines +## Implementation Guidelines > [!IMPORTANT] -> This section is non-normative and provides implementation -> guidance only. It does not add requirements to the specification. +> 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 expose environment variable context propagation. The existing `TextMapPropagator` can @@ -145,17 +145,8 @@ 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: -- `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. - -Examples: +Example implementations: - [OpenTelemetry .NET implementation][di] - [OpenTelemetry C++ implementation][ci] From 5334498f1d16d164b5d6a5417af397bbc7374786 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 19 Jun 2026 07:42:14 +0200 Subject: [PATCH 2/7] Update PR number --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30750af1500..e64ab56314a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ release. ([#5144](https://github.com/open-telemetry/opentelemetry-specification/pull/5144)) - Cleanup implementation guidelines for environment variable propagation carriers. - ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) + ([#5166](https://github.com/open-telemetry/opentelemetry-specification/pull/5166)) ### Traces From 7d1adb6443650d5b670ef3fe93ffaa43c67d221d Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 19 Jun 2026 07:43:52 +0200 Subject: [PATCH 3/7] add JS implementation --- specification/context/env-carriers.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index f23a2f7d0eb..efbbf723a53 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -152,6 +152,7 @@ Example implementations: - [OpenTelemetry C++ implementation][ci] - [OpenTelemetry Go implementation][gi] - [OpenTelemetry Java implementation][ji] +- [OpenTelemetry JavaScript implementation][jsi] - [OpenTelemetry Python implementation][pi] - [OpenTelemetry Swift implementation][si] @@ -159,5 +160,6 @@ Example implementations: [ci]: https://github.com/open-telemetry/opentelemetry-cpp/blob/main/api/include/opentelemetry/context/propagation/environment_carrier.h [gi]: https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/propagators/envcar [ji]: https://github.com/open-telemetry/opentelemetry-java/tree/main/api/incubator/src/main/java/io/opentelemetry/api/incubator/propagation +[jsi]: https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-propagator-env-carrier [pi]: https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-api/src/opentelemetry/propagators/_envcarrier.py [si]: https://github.com/open-telemetry/opentelemetry-swift-core/blob/main/Sources/OpenTelemetrySdk/Trace/Propagation/EnvironmentContextPropagator.swift From 3df39209cb2ac1afb808896e506236e153a19396 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 19 Jun 2026 07:59:52 +0200 Subject: [PATCH 4/7] "cleanup" -> "clean up" --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e64ab56314a..7c21e23c2f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,7 @@ 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)) -- Cleanup implementation guidelines for environment variable propagation +- Clean up implementation guidelines for environment variable propagation carriers. ([#5166](https://github.com/open-telemetry/opentelemetry-specification/pull/5166)) From fef9b99631244b99e21a02143752515820ea85dd Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 19 Jun 2026 10:37:45 +0200 Subject: [PATCH 5/7] add caching --- specification/context/env-carriers.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index efbbf723a53..f9d96267a8e 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -146,6 +146,12 @@ that implement these operations themselves. Whichever component performs `Get`, behavior described above. Language-specific helper components are only expected to operate on the carrier shapes supported by that language implementation. +Implementations may consider a caching behavior that fits their API shape. For example, an implementation can: + +- Load environment variables whose names are already normalized into a cache + during initialization or on first use. +- Cache the results of individual `Get` lookups by normalized key. + Example implementations: - [OpenTelemetry .NET implementation][di] From 8b7b9f25337494329e213f2be86651c78596539d Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Fri, 19 Jun 2026 10:38:40 +0200 Subject: [PATCH 6/7] fmt --- specification/context/env-carriers.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index f9d96267a8e..254f708f66f 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -146,7 +146,8 @@ that implement these operations themselves. Whichever component performs `Get`, behavior described above. Language-specific helper components are only expected to operate on the carrier shapes supported by that language implementation. -Implementations may consider a caching behavior that fits their API shape. For example, an implementation can: +Implementations may consider a caching behavior that fits their API shape. For +example, an implementation can: - Load environment variables whose names are already normalized into a cache during initialization or on first use. From 1b987e74c491e819398fc246dce975a5a4003665 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 22 Jun 2026 22:58:56 +0200 Subject: [PATCH 7/7] avoid RFC wording --- 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 44c6c065715..10fa7e91797 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -148,7 +148,7 @@ that implement these operations themselves. Whichever component performs `Get`, behavior described above. Language-specific helper components are only expected to operate on the carrier shapes supported by that language implementation. -Implementations may consider a caching behavior that fits their API shape. For +Implementations can consider a caching behavior that fits their API shape. For example, an implementation can: - Load environment variables whose names are already normalized into a cache