Skip to content

Align environment variable propagation names with POSIX and define normalization rules #4944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
reyang merged 9 commits into from
Mar 18, 2026
Merged

Align environment variable propagation names with POSIX and define normalization rules #4944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7dca571
Align environment variable context propagation name restrictions with…
pellared Mar 13, 2026
3edc7d0
MUST for deterministic behavior
pellared Mar 13, 2026
842ebb8
clarify
pellared Mar 13, 2026
c7a1196
make the normalization more clear
pellared Mar 13, 2026
757c39d
Update specification/context/env-carriers.md
pellared Mar 13, 2026
cc356d7
Merge branch 'main' into env-car-normalization
pellared Mar 16, 2026
824012f
Merge branch 'main' into env-car-normalization
pellared Mar 16, 2026
e82e744
Merge branch 'main' into env-car-normalization
pellared Mar 17, 2026
eb57d2c
Merge branch 'main' into env-car-normalization
pellared Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
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
View file
Open in desktop
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:

@reyang reyang Mar 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the consumer side, do we expect the consumer to support both uppercase and lowercase letters due to backward compatibility considerations, or we want the consumer to put a rigid bar and ignore things that are not using uppercase letters?

@pellared pellared Mar 18, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. While handling this on the consumer side would align with Postel’s law (being liberal in what you accept), it introduces non-trivial complexity. In practice, it’s not just a matter of checking one alternative. We’d likely need to scan all environment variables and implement matching logic, which can become ambiguous and harder to reason about.

From my perspective, it’s better to keep things simple and predictable by enforcing a consistent format (uppercase). If we later find real-world interoperability issues, we can still extend the consumer behavior in a backward-compatible way.

So for now, I’d lean toward not adding this flexibility. It feels like YAGNI until we have concrete evidence that it’s needed.

@reyang reyang Mar 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯

- 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