[spec] add `EnvVarPropagator` decorator for env variable context #4484

adrielp · 2025-04-20T16:24:34Z

propagation

Changes

Changelog has been updated to reflect that addition of the EnvVarPropagator decorator for the TextMapPropagator

Related issues #
Related OTEP 0258
CHANGELOG.md file updated for non-trivial changes

propagation

adrielp · 2025-04-20T16:27:01Z

Again, I tried to keep it very simple. I would love some feedback around the description of the decorator, and feedback from experts in the Python, Go, and Swift SDK's for what the simple examples provide.

specification/context/env-carriers.md

Co-authored-by: Reiley Yang <[email protected]>

scherepiuk · 2025-04-24T11:06:41Z

specification/context/env-carriers.md

+    ...
+}
+
+type EnvVarPropagator func(TextMapPropagator) TextMapPropagator


I'm a little confused by the type selection in this example. What do you think about using embedding here like so?

type EnvVarPropagator struct { TextMapPropagator }

scherepiuk · 2025-04-24T11:14:44Z

specification/context/env-carriers.md

+func (envp EnvVarPropagator) Inject(ctx context.Context, carrier TextMapCarrier) {
+    env := os.Environ()
+    // Inject context into environment variable copy
+    ...
+}


I'm not too familiar with the Propagators API, but I noticed the Inject method in the TextMapPropagator interface doesn't return anything. So I'm curious what future implementors should do with the scoped copy of environment variables? Set them to the mutable carrier?

pellared · 2025-04-24T13:37:39Z

I will do my best to review next week.

pellared · 2025-04-28T12:55:41Z

specification/context/env-carriers.md

+```go
+type TextMapPropagator interface {
+    // Includes Inject, Extract, and Fields
+    ...
+}
+
+type EnvVarPropagator func(TextMapPropagator) TextMapPropagator
+
+func (envp EnvVarPropagator) Inject(ctx context.Context, carrier TextMapCarrier) {
+    env := os.Environ()
+    // Inject context into environment variable copy
+    ...
+}
+
+func (envp EnvVarPropagator) Extract(ctx context.Context, carrier TextMapCarrier) context.Context {
+    // Extract context from environment variables
+    ...
+}
+...
+```


This doesn't currently demonstrate the intended concept. Could you create a prototype (e.g., a draft PR) in https://github.com/open-telemetry/opentelemetry-go instead?

Also, the current design isn't quite convincing. Shouldn't we be implementing a TextMapCarrier that works with environment variables? After all, the document is titled "Environment Variables as Context Propagation Carriers", which strongly suggests that direction.

pellared · 2025-04-28T12:57:33Z

specification/context/env-carriers.md

+### Environment Variable Propagator Decorator
+
+The `EnvVarPropagator` is a [decorator][dec] that wraps a `TextMapPropagator`,
+handling the injection and extraction of context and baggage into and from
+environment variables.
+
+The `EnvVarPropagator` SHOULD be configurable to match platform-specific
+restrictions and handle environment variable naming conventions as described in
+the [Environment Variable Names](#environment-variable-names) and [Format
+Restrictions](#format-restrictions) sections.


I do not understand why we need a propagator decorator. Isn't this something that is needed for Python propagator design?

Don't we simply need a new carrier implementation where environmental variables are the medium?

PTAL open-telemetry/opentelemetry-go#6778

jsuereth · 2025-05-05T11:57:20Z

specification/context/env-carriers.md

+the [Environment Variable Names](#environment-variable-names) and [Format
+Restrictions](#format-restrictions) sections.
+
+The `EnvVarPropagator` MAY define an `EnvVarCarrier` type that implements the


I'd like to see some implementations of this across languages.

My suspicion is that there is not a great abstraction around ENV + fork() you can use here, so instead I think non-normative recommendations for how to use TextMapPropagator and then language-specific implementations may be better.

carlosalberto · 2025-05-14T15:52:50Z

Ping @adrielp

adrielp · 2025-05-14T18:33:11Z

I haven't forgotten about this, just been thinking about the comments and been out-of-band. I recently wrote a working version in Python that I'd like to discuss (and can open a draft PR). I've also looked through the Go source code for how context propagation works. I'd like to discuss this next week (May 20, 2025) during the SIG call in depth.

Due to language implementation details, I think I'm concerned about saying the environment is the carrier, without a dedicated wrapper. Based on the spec, there are things to be aware of that just does not seem to be best implemented at the carrier layer, but instead within a propagators natural inject/extra methods.

One example was in the original Python prototype. The extract_from_environment method used os.environ (the ACTUAL Python object) as the carrier passed into the TextMap formatter. I think there are a few things wrong with this approach.

I'll try to get a simple prototype if I can find some time in Go before the spec call. Will respond to the other comments individually, but most is encompassed here. I will add the talking item to the next calls. Thanks for bearing with my low bandwidth here!

pellared · 2025-05-15T09:48:54Z

I recently wrote a working version in Python that I'd like to discuss (and can open a draft PR)

I think it would be good to open it to get feedback from Python maintainers before the SIG meeting.

I've also looked through the Go source code for how context propagation works.

I created a prototype in Go which implements the feature by creating a new carrier: open-telemetry/opentelemetry-go#6778.

Due to language implementation details, I think I'm concerned about saying the environment is the carrier, without a dedicated wrapper.

As you said, this is an implementation detail. From the specification perspective, we just need an carrier. If some languages need a new propagator for each carrier then it was SIG's decision to model it that way. For instance, I have totally no idea why the carrier in Go has a Keys method, but ship has sailed 😉

adrielp · 2025-05-15T12:39:35Z

@pellared - thanks for the context on prior art within the Go SIG. Super looking forward to reading your prototype, appreciate you taking the initiative to put it together!!

github-actions · 2025-05-23T03:30:40Z

This PR was marked stale due to lack of activity. It will be closed in 7 days.

tylerbenson · 2025-05-28T15:09:22Z

specification/context/env-carriers.md

+The `EnvVarPropagator` is a [decorator][dec] that wraps a `TextMapPropagator`,
+handling the injection and extraction of context and baggage into and from
+environment variables.


This document doesn't really address things like interactions with span linking and configuration of the global propagators. There are some difficult details that we had to deal with for the X-Ray Lambda Propagator.

adrielp · 2025-06-02T23:16:18Z

based on the above and the conversations in slack, I added a related PR in the python SDK for env carrier. open-telemetry/opentelemetry-python#4609

adrielp · 2025-06-03T20:47:41Z

The scope of documented information and propagation has diverged from the original intent of this pull request. I will be closing this pull request so that it's original intent is still available for historical context, then I will open a new pull request that provides supplementary guidelines for language implementations. There are now two prototype draft pull requests in Python & Go that will be updated to reflect the new guidelines.

tylerbenson · 2025-06-04T13:46:18Z

I still think having an env var propagation spec is useful, but there are some weird API edge cases, specifically with how it may interact with span linking and the global propagator. One way to mitigate those problems is by creating span links from all propagators in the chain that differ from the last one, but that also requires a spec change.

## Changes Adds supplementary guidance around the behaviors the SDKs should look to implement. * [x] Related issues [#4470](#4470) & #4484 * [x] Related [OTEP 0258](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0258-env-context-baggage-carriers.md) * [x] Links to the prototypes (when adding or changing features) - [Go](open-telemetry/opentelemetry-go#6778) - [Python](open-telemetry/opentelemetry-python#4609) * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes --------- Co-authored-by: Robert Pająk <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]> Co-authored-by: Reiley Yang <[email protected]>

[spec] add EnvVarPropagator decorator for env variable context

c62c0f6

propagation

adrielp requested review from a team as code owners April 20, 2025 16:24

[chore] update changelog with pull request link

7e7ab7a

adrielp commented Apr 21, 2025

View reviewed changes

specification/context/env-carriers.md Outdated Show resolved Hide resolved

carlosalberto reviewed Apr 21, 2025

View reviewed changes

specification/context/env-carriers.md Show resolved Hide resolved

reyang approved these changes Apr 22, 2025

View reviewed changes

adrielp and others added 2 commits April 22, 2025 11:55

Update specification/context/env-carriers.md

b656358

Merge branch 'main' into env-context-decorator

7d30864

reyang reviewed Apr 22, 2025

View reviewed changes

specification/context/env-carriers.md Outdated Show resolved Hide resolved

reyang reviewed Apr 22, 2025

View reviewed changes

specification/context/env-carriers.md Outdated Show resolved Hide resolved

Apply suggestions from code review

05d0ac0

Co-authored-by: Reiley Yang <[email protected]>

adrielp requested a review from carlosalberto April 22, 2025 21:56

scherepiuk reviewed Apr 24, 2025

View reviewed changes

carlosalberto approved these changes Apr 24, 2025

View reviewed changes

pellared reviewed Apr 28, 2025

View reviewed changes

trask added the changelog.opentelemetry.io label Apr 29, 2025

jsuereth reviewed May 5, 2025

View reviewed changes

Merge branch 'main' into env-context-decorator

eff137d

pellared mentioned this pull request May 15, 2025

[Prototype] propagation: add EnvCarrier open-telemetry/opentelemetry-go#6778

Draft

github-actions bot added the Stale label May 23, 2025

carlosalberto removed the Stale label May 23, 2025

tylerbenson reviewed May 28, 2025

View reviewed changes

adrielp mentioned this pull request Jun 2, 2025

[carriers] add env carrier open-telemetry/opentelemetry-python#4609

Draft

12 tasks

Merge branch 'main' into env-context-decorator

4ba04d9

adrielp closed this Jun 3, 2025

pellared removed the changelog.opentelemetry.io label Jun 4, 2025

adrielp mentioned this pull request Jun 10, 2025

[spec] add supplementary guidance around env context propagation #4548

Merged

4 tasks

[spec] add EnvVarPropagator decorator for env variable context #4484

[spec] add EnvVarPropagator decorator for env variable context #4484

Uh oh!

Conversation

adrielp commented Apr 20, 2025

Changes

Uh oh!

adrielp commented Apr 20, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

scherepiuk Apr 24, 2025

Choose a reason for hiding this comment

Uh oh!

scherepiuk Apr 24, 2025

Choose a reason for hiding this comment

Uh oh!

pellared commented Apr 24, 2025

Uh oh!

pellared Apr 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pellared Apr 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pellared May 15, 2025

Choose a reason for hiding this comment

Uh oh!

jsuereth May 5, 2025

Choose a reason for hiding this comment

Uh oh!

carlosalberto commented May 14, 2025

Uh oh!

adrielp commented May 14, 2025

Uh oh!

pellared commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adrielp commented May 15, 2025

Uh oh!

github-actions bot commented May 23, 2025

Uh oh!

tylerbenson May 28, 2025

Choose a reason for hiding this comment

Uh oh!

adrielp commented Jun 2, 2025

Uh oh!

adrielp commented Jun 3, 2025

Uh oh!

tylerbenson commented Jun 4, 2025

Uh oh!

Uh oh!

[spec] add `EnvVarPropagator` decorator for env variable context #4484

[spec] add `EnvVarPropagator` decorator for env variable context #4484

pellared Apr 28, 2025 •

edited

Loading

pellared Apr 28, 2025 •

edited

Loading

pellared commented May 15, 2025 •

edited

Loading