Skip to content

[API] Normalize empty environment variable names#7424

Merged
martincostello merged 3 commits into
open-telemetry:mainfrom
martincostello:update-env-var-carrier-for-empty-names
Jun 23, 2026
Merged

[API] Normalize empty environment variable names#7424
martincostello merged 3 commits into
open-telemetry:mainfrom
martincostello:update-env-var-carrier-for-empty-names

Conversation

@martincostello

Copy link
Copy Markdown
Member

open-telemetry/opentelemetry-specification#5163.

Changes

Normalize an empty value to _.

/cc @pellared

Merge requirement checklist

  • CONTRIBUTING guidelines followed (license requirements, nullable enabled, static analysis, etc.)
  • Unit tests added/updated
  • Appropriate CHANGELOG.md files updated for non-trivial changes
  • Changes in public API reviewed (if applicable)

@github-actions github-actions Bot added the pkg:OpenTelemetry.Api Issues related to OpenTelemetry.Api NuGet package label Jun 18, 2026
@codecov

codecov Bot commented Jun 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.26%. Comparing base (0fd5949) to head (dc9906e).
⚠️ Report is 9 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #7424      +/-   ##
==========================================
+ Coverage   89.84%   90.26%   +0.42%     
==========================================
  Files         276      279       +3     
  Lines       14611    15584     +973     
==========================================
+ Hits        13127    14067     +940     
- Misses       1484     1517      +33     
Flag Coverage Δ
unittests-Project-Experimental 89.87% <100.00%> (+0.10%) ⬆️
unittests-Project-Stable 89.89% <100.00%> (+0.16%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
.../Context/Propagation/EnvironmentVariableCarrier.cs 98.59% <100.00%> (+0.04%) ⬆️

... and 14 files with indirect coverage changes

@martincostello
martincostello marked this pull request as ready for review June 18, 2026 13:57
@martincostello
martincostello requested a review from a team as a code owner June 18, 2026 13:57
@martincostello
martincostello enabled auto-merge June 18, 2026 13:57
pellared added a commit to pellared/opentelemetry-specification that referenced this pull request Jun 22, 2026
…try#5163)

Issue discovered by @MrAlias in
open-telemetry/opentelemetry-go-contrib#9112 (comment)

Also see
open-telemetry#5163 (comment)

Prototypes: 
-
open-telemetry/opentelemetry-go-contrib@0fedf62
- open-telemetry/opentelemetry-dotnet#7424
- open-telemetry/opentelemetry-swift-core#86
- open-telemetry/opentelemetry-python#5328
- open-telemetry/opentelemetry-js#6827
- open-telemetry/opentelemetry-java#8481

For values to be fully portable across POSIX-compliant systems and shell
utilities, the standard dictates that environment variable names must
consist solely of uppercase letters, digits, and underscores (_), and
must not begin with a digit. While some individual implementations might
tolerate unusual characters, an empty string lacks any valid characters
entirely and cannot act as a recognizable identifier.

I verified that on Ubuntu it is not possible to set a env var with an
empty name.

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment thread src/OpenTelemetry.Api/CHANGELOG.md Outdated
Comment thread src/OpenTelemetry.Api/Context/Propagation/EnvironmentVariableCarrier.cs Outdated
Co-authored-by: xiang17 <xili9@microsoft.com>
Copilot AI review requested due to automatic review settings June 23, 2026 04:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Updates the experimental EnvironmentVariableCarrier key normalization logic in OpenTelemetry.Api to align with the updated environment variable carrier specification by ensuring empty propagation keys normalize to a valid environment variable name.

Changes:

  • Normalize an empty key ("") to a single underscore ("_") in EnvironmentVariableCarrier.NormalizeKey.
  • Update normalization documentation to explicitly describe the empty-key behavior.
  • Extend unit tests to cover the empty-key normalization case.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File Description
test/OpenTelemetry.Api.Tests/Context/Propagation/EnvironmentVariableCarrierTests.cs Adds coverage asserting NormalizeKey("") returns "_".
src/OpenTelemetry.Api/Context/Propagation/EnvironmentVariableCarrier.cs Implements empty-key normalization and updates remarks; ensures empty keys are not treated as already-normalized.
src/OpenTelemetry.Api/CHANGELOG.md Documents the experimental behavior change for empty key normalization.

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

Co-authored-by: xiang17 <xili9@microsoft.com>
@martincostello
martincostello added this pull request to the merge queue Jun 23, 2026
Merged via the queue into open-telemetry:main with commit 88fd1f0 Jun 23, 2026
74 checks passed
@martincostello
martincostello deleted the update-env-var-carrier-for-empty-names branch June 23, 2026 05:17
@martincostello martincostello added this to the v1.17.0 milestone Jul 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pkg:OpenTelemetry.Api Issues related to OpenTelemetry.Api NuGet package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants