diff --git a/CHANGELOG.md b/CHANGELOG.md index 6cb6c87fda8..0b53f1b2cea 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/specification/README.md b/specification/README.md index 32a653e04d6..5d587fdf99f 100644 --- a/specification/README.md +++ b/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) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index fef72cd153c..67d4aa74afb 100644 --- a/specification/baggage/api.md +++ b/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. diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md new file mode 100644 index 00000000000..188c2881b87 --- /dev/null +++ b/specification/context/env-carriers.md @@ -0,0 +1,151 @@ +# Environment Variables as Context Propagation Carriers + +**Status**: [Experimental](../document-status.md) + +
+Table of Contents + + + +- [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) + + + +
+ +## 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.