[API] Add support for W3C randomness flag

[martincostello]

Contributes to #6768. I'm not sure if this fixes it.

Changes

Update TraceContextPropagator to handle the W3C randomness flag.

This got flagged by the updates to .NET 11 preview.4 in #6899 and open-telemetry/opentelemetry-dotnet-contrib#3867, and it looks like we can support it without needing to have the ActivityTraceFlags.RandomTraceId enum value defined (dotnet/runtime#124509).

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 86.66667% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.94%. Comparing base (b0d5e79) to head (1f733c9).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
....Api/Context/Propagation/TraceContextPropagator.cs	86.04%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7301      +/-   ##
==========================================
+ Coverage   89.85%   89.94%   +0.08%     
==========================================
  Files         273      275       +2     
  Lines       13773    13999     +226     
==========================================
+ Hits        12376    12591     +215     
- Misses       1397     1408      +11     

Flag	Coverage Δ
unittests-Project-Experimental	89.79% <86.66%> (-0.02%)	⬇️
unittests-Project-Stable	89.86% <86.66%> (+0.05%)	⬆️

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

Files with missing lines	Coverage Δ
...nTelemetry/Internal/OpenTelemetrySdkEventSource.cs	62.79% <100.00%> (+0.43%)	⬆️
....Api/Context/Propagation/TraceContextPropagator.cs	90.56% <86.04%> (-0.53%)	⬇️

... and 10 files with indirect coverage changes

[Copilot]

Pull request overview

Adds support for the W3C trace context randomness flag (bit 0x02) in TraceContextPropagator so the flag round-trips through both extract and inject paths, and updates OpenTelemetrySdkEventSource to render the full trace flags byte. Tests are extended to cover the new bit and the Dockerfile is bumped to W3C spec level 2.

Changes:

• TraceContextPropagator.Inject now writes the entire trace flags byte as hex (covering Recorded + Random), and TryExtractTraceparent recognizes the 0x02 random bit.
• OpenTelemetrySdkEventSource.ActivityStarted formats the flags byte as 2-digit hex instead of hardcoding -00/-01.
• New unit tests for extracting/injecting the random flag (alone and combined with Recorded), Dockerfile SPEC_LEVEL=2, CHANGELOG entries.

Reviewed changes

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

Show a summary per file

File	Description
src/OpenTelemetry.Api/Context/Propagation/TraceContextPropagator.cs	Inject/extract now handle the random flag bit; minor ternary refactor in TryExtractTracestate; WriteTraceParentIntoSpan writes flags via hex helper.
src/OpenTelemetry/Internal/OpenTelemetrySdkEventSource.cs	Logs full trace flags byte using x2 formatting.
test/OpenTelemetry.Tests/Trace/Propagation/TraceContextPropagatorTests.cs	Adds tests for random flag (alone and combined), and invalid traceparents with -02/-03.
test/OpenTelemetry.Api.Tests/Context/Propagation/EnvironmentVariableCarrierTests.cs	Parameterizes round-trip test across all four flag combinations.
test/OpenTelemetry.Instrumentation.W3cTraceContext.Tests/Dockerfile	Bumps SPEC_LEVEL from 1 to 2.
src/OpenTelemetry.Api/CHANGELOG.md, src/OpenTelemetry/CHANGELOG.md	Document the changes.

---

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

[Kielek]

I didn't check the exporter parts (OTLP, Console). IMO worth to do this.

EDIT: Separate PR will be fine.

[martincostello]

I didn't check the exporter parts (OTLP, Console). IMO worth to do this.

I checked the repo again.

• OTLP writes the value rather than a string, so it already does the right thing and doesn't need formatting special casing:

  opentelemetry-dotnet/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/Serializer/ProtobufOtlpTraceSerializer.cs

  Lines 269 to 282 in 2435127

  	internal static int WriteTraceFlags(byte[] buffer, int position, ActivityTraceFlags activityTraceFlags, bool hasRemoteParent, int fieldNumber)
  	{
  	var spanFlags = (uint)activityTraceFlags & 0x000000FF;
  	spanFlags |= 0x00000100;
  	if (hasRemoteParent)
  	{
  	spanFlags |= 0x00000200;
  	}
  	position = ProtobufSerializer.WriteFixed32WithTag(buffer, position, fieldNumber, spanFlags);
  	return position;
  	}

• Console does ToString() on the enum already, so doesn't need updating and doesn't need to be high-performance.

  opentelemetry-dotnet/src/OpenTelemetry.Exporter.Console/ConsoleActivityExporter.cs

  Line 23 in 2435127

  this.WriteLine($"Activity.TraceFlags: {activity.ActivityTraceFlags}");

• OpenTelemetrySdkEventSource does the slow path, but that's for a verbose-level trace message so I don't think we need to make it more performant.

  opentelemetry-dotnet/src/OpenTelemetry/Internal/OpenTelemetrySdkEventSource.cs

  Line 73 in 2435127

  var traceFlags = ((byte)activity.ActivityTraceFlags).ToString("x2", CultureInfo.InvariantCulture);

• B3 and Jaeger don't have any support for interpreting the W3C randomness flag so don't need changing