[spec] add environment variables as context propagators specification

CHANGELOG.md

@@ -9,6 +9,9 @@ release.
 
 ### Context
 
+- Add context propagation through Environment Variables specification.
+    ([#4454](https://github.com/open-telemetry/opentelemetry-specification/pull/4454))
+
 ### Traces
 
 ### Metrics
@@ -20,6 +23,9 @@ release.
 
 ### Baggage
 
+- Add context (baggage) propagation through Environment Variables specification.
+    ([#4454](https://github.com/open-telemetry/opentelemetry-specification/pull/4454))
+
 ### Resource
 
 ### Profiles

specification/README.md

@@ -28,6 +28,7 @@ path_base_for_github_subdir:
 - API Specification
   - [Context](context/README.md)
     - [Propagators](context/api-propagators.md)
+    - [Environment Variable Carriers](context/env-carriers.md)
   - [Baggage](baggage/api.md)
   - [Tracing](trace/api.md)
   - [Metrics](metrics/api.md)

specification/baggage/api.md

@@ -183,6 +183,10 @@ The API layer or an extension package MUST include the following `Propagator`s:
 See [Propagators Distribution](../context/api-propagators.md#propagators-distribution)
 for how propagators are to be distributed.
 
+See [Environment Variable Carriers](../context/env-carriers.md) for how propagation should
+be handled when using environment variables as a carrier mechanism between
+processes.
+
 Note: The W3C baggage specification does not currently assign semantic meaning
 to the optional metadata.
 

specification/context/env-carriers.md

@@ -0,0 +1,151 @@
+# Environment Variables as Context Propagation Carriers
+
+**Status**: [Experimental](../document-status.md)
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Propagator Mechanisms](#propagator-mechanisms)
+  * [Environment Variable Names](#environment-variable-names)
+  * [Format Restrictions](#format-restrictions)
+    + [Name Restrictions](#name-restrictions)
+    + [Value Restrictions](#value-restrictions)
+    + [Size Limitations](#size-limitations)
+  * [Operational Guidance](#operational-guidance)
+    + [Environment Variable Immutability](#environment-variable-immutability)
+    + [Process Spawning](#process-spawning)
+    + [Security](#security)
+    + [Case Sensitivity](#case-sensitivity)
+
+<!-- tocstop -->
+
+</details>
+
+## Overview
+
+Environment variables provide a mechanism to propagate context and baggage
+information across process boundaries when network protocols are not
+applicable. This specification extends the [API Propagators](../context/api-propagators.md)
+to define how the
+[TextMapPropagator](../context/api-propagators.md#textmap-propagator) can be
+used with environment variables.
+
+Common systems where context propagation via environment variables is useful
+include:
+
+- Batch processing systems
+- CI/CD environments
+- Command-line tools
+
+## Propagator Mechanisms
+
+Propagating context via environment variables involves reading and writing to
+environment variables. A `TextMapPropagator` SHOULD be used alongside its
+normal `Get`, `Set`, `Extract`, and `Inject` functionality as described in the [API
+Propagators](../context/api-propagators.md) specification.
+
+### Environment Variable Names
+
+It is RECOMMENDED to use the [W3C Trace
+Context](https://www.w3.org/TR/trace-context/) and [W3C
+Baggage](https://www.w3.org/TR/baggage/) specifications mapped to environment
+variable names for consistent context propagation.
+
+When using the W3C Trace Context and Baggage propagators with environment
+variables, the following translated standard environment variable names SHOULD
+be used:
+
+| Context Information | Environment Variable | W3C Header Equivalent |
+|---------------------|----------------------|-----------------------|
+| Trace Context       | `TRACEPARENT`        | `traceparent`         |
+| Trace State         | `TRACESTATE`         | `tracestate`          |
+| Baggage             | `BAGGAGE`            | `baggage`             |
+
+Implementations MAY support additional propagation formats and SHOULD provide
+configuration options to override the default environment variable.
+
+### Format Restrictions
+
+#### Name Restrictions
+
+Environment variable names used for context propagation:
+
+- SHOULD use uppercase letters, digits, and underscores for maximum
+  cross-platform compatibility
+- MUST NOT include characters forbidden in environment variables per
+  platform-specific restrictions
+- SHOULD follow naming conventions that align with the propagation format
+  specification they're implementing (e.g., `TRACEPARENT` for W3C trace context)
+
+#### Value Restrictions
+
+Environment variable values used for context propagation:
+
+- MUST only use characters that are valid in HTTP header fields per [RFC
+  9110](https://tools.ietf.org/html/rfc9110)
+- MUST follow the format requirements of the specific propagation protocol
+  (e.g., W3C Trace Context specification for `TRACEPARENT` values)
+- SHOULD NOT contain sensitive information
+
+#### Size Limitations
+
+Implementations SHOULD follow platform-specific environment variable size
+limitations:
+
+- Windows: Maximum 32,767 characters for name=value pairs according to
+  [Microsoft Documentation](https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-setenvironmentvariable)
+- UNIX: System-dependent limits exist and are typically lower than Windows.
+
+When truncation is required due to size limitations, implementations MUST
+truncate whole entries. Truncation SHOULD start at the end of the entry list.
+Implementers MUST document how graceful truncation is handled and SHOULD
+provide the link to the corresponding specification (e.g., [W3C tracestate
+Truncation guidance][w3c-truncation]).
+
+[w3c-truncation]: https://www.w3.org/TR/trace-context/#tracestate-limits
+
+### Operational Guidance
+
+#### Environment Variable Immutability
+
+Once set for a process, environment variables SHOULD be treated as immutable
+within that process:
+
+- 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.
+
+#### 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.
+- When spawning multiple child processes with different contexts or baggage,
+  each child SHOULD receive its own copy of the environment variables with
+  appropriate information.
+
+#### 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.
+
+#### Case Sensitivity
+
+Environment variable names are case-sensitive on UNIX and case-insensitive on
+Windows.
+
+- For maximum compatibility, implementations MUST:
+  - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`).
+  - Use the canonical case when setting environment variables.