From c62c0f68c708f00e5a3866c8e4d09d848824dcb4 Mon Sep 17 00:00:00 2001
From: Adriel Perkins <adriel@adrielperkins.com>
Date: Sun, 20 Apr 2025 12:21:35 -0400
Subject: [PATCH 1/4] [spec] add `EnvVarPropagator` decorator for env variable
 context propagation

---
 CHANGELOG.md                          |  4 ++
 specification/context/env-carriers.md | 77 +++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 732460cedf5..dc08cd47c72 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ release.
 
 ### Context
 
+- Add `EnvVarPropagator` decorator with examples for environment variables as context carrier specification. ([#]())
+
 ### Traces
 
 ### Metrics
@@ -17,6 +19,8 @@ release.
 
 ### Baggage
 
+- Add `EnvVarPropagator` decorator with examples for environment variables as context carrier specification. ([#]())
+
 ### Resource
 
 ### Profiles
diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md
index 188c2881b87..c161d52c872 100644
--- a/specification/context/env-carriers.md
+++ b/specification/context/env-carriers.md
@@ -19,6 +19,12 @@
     + [Process Spawning](#process-spawning)
     + [Security](#security)
     + [Case Sensitivity](#case-sensitivity)
+- [Propagator API](#propagator-api)
+  * [Environment Variable Propagator Decorator](#environment-variable-propagator-decorator)
+    + [Examples](#examples)
+      - [Go](#go)
+      - [Python](#python)
+      - [Swift](#swift)
 
 <!-- tocstop -->
 
@@ -149,3 +155,74 @@ Windows.
 - For maximum compatibility, implementations MUST:
   - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`).
   - Use the canonical case when setting environment variables.
+
+## Propagator API
+
+### 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.
+
+The `EnvVarPropagator` MAY define an `EnvVarCarrier` type that implements the
+`TextMap` carrier interface when calling `Inject` and `Extract operations.
+
+#### Examples
+
+##### Go
+
+```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
+    ...
+}
+...
+```
+
+##### Python
+
+```python
+class EnvVarPropagator(TextMapPropagator):
+    def inject(self, context, carrier):
+        env_dict = os.environ.copy()
+        # Inject context into environment variables
+        ...
+    def extract(self, carrier):
+        # Extract context from environment variables
+        ...
+```
+
+##### Swift
+
+```swift
+public struct EnvVarPropagator: TextMapPropagator {
+    public func inject(...) {
+        // Inject context into environment variables
+        ...
+    }
+    public func extract(...) -> SpanContext? {
+        // Extract context from environment variables
+        ...
+    }
+}
+```
+
+[dec]: https://wikipedia.org/wiki/Decorator_pattern

From 7e7ab7a4b9c3b892edcc3beff10ec5753f6110df Mon Sep 17 00:00:00 2001
From: Adriel Perkins <adriel@adrielperkins.com>
Date: Sun, 20 Apr 2025 12:25:17 -0400
Subject: [PATCH 2/4] [chore] update changelog with pull request link

---
 CHANGELOG.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc08cd47c72..a1228f8a642 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ release.
 
 ### Context
 
-- Add `EnvVarPropagator` decorator with examples for environment variables as context carrier specification. ([#]())
+- Add `EnvVarPropagator` decorator with examples for environment variables as context carrier specification. ([#4484](https://github.com/open-telemetry/opentelemetry-specification/pull/4484))
 
 ### Traces
 
@@ -19,7 +19,7 @@ release.
 
 ### Baggage
 
-- Add `EnvVarPropagator` decorator with examples for environment variables as context carrier specification. ([#]())
+- Add `EnvVarPropagator` decorator with examples for environment variables as context carrier specification. ([#4484](https://github.com/open-telemetry/opentelemetry-specification/pull/4484))
 
 ### Resource
 

From b656358d0e6fe77efdc696ef8ccd6557f5b46bd8 Mon Sep 17 00:00:00 2001
From: Adriel Perkins <adriel@adrielperkins.com>
Date: Tue, 22 Apr 2025 11:55:18 -0400
Subject: [PATCH 3/4] Update specification/context/env-carriers.md

---
 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 c161d52c872..f51aaefccad 100644
--- a/specification/context/env-carriers.md
+++ b/specification/context/env-carriers.md
@@ -170,7 +170,7 @@ the [Environment Variable Names](#environment-variable-names) and [Format
 Restrictions](#format-restrictions) sections.
 
 The `EnvVarPropagator` MAY define an `EnvVarCarrier` type that implements the
-`TextMap` carrier interface when calling `Inject` and `Extract operations.
+`TextMap` carrier interface when calling `Inject` and `Extract` operations.
 
 #### Examples
 

From 05d0ac0e4e38fcd292857a1a99d57cb81145e42e Mon Sep 17 00:00:00 2001
From: Adriel Perkins <adriel@adrielperkins.com>
Date: Tue, 22 Apr 2025 12:01:24 -0400
Subject: [PATCH 4/4] Apply suggestions from code review

Co-authored-by: Reiley Yang <reyang@microsoft.com>
---
 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 f51aaefccad..95711f53646 100644
--- a/specification/context/env-carriers.md
+++ b/specification/context/env-carriers.md
@@ -205,6 +205,7 @@ class EnvVarPropagator(TextMapPropagator):
         env_dict = os.environ.copy()
         # Inject context into environment variables
         ...
+
     def extract(self, carrier):
         # Extract context from environment variables
         ...
@@ -218,6 +219,7 @@ public struct EnvVarPropagator: TextMapPropagator {
         // Inject context into environment variables
         ...
     }
+
     public func extract(...) -> SpanContext? {
         // Extract context from environment variables
         ...