[Breaking change]: ActivitySource does not retain creation tags or links for PropagationData #56340

Description

When an ActivityListener samples an activity as ActivitySamplingResult.PropagationData, ActivitySource.CreateActivity and ActivitySource.StartActivity no longer copy caller-supplied creation tags and links to the created Activity. The tags and links remain available to the sampling callback through ActivityCreationOptions<T>.Tags and ActivityCreationOptions<T>.Links.

For more information, see dotnet/runtime#135277.

Version

.NET 12 Preview 1

Previous behavior

CreateActivity and StartActivity copied caller-supplied creation tags and links to the returned Activity even when the combined sampling result was PropagationData.

using System.Diagnostics;

using ActivitySource source = new("Example");
using ActivityListener listener = new()
{
    ShouldListenTo = activitySource => ReferenceEquals(activitySource, source),
    Sample = (ref ActivityCreationOptions<ActivityContext> _) =>
        ActivitySamplingResult.PropagationData,
};
ActivitySource.AddActivityListener(listener);

using Activity activity = source.StartActivity(
    "Request",
    ActivityKind.Server,
    default(ActivityContext),
    tags: [new("http.request.method", "GET")],
    links: [new ActivityLink(default)])!;

// The activity retained the creation tag and link.
Console.WriteLine(activity.TagObjects.Count()); // 1
Console.WriteLine(activity.Links.Count());      // 1

New behavior

When the combined sampling result is PropagationData, caller-supplied creation tags and links are not copied to the created Activity.

using System.Diagnostics;

using ActivitySource source = new("Example");
using ActivityListener listener = new()
{
    ShouldListenTo = activitySource => ReferenceEquals(activitySource, source),
    Sample = (ref ActivityCreationOptions<ActivityContext> options) =>
    {
        // Creation tags and links remain available to the sampler.
        Console.WriteLine(options.Tags.Count());
        Console.WriteLine(options.Links.Count());
        return ActivitySamplingResult.PropagationData;
    },
};
ActivitySource.AddActivityListener(listener);

using Activity activity = source.StartActivity(
    "Request",
    ActivityKind.Server,
    default(ActivityContext),
    tags: [new("http.request.method", "GET")],
    links: [new ActivityLink(default)])!;

// The activity does not retain the creation tag or link.
Console.WriteLine(activity.TagObjects.Count()); // 0
Console.WriteLine(activity.Links.Count());      // 0

Tags added by a sampler through ActivityCreationOptions<T>.SamplingTags continue to be copied to the created activity. If any listener returns ActivitySamplingResult.AllData or ActivitySamplingResult.AllDataAndRecorded, the combined sampling result requests all data and the caller-supplied creation tags and links are retained.

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

PropagationData creates an activity only to propagate its identity and baggage; tags and links are unnecessary on the created activity. Avoiding their copies reduces the time and allocations for sampled-out operations while preserving their availability to samplers. For example, the PR reduced allocations from 976 B to 416 B when creating an activity with nine tags and one link.

Recommended action

Applications whose samplers need to examine creation tags or links require no changes; continue to read them from ActivityCreationOptions<T>.Tags and ActivityCreationOptions<T>.Links.

Applications that need caller-supplied creation tags or links on the returned Activity or in ActivityStarted callbacks must have a listener return ActivitySamplingResult.AllData or ActivitySamplingResult.AllDataAndRecorded for those activities. Do not return PropagationData when those properties must be retained. This retains the data but also requests all activity data and its associated allocation cost.

Feature area

Core .NET libraries

Affected APIs

All overloads that accept tags and links:

• System.Diagnostics.ActivitySource.CreateActivity
• System.Diagnostics.ActivitySource.StartActivity