[API Proposal]: Expose API to return the Legacy propagator

[tarekgh]

Background and motivation

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.

As part of this change, DistributedContextPropagator.CreateDefaultPropagator() will now return an instance of the W3C propagator instead of the legacy one. For users who need to preserve previous behavior, we are introducing a new API that returns the legacy propagator explicitly.

API Proposal

namespace System.Diagnostics
{
    public abstract class DistributedContextPropagator
    {
        ...
       public static DistributedContextPropagator CreateDefaultPropagator();
       public static DistributedContextPropagator CreatePassThroughPropagator();
       public static DistributedContextPropagator CreateNoOutputPropagator();

+     public static DistributedContextPropagator CreateLegacyPropagator();
    }
}

Alternative names

• CreatePreW3CPropagator
• CreateLegacyTraceContextPropagator
• CreateCorrelationContextPropagator
• CreateTraceParentCorrelationContextPropagator
• CreateClassicalPropagator
• CreateBackwardCompatiblePropagator
• CreateTransitionalPropagator

API Usage

// Revert to the old behavior using the legacy propagator
DistributedContextPropagator.Current = DistributedContextPropagator.CreateLegacyPropagator();

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-diagnostics-activity
See info in area-owners.md if you want to be subscribed.

[tarekgh]

@noahfalk @samsp-msft @lmolkova @rajkumar-rangaraj

[stephentoub]

Is there a more descriptive name we could use than "Legacy"?

[tarekgh]

Is there a more descriptive name we could use than "Legacy"?

I am open to any suggestions. Here are other suggestions I can think of: Classical, Transitional, CorrelationContext, or BackwardCompatible.

[stephentoub]

What's the key functional/behavioral difference? Can we name it based on what it does? Based on your issue description, seems "Correlation Context" would be the closest?