[API] Support environment variable context propagation

[martincostello]

Contributes to #6776

Changes

Add support for using environment variables as context propagation carriers.

I've done this as stable (rather than experimental) for now until there's some reviews of the overall shape and whether it should be experimental, or whether it's just the chicken-and-egg case of it only being experimental because there aren't enough implementations yet.

I'll do the additional fix-ups to make this experimental if needed later, as well as update the CHANGELOG.

Example output from the example project:

[Parent] ProcessId: 12040
[Parent] TraceId: c5995da6f9b9f16054855846a6d14e6a
[Parent] SpanId: db3d80398a7a4783
[Parent] ParentSpanId: <none>
[Parent] Baggage: tenant.id=contoso, user.id=alice
[Parent] Injected environment variables:
[Parent]   TRACESTATE=<not set>
[Parent]   TRACEPARENT=00-c5995da6f9b9f16054855846a6d14e6a-db3d80398a7a4783-01
[Parent]   BAGGAGE=tenant.id=contoso,user.id=alice


  [Child] Captured propagated environment variables:
  [Child]   TRACESTATE=<not set>
  [Child]   TRACEPARENT=00-c5995da6f9b9f16054855846a6d14e6a-db3d80398a7a4783-01
  [Child]   BAGGAGE=tenant.id=contoso,user.id=alice

  [Child] ProcessId: 18820
  [Child] TraceId: c5995da6f9b9f16054855846a6d14e6a
  [Child] SpanId: d75fc3391ae9b0bd
  [Child] ParentSpanId: db3d80398a7a4783
  [Child] ExtractedParentTraceId: c5995da6f9b9f16054855846a6d14e6a
  [Child] ExtractedParentSpanId: db3d80398a7a4783
  [Child] Baggage: tenant.id=contoso, user.id=alice

[Parent] Child process exited with code 0.

Benchmarks

Expand to view

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.8246/25H2/2025Update/HudsonValley2)
13th Gen Intel Core i7-13700H 2.90GHz, 1 CPU, 20 logical and 14 physical cores
.NET SDK 10.0.203
  [Host]               : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v3
  .NET 10.0            : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v3
  .NET Framework 4.6.2 : .NET Framework 4.8.1 (4.8.9325.0), X64 RyuJIT VectorSize=256

Method	Job	Runtime	IncludeBaggage	Mean	Error	StdDev	Ratio	RatioSD	Gen0	Allocated	Alloc Ratio
Capture	.NET 10.0	.NET 10.0	False	76.89 ns	1.558 ns	1.794 ns	1.00	0.03	0.0324	408 B	1.00
Capture	.NET Framework 4.6.2	.NET Framework 4.6.2	False	148.11 ns	2.927 ns	4.642 ns	1.93	0.07	0.0815	514 B	1.26
Extract	.NET 10.0	.NET 10.0	False	127.94 ns	2.585 ns	3.868 ns	1.00	0.04	0.0229	288 B	1.00
Extract	.NET Framework 4.6.2	.NET Framework 4.6.2	False	383.65 ns	7.619 ns	8.774 ns	3.00	0.11	0.0634	401 B	1.39
Inject	.NET 10.0	.NET 10.0	False	178.30 ns	3.537 ns	6.982 ns	1.00	0.05	0.0739	928 B	1.00
Inject	.NET Framework 4.6.2	.NET Framework 4.6.2	False	546.00 ns	10.948 ns	17.365 ns	3.07	0.15	0.2031	1284 B	1.38
Capture	.NET 10.0	.NET 10.0	True	99.20 ns	1.957 ns	2.175 ns	1.00	0.03	0.0356	448 B	1.00
Capture	.NET Framework 4.6.2	.NET Framework 4.6.2	True	187.41 ns	3.736 ns	5.476 ns	1.89	0.07	0.0942	594 B	1.33
Extract	.NET 10.0	.NET 10.0	True	267.03 ns	5.377 ns	12.026 ns	1.00	0.06	0.0648	816 B	1.00
Extract	.NET Framework 4.6.2	.NET Framework 4.6.2	True	869.75 ns	3.985 ns	3.328 ns	3.26	0.14	0.1574	995 B	1.22
Inject	.NET 10.0	.NET 10.0	True	304.95 ns	6.108 ns	12.477 ns	1.00	0.06	0.1121	1408 B	1.00
Inject	.NET Framework 4.6.2	.NET Framework 4.6.2	True	1,171.92 ns	22.772 ns	32.660 ns	3.85	0.19	0.3548	2239 B	1.59

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)

[codecov]

Codecov Report

❌ Patch coverage is 98.76543% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 89.75%. Comparing base (7e29276) to head (73a96e3).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
.../Context/Propagation/EnvironmentVariableCarrier.cs	98.76%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7174      +/-   ##
==========================================
+ Coverage   89.69%   89.75%   +0.05%     
==========================================
  Files         272      273       +1     
  Lines       13366    13514     +148     
==========================================
+ Hits        11989    12129     +140     
- Misses       1377     1385       +8     

Flag	Coverage Δ
unittests-Project-Experimental	89.50% <98.76%> (-0.19%)	⬇️
unittests-Project-Stable	89.49% <98.76%> (-0.17%)	⬇️
unittests-Solution	89.72% <98.76%> (+0.09%)	⬆️
unittests-UnstableCoreLibraries-Experimental	44.23% <0.00%> (+2.93%)	⬆️

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.76% <98.76%> (ø)

... and 5 files with indirect coverage changes

[Copilot]

Pull request overview

Adds first-class support for propagating OpenTelemetry context/baggage via environment variables, aligning with the OpenTelemetry environment variable carrier spec.

Changes:

• Introduces EnvironmentVariableCarrier API for capture/get/set + key normalization in OpenTelemetry.Api.
• Adds unit tests, fuzz tests, and benchmarks validating normalization and round-trip behavior.
• Adds documentation and a runnable example demonstrating parent/child process propagation via environment variables.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/OpenTelemetry.Api/Context/Propagation/EnvironmentVariableCarrier.cs	New carrier implementation for capturing and using env vars as propagation carriers.
src/OpenTelemetry.Api/.publicApi/Stable/PublicAPI.Unshipped.txt	Declares new stable public APIs for EnvironmentVariableCarrier.
src/OpenTelemetry.Api/README.md	Documents environment variable propagation usage and links to the spec.
test/OpenTelemetry.Api.Tests/OpenTelemetry.Api.Tests.csproj	Links EnvironmentVariableScope helper into API tests.
test/OpenTelemetry.Api.Tests/Context/Propagation/EnvironmentVariableCarrierTests.cs	New unit tests covering normalization/capture/get/set and propagator round-trips.
test/OpenTelemetry.Api.FuzzTests/Context/Propagation/Generators.cs	Adds generators for env-var keys and opaque values.
test/OpenTelemetry.Api.FuzzTests/Context/Propagation/EnvironmentVariableCarrierFuzzTests.cs	New fuzz tests for normalization validity and round-trip invariants.
test/Benchmarks/Context/Propagation/EnvironmentVariableCarrierBenchmarks.cs	Adds benchmarks for capture/extract/inject.
examples/EnvironmentVariables/Program.cs	New end-to-end example demonstrating env-var propagation across processes.
examples/EnvironmentVariables/Examples.EnvironmentVariables.csproj	Adds example project for the new scenario.
OpenTelemetry.slnx	Includes the new example project in the solution.

---

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

[pellared]

Overall LGTM. All comments are rather minor. Thanks a lot ❤️