Skip to content
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ release.

### Context

- Align environment variable context propagation name restrictions with POSIX.1-2024
and define normalization behavior.
([#4914](https://github.com/open-telemetry/opentelemetry-specification/issues/4914))

### Traces

- Stabilize Tracer `enabled` operation
Expand Down
16 changes: 10 additions & 6 deletions specification/context/env-carriers.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,12 +77,16 @@ configuration options to override the default environment variable.

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)
Comment thread
kamphaus marked this conversation as resolved.
- MUST be normalized by:
Comment thread
reyang marked this conversation as resolved.
- uppercasing ASCII letters,
- replacing every character that is not an ASCII letter, digit, or underscore
(`_`) with an underscore (`_`),
- prefixing the name with an underscore (`_`) if it would otherwise start with
an ASCII digit.

> [!NOTE]
> This normalization is consistent with the environment variable naming rules
> defined in [POSIX.1-2024](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html).

#### Value Restrictions

Expand Down
Loading