[Breaking change]: Switch the default trace context propagator from Legacy to W3C

[tarekgh]

Description

DistributedContextPropagator is the type used to encode trace context and baggage values for propagation across process/machine boundaries. Historically, .NET used a legacy propagator as the default, which propagated baggage using the Correlation-Context header name. However, this legacy propagator is not fully compliant with the W3C Trace Context and Baggage specifications.

Starting with .NET 10, we are adopting the W3C propagator as the default. The new W3C propagator differs from the legacy one in several key ways:

• It uses the baggage header name instead of Correlation-Context to propagate baggage.
• It propagates only W3C-formatted trace parent IDs, whereas the legacy propagator can handle older hierarchical IDs.
• It enforces W3C-compliant encoding for trace parent, trace state, and baggage keys and values. The legacy propagator is more lenient and does not enforce strict formatting.

dotnet/runtime#114583
dotnet/runtime#114584

Version

.NET 10

Previous behavior

DistributedContextPropagator.CreateDefaultPropagator() was returning instance of the legacy propagator and by default DistributedContextPropagator.Current was set to that legacy instance.

New behavior

DistributedContextPropagator.CreateDefaultPropagator() will return instance of the W3C propagator and by default DistributedContextPropagator.Current will be set to that W3C instance.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

This change is to fully comply with the W3C specification for propagating the trace context and baggage.

Recommended action

In .NET, we are exposing a new API DistributedContextPropagator.CreateLegacyPropagator() to allow retrieve the legacy propagator instance to use if want to get the old behavior. Users can do the following to get the old behavior.

DistributedContextPropagator.Current = DistributedContextPropagator.CreateLegacyPropagator();

Feature area

Diagnostics

Affected APIs

DistributedContextPropagator.Current 
DistributedContextPropagator CreateDefaultPropagator()

[CamSoper]

@tarekgh Is this going out with the Preview 4 release?

[tarekgh]

@CamSoper Yes, the plan is to get this in preview 4. You can watch the PR dotnet/runtime#114583 to know when this will get merged.