env var carriers to only read and return normalized names

[pellared]

Fixes #5143

Prototypes:

• envcar: ignore non-normalized env names on Get and Keys opentelemetry-go-contrib#9112
• [CONTEXT] Fix env carrier key normalization to be spec compliant opentelemetry-cpp#4141
• Do not attempt to enumerate or normalize entries from carrier opentelemetry-java#8474
• feat(propagator-env-carrier): add environment variable carrier helpers opentelemetry-js#6774
• opentelemetry-api: update EnvironmentGetter to ignore non-normalized environment variable names opentelemetry-python#5289
• update EnvironmentMappingGetter to ignore non-normalized environment variable names opentelemetry-swift-core#83

Rationale

The previous wording required environment variable carriers to normalize every key present in the carrier before matching a requested propagation key.

This PR removes that requirement for two reasons:

• Efficiency: extraction should not require reading every environment variable
• Determinism: if multiple environment variable names normalize to the same key, selecting one is ambiguous and implementation-dependent.

Instead, carriers normalize the key requested by the propagator and read only the corresponding normalized environment variable name. Keys similarly returns only environment variable names that are already normalized.

This keeps injection behavior unchanged while making extraction predictable and avoiding unnecessary environment enumeration.

[Copilot]

Pull request overview

Updates the environment-variable carrier specification to avoid requiring environment enumeration during extraction by defining that carriers only operate on normalized environment variable names (for reads and key listing), addressing the efficiency and determinism concerns raised in issue #5143.

Changes:

• Redefine env-var carrier Get behavior to read only the normalized key name (no matching against non-normalized env var names).
• Redefine Keys behavior to return only already-normalized environment variable names.
• Add a changelog entry documenting this specification clarification.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
specification/context/env-carriers.md	Tightens normalization semantics so Get reads only normalized env var names and Keys returns only already-normalized names.
CHANGELOG.md	Records the env-var carrier normalization behavior change in the Unreleased Context section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pellared]

CC @open-telemetry/semconv-cicd-approvers @marcalff @jack-berg

[adrielp]

Just left a couple comments.

[marcalff]

LGTM,

Thanks for supporting this simplification.

[jack-berg]

This PR removes that requirement for two reasons:

Efficiency: extraction should not require reading every environment variable

Check out the java implementation of this. Some notes:

• get has an optimistic lookup against the single requested key. It only reads additional env vars if that optimistic lookup fails, and even so, exits early once it finds a match. The optimistic lookup should be common, I think.
• keys has no choice but to iterate through all env vars and normalize, but keys in not commonly called. The only built-in propagators which use it are the depreceated ottrace and jaeger propagators.
• There's an additional optimization available in the normalize function itself. Currently, java assumes that normalization is needed. It could instead do a first pass to discover if any keys are present which require normalization. If not, avoid allocation.

Finally, starting a new process that needs env var context propagation seems like orders of magnitude more resource utilization that what we're talking about for reading / normalizing all env vars. Does this really matter?

Determinism: if multiple environment variable names normalize to the same key, selecting one is ambiguous and implementation-dependent.

Does this solve that?

The real inefficiency comes from keys(), which in the current implementation has to iterate / normalize all

[pellared]

@jack-berg, regarding #5144 (comment) I suggest continuing the discussion in #5143. Notably please check #5143 (comment) which should answer your concern.