[Extensions] Add W3CTraceState

src/OpenTelemetry.Extensions/.publicApi/PublicAPI.Unshipped.txt

@@ -14,9 +14,14 @@ OpenTelemetry.RateLimitingSampler
 OpenTelemetry.RateLimitingSampler.RateLimitingSampler(int maxTracesPerSecond) -> void
 OpenTelemetry.Trace.BaggageActivityProcessor
 OpenTelemetry.Trace.TracerProviderBuilderExtensions
+OpenTelemetry.Trace.W3CTraceState
+OpenTelemetry.Trace.W3CTraceState.Remove(string! key) -> OpenTelemetry.Trace.W3CTraceState!
+OpenTelemetry.Trace.W3CTraceState.Set(string! key, string! value) -> OpenTelemetry.Trace.W3CTraceState!
+OpenTelemetry.Trace.W3CTraceState.TryGetValue(string! key, out string? value) -> bool
 override OpenTelemetry.ConsistentProbabilitySampler.ShouldSample(in OpenTelemetry.Trace.SamplingParameters samplingParameters) -> OpenTelemetry.Trace.SamplingResult
 override OpenTelemetry.RateLimitingSampler.ShouldSample(in OpenTelemetry.Trace.SamplingParameters samplingParameters) -> OpenTelemetry.Trace.SamplingResult
 override OpenTelemetry.Trace.BaggageActivityProcessor.OnStart(System.Diagnostics.Activity! data) -> void
+override OpenTelemetry.Trace.W3CTraceState.ToString() -> string!
 static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.AddBaggageProcessor(this OpenTelemetry.Logs.LoggerProviderBuilder! builder) -> OpenTelemetry.Logs.LoggerProviderBuilder!
 static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.AddBaggageProcessor(this OpenTelemetry.Logs.LoggerProviderBuilder! builder, System.Predicate<string!>! baggageKeyPredicate) -> OpenTelemetry.Logs.LoggerProviderBuilder!
 static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.AddBaggageProcessor(this OpenTelemetry.Logs.OpenTelemetryLoggerOptions! loggerOptions) -> OpenTelemetry.Logs.OpenTelemetryLoggerOptions!
@@ -25,3 +30,5 @@ static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.AttachLogsToA
 static OpenTelemetry.Trace.BaggageActivityProcessor.AllowAllBaggageKeys.get -> System.Predicate<string!>!
 static OpenTelemetry.Trace.TracerProviderBuilderExtensions.AddAutoFlushActivityProcessor(this OpenTelemetry.Trace.TracerProviderBuilder! builder, System.Func<System.Diagnostics.Activity!, bool>! predicate, int timeoutMilliseconds = 10000) -> OpenTelemetry.Trace.TracerProviderBuilder!
 static OpenTelemetry.Trace.TracerProviderBuilderExtensions.AddBaggageActivityProcessor(this OpenTelemetry.Trace.TracerProviderBuilder! builder, System.Predicate<string!>! baggageKeyPredicate) -> OpenTelemetry.Trace.TracerProviderBuilder!
+static OpenTelemetry.Trace.W3CTraceState.Parse(string? tracestate) -> OpenTelemetry.Trace.W3CTraceState!
+static OpenTelemetry.Trace.W3CTraceState.TryParse(string? tracestate, out OpenTelemetry.Trace.W3CTraceState! state) -> bool

src/OpenTelemetry.Extensions/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+* Added `W3CTraceState`, an immutable parsed view of a W3C `tracestate` header
+  exposing the get, add, update and delete operations the OpenTelemetry
+  [tracing API](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.60.0/specification/trace/api.md#tracestate)
+  specification defines, and preserving members it did not generate.
+  ([#5115](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/5115))
+
 ## 1.18.0-beta.1
 
 Released 2026-Aug-21

src/OpenTelemetry.Extensions/README.md

@@ -161,3 +161,37 @@ builder.Services.AddOpenTelemetry()
             .SetSampler(new ParentBasedSampler(new ConsistentProbabilitySampler(0.1)));
     });
 ```
+
+### W3CTraceState
+
+`W3CTraceState` is an immutable, parsed view of a W3C
+[`tracestate`](https://www.w3.org/TR/2021/REC-trace-context-1-20211123/#tracestate-header)
+header. It exposes the get, add, update and delete operations the OpenTelemetry
+[tracing API](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.60.0/specification/trace/api.md#tracestate)
+specification defines for `TraceState`, which .NET otherwise surfaces only as the
+raw `ActivityContext.TraceState` string. Custom samplers and propagators that
+edit that string by hand have to re-implement the W3C mutation rules, and the
+obvious hand-rolled version gets several of them wrong.
+
+Parsing always succeeds, a mutating operation that changes something returns a
+new instance, and neither throws: an operation that changes nothing, such as one
+naming an invalid key or value, hands back the receiver itself. Members this
+instance did not generate are preserved verbatim, including malformed ones, so
+that an arbitrary sequence of mutations does not erode another vendor's entries.
+
+Use `TryParse` where a caller wants to know that a header was unusable: it
+returns `false` when members were retained and not one of them matched the
+`list-member` grammar.
+
+Example of `W3CTraceState` usage in a custom sampler:
+
+```cs
+public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
+{
+    var traceState = W3CTraceState.Parse(samplingParameters.ParentContext.TraceState)
+                                  .Set("mykey", "myvalue")
+                                  .ToString();
+
+    return new SamplingResult(SamplingDecision.RecordAndSample, traceState);
+}
+```