Skip to content

envcar: refine normalization#8678

Merged
pellared merged 4 commits into
open-telemetry:mainfrom
pellared:envcar-normalize
Mar 16, 2026
Merged

envcar: refine normalization#8678
pellared merged 4 commits into
open-telemetry:mainfrom
pellared:envcar-normalize

Conversation

@pellared
Copy link
Copy Markdown
Member

@pellared pellared commented Mar 13, 2026

Why

From POSIX Standards:

Environment variable names used by the utilities in the Shell and Utilities volume of POSIX.1-2024 consist solely of uppercase letters, digits, and the ('_') from the characters defined in Portable Character Set and do not begin with a digit.

Related to open-telemetry/opentelemetry-specification#4914

What

Change the normalization so that it adds _ in front when the key starts with a digit so that the result is compliant with the POSIX Standards.

goos: linux
goarch: amd64
pkg: go.opentelemetry.io/contrib/propagators/envcar
cpu: 13th Gen Intel(R) Core(TM) i7-13800H
BenchmarkNormalize/#00-20               996370892                1.244 ns/op           0 B/op          0 allocs/op
BenchmarkNormalize/ABC-20               58236038                19.98 ns/op            3 B/op          1 allocs/op
BenchmarkNormalize/abc-20               63575781                19.51 ns/op            3 B/op          1 allocs/op
BenchmarkNormalize/01239-20             49892817                27.72 ns/op            8 B/op          1 allocs/op
BenchmarkNormalize/0abc-20              50815398                25.87 ns/op            5 B/op          1 allocs/op
BenchmarkNormalize/9-20                 81466388                15.07 ns/op            2 B/op          1 allocs/op
BenchmarkNormalize/a_b_c-20             48530017                25.69 ns/op            5 B/op          1 allocs/op
BenchmarkNormalize/hello-world-20       21449659                52.89 ns/op           16 B/op          1 allocs/op
BenchmarkNormalize/foo.bar-20           29744493                33.63 ns/op            8 B/op          1 allocs/op
BenchmarkNormalize/Content-Type-20              22689820                52.31 ns/op           16 B/op          1 allocs/op
BenchmarkNormalize/traceparent-20               24628167                51.74 ns/op           16 B/op          1 allocs/op
BenchmarkNormalize/key_with_spaces-20           20892998                56.24 ns/op           16 B/op          1 allocs/op
BenchmarkNormalize/MiXeD_123!-20                26057121                46.39 ns/op           16 B/op          1 allocs/op
BenchmarkNormalize/🧳-20                        90115291                11.71 ns/op            0 B/op          0 allocs/op
BenchmarkNormalize/Mój_Bagaż-20                 20788340                57.58 ns/op           16 B/op          1 allocs/op

@pellared pellared marked this pull request as ready for review March 13, 2026 15:59
@pellared pellared requested a review from a team as a code owner March 13, 2026 15:59
@pellared
Copy link
Copy Markdown
Member Author

@Joibel PTAL

@github-actions github-actions Bot requested a review from Joibel March 13, 2026 16:03
@codecov
Copy link
Copy Markdown

codecov Bot commented Mar 13, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.1%. Comparing base (340d326) to head (6da8f54).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@          Coverage Diff          @@
##            main   #8678   +/-   ##
=====================================
  Coverage   82.0%   82.1%           
=====================================
  Files        182     183    +1     
  Lines      13780   13790   +10     
=====================================
+ Hits       11311   11332   +21     
+ Misses      2065    2054   -11     
  Partials     404     404           
Files with missing lines Coverage Δ
propagators/envcar/carrier.go 100.0% <100.0%> (ø)
propagators/envcar/normalize.go 100.0% <100.0%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@pellared pellared merged commit 3a110a0 into open-telemetry:main Mar 16, 2026
30 checks passed
github-merge-queue Bot pushed a commit to open-telemetry/opentelemetry-specification that referenced this pull request Mar 18, 2026
…rmalization rules (#4944)

This PR aligns environment variable context propagation naming with
POSIX.1-2024 and defines normalization rules for propagation keys.

Fixes
#4914

Prototype
open-telemetry/opentelemetry-go-contrib#8678

Note that the changes are in a document which has status "Alpha".

## Motivation

The current text refers to platform-specific restrictions but does not
define how invalid propagation keys should be handled. In particular, it
does not clearly address cases such as:

- names containing `-` (which is used e.g. by
https://github.com/openzipkin/b3-propagation) or other disallowed
characters
- names beginning with digits

## Changes

Propagation keys MUST be normalized to valid environment variable names
by:

- converting ASCII letters to uppercase
- replacing disallowed characters with `_`
- prefixing `_` when the name would otherwise begin with a digit


## Benefits

- Defines deterministic behavior across SDKs
- Improves interoperability between propagators (e.g., W3C and B3)
- Reduces implementation ambiguity
- Aligns with POSIX.1-2024

---------

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
@pellared pellared added this to the v1.43.0 milestone Apr 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants