feat: Add W3C traceparent support to tracing client and utils

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - Prevent users from disabling AndroidEnableAssemblyCompression which leads to untrappable crash ([#4089](https://github.com/getsentry/sentry-dotnet/pull/4089))
 
+### Features
+
+- If an incoming HTTP request has the `traceparent` header, it is now parsed and interpreted like the `sentry-trace` header. Outgoing requests now contain the `traceparent` header to facilitate integration with servesr that only support the [W3C Trace Context](https://www.w3.org/TR/trace-context/). ([#4084](https://github.com/getsentry/sentry-dotnet/pull/4084))
+
 ## 5.5.1
 
 ### Fixes

src/Sentry.AspNet/HttpContextExtensions.cs

@@ -33,6 +33,27 @@ public static class HttpContextExtensions
         }
     }
 
+    private static W3CTraceHeader? TryGetW3CTraceHeader(HttpContext context, SentryOptions? options)
+    {
+        var value = context.Request.Headers.Get(W3CTraceHeader.HttpHeaderName);
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        options?.LogDebug("Received Sentry trace header '{0}'.", value);
+
+        try
+        {
+            return W3CTraceHeader.Parse(value);
+        }
+        catch (Exception ex)
+        {
+            options?.LogError(ex, "Invalid Sentry trace header '{0}'.", value);
+            return null;
+        }
+    }
+
     private static BaggageHeader? TryGetBaggageHeader(HttpContext context, SentryOptions? options)
     {
         var value = context.Request.Headers.Get(BaggageHeader.HttpHeaderName);
@@ -64,7 +85,10 @@ public static void StartOrContinueTrace(this HttpContext httpContext)
     {
         var options = SentrySdk.CurrentOptions;
 
+        // If both sentry-trace and traceparent headers are present, sentry-trace takes precedence.
+        // See: https://github.com/getsentry/team-sdks/issues/41
         var traceHeader = TryGetSentryTraceHeader(httpContext, options);
+        traceHeader ??= TryGetW3CTraceHeader(httpContext, options)?.SentryTraceHeader;
         var baggageHeader = TryGetBaggageHeader(httpContext, options);
 
         var method = httpContext.Request.HttpMethod;

src/Sentry.AspNetCore/Extensions/HttpContextExtensions.cs

@@ -65,6 +65,27 @@ internal static class HttpContextExtensions
         }
     }
 
+    public static W3CTraceHeader? TryGetW3CTraceHeader(this HttpContext context, SentryOptions? options)
+    {
+        var value = context.Request.Headers.GetValueOrDefault(W3CTraceHeader.HttpHeaderName);
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        options?.LogDebug("Received Sentry trace header '{0}'.", value);
+
+        try
+        {
+            return W3CTraceHeader.Parse(value!);
+        }
+        catch (Exception ex)
+        {
+            options?.LogError(ex, "Invalid Sentry trace header '{0}'.", value);
+            return null;
+        }
+    }
+
     public static BaggageHeader? TryGetBaggageHeader(this HttpContext context, SentryOptions? options)
     {
         var value = context.Request.Headers.GetValueOrDefault(BaggageHeader.HttpHeaderName);

src/Sentry.AspNetCore/SentryMiddleware.cs

@@ -105,7 +105,10 @@ public async Task InvokeAsync(HttpContext context, RequestDelegate next)
                 context.Response.OnCompleted(() => hub.FlushAsync(_options.FlushTimeout));
             }
 
+            // If both sentry-trace and traceparent headers are present, sentry-trace takes precedence.
+            // See: https://github.com/getsentry/team-sdks/issues/41
             var traceHeader = context.TryGetSentryTraceHeader(_options);
+            traceHeader ??= context.TryGetW3CTraceHeader(_options)?.SentryTraceHeader;
             var baggageHeader = context.TryGetBaggageHeader(_options);
             var transactionContext = hub.ContinueTrace(traceHeader, baggageHeader);
 

src/Sentry.Azure.Functions.Worker/HttpRequestDataExtensions.cs

@@ -30,6 +30,31 @@ internal static class HttpRequestDataExtensions
         }
     }
 
+    public static W3CTraceHeader? TryGetW3CTraceHeader(this HttpRequestData context, IDiagnosticLogger? logger)
+    {
+        var traceHeaderValue = context.Headers.TryGetValues(W3CTraceHeader.HttpHeaderName, out var values)
+            ? values.FirstOrDefault()
+            : null;
+
+        if (traceHeaderValue is null)
+        {
+            logger?.LogDebug("Did not receive a Sentry trace header.");
+            return null;
+        }
+
+        logger?.LogDebug("Received Sentry trace header '{0}'.", traceHeaderValue);
+
+        try
+        {
+            return W3CTraceHeader.Parse(traceHeaderValue);
+        }
+        catch (Exception ex)
+        {
+            logger?.LogError(ex, "Invalid Sentry trace header '{0}'.", traceHeaderValue);
+            return null;
+        }
+    }
+
     public static BaggageHeader? TryGetBaggageHeader(this HttpRequestData context, IDiagnosticLogger? logger)
     {
         var baggageValue = context.Headers.TryGetValues(BaggageHeader.HttpHeaderName, out var value)

src/Sentry.Azure.Functions.Worker/SentryFunctionsWorkerMiddleware.cs

@@ -123,7 +123,10 @@ private async Task<TransactionContext> StartOrContinueTraceAsync(FunctionContext
             TransactionNameCache.TryAdd(transactionNameKey, transactionName);
         }
 
+        // If both sentry-trace and traceparent headers are present, sentry-trace takes precedence.
+        // See: https://github.com/getsentry/team-sdks/issues/41
         var traceHeader = requestData.TryGetSentryTraceHeader(_logger);
+        traceHeader ??= requestData.TryGetW3CTraceHeader(_logger)?.SentryTraceHeader;
         var baggageHeader = requestData.TryGetBaggageHeader(_logger);
 
         return SentrySdk.ContinueTrace(traceHeader, baggageHeader, transactionName, Operation);

src/Sentry/SentryMessageHandler.cs

@@ -136,6 +136,7 @@ private void PropagateTraceHeaders(HttpRequestMessage request, string url)
         if (_options?.TracePropagationTargets.MatchesSubstringOrRegex(url) is true or null)
         {
             AddSentryTraceHeader(request);
+            AddW3CTraceHeader(request);
             AddBaggageHeader(request);
         }
     }
@@ -149,6 +150,15 @@ private void AddSentryTraceHeader(HttpRequestMessage request)
         }
     }
 
+    private void AddW3CTraceHeader(HttpRequestMessage request)
+    {
+        // Set trace header if it hasn't already been set
+        if (!request.Headers.Contains(W3CTraceHeader.HttpHeaderName) && _hub.GetTraceHeader() is { } traceHeader)
+        {
+            request.Headers.Add(W3CTraceHeader.HttpHeaderName, new W3CTraceHeader(traceHeader).ToString());
+        }
+    }
+
     private void AddBaggageHeader(HttpRequestMessage request)
     {
         var baggage = _hub.GetBaggage();

src/Sentry/SentryOptions.cs

@@ -952,7 +952,8 @@ public double? ProfilesSampleRate
     /// <summary>
     /// A customizable list of <see cref="StringOrRegex"/> objects, each containing either a
     /// substring or regular expression pattern that can be used to control which outgoing HTTP requests
-    /// will have the <c>sentry-trace</c> and <c>baggage</c> headers propagated, for purposes of distributed tracing.
+    /// will have the <c>sentry-trace</c>, <c>traceparent</c>, and <c>baggage</c> headers propagated,
+    /// for purposes of distributed tracing.
     /// The default value contains a single value of <c>.*</c>, which matches everything.
     /// To disable propagation completely, clear this collection or set it to an empty collection.
     /// </summary>

src/Sentry/W3CTraceHeader.cs

@@ -0,0 +1,131 @@
+namespace Sentry;
+
+/// <summary>
+/// Extension methods for working with Sentry trace headers.
+/// </summary>
+internal class W3CTraceHeader
+{
+    private const string SupportedVersion = "00";
+
+    /// <summary>
+    /// The name of the W3C trace context header used for distributed tracing.
+    /// This field contains the value "traceparent" which is part of the W3C Trace Context specification.
+    /// </summary>
+    public const string HttpHeaderName = "traceparent";
+
+    /// <summary>
+    /// Represents the sampled trace flags value ("01") in W3C Trace Context specification.
+    /// This flag indicates that the trace is part of the sampling set and should be recorded.
+    /// </summary>
+    public const string TraceFlagsSampled = "01";
+
+    /// <summary>
+    /// Represents the unsampled trace flags value ("00") in W3C Trace Context specification.
+    /// This flag indicates that the trace is not part of the sampling set and should not be recorded.
+    /// </summary>
+    public const string TraceFlagsNotSampled = "00";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="W3CTraceHeader"/> class from a Sentry trace header.
+    /// </summary>
+    /// <param name="source">The source Sentry trace header to create the W3C trace header from.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="source"/> is null.</exception>
+    public W3CTraceHeader(SentryTraceHeader source)
+    {
+        if (source is null)
+        {
+            throw new ArgumentNullException(nameof(source), "Source Sentry trace header cannot be null.");
+        }
+
+        SentryTraceHeader = source;
+    }
+
+    /// <summary>
+    /// Gets the Sentry trace header containing trace identification and sampling information.
+    /// </summary>
+    /// <value>
+    /// The Sentry trace header that contains the trace ID, span ID, and sampling decision.
+    /// </value>
+    public SentryTraceHeader SentryTraceHeader { get; }
+
+    /// <summary>
+    /// Parses a <see cref="SentryTraceHeader"/> from a string representation of the Sentry trace header.
+    /// </summary>
+    /// <param name="value">
+    /// A string containing the Sentry trace header, expected to follow the format "traceId-spanId-sampled",
+    /// where "sampled" is optional.
+    /// </param>
+    /// <returns>
+    /// A <see cref="SentryTraceHeader"/> object if parsing succeeds, or <c>null</c> if the input string is null, empty, or whitespace.
+    /// </returns>
+    /// <exception cref="FormatException">
+    /// Thrown if the input string does not contain a valid trace header format, specifically if it lacks required trace ID and span ID components.
+    /// </exception>
+    public static W3CTraceHeader? Parse(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        var components = value.Split('-', StringSplitOptions.RemoveEmptyEntries);
+        if (components.Length < 4)
+        {
+            throw new FormatException($"Invalid W3C trace header: {value}.");
+        }
+
+        var version = components[0];
+        if (version != SupportedVersion)
+        {
+            throw new FormatException($"Invalid W3C trace header version: {version}.");
+        }
+
+        var traceId = SentryId.Parse(components[1]);
+        var spanId = SpanId.Parse(components[2]);
+        var isSampled = ConvertTraceFlagsToSampled(components[3]);
+
+        return new W3CTraceHeader(new SentryTraceHeader(traceId, spanId, isSampled));
+    }
+
+    /// <inheritdoc/>
+    public override string ToString()
+    {
+        var traceFlags = ConvertSampledToTraceFlags(SentryTraceHeader.IsSampled);
+        return $"{SupportedVersion}-{SentryTraceHeader.TraceId}-{SentryTraceHeader.SpanId}-{traceFlags}";
+    }
+
+    private static string? ConvertSampledToTraceFlags(bool? isSampled) => (isSampled ?? false) ? TraceFlagsSampled : TraceFlagsNotSampled;
+
+    private static bool? ConvertTraceFlagsToSampled(string? traceFlags)
+    {
+        if (string.IsNullOrWhiteSpace(traceFlags) || traceFlags.Length != 2)
+        {
+            return null;
+        }
+
+        // In version 00 of the W3C Trace Context specification, the trace flags field is 2 hex digits.
+        // Only the first bit is used. We use string comparison first to avoid parsing the hex value in
+        // the bulk of all cases.
+        // See https://github.com/getsentry/sentry-dotnet/pull/4084#discussion_r2035771628
+        if (string.Equals(traceFlags, TraceFlagsSampled, StringComparison.Ordinal))
+        {
+            return true;
+        }
+        else if (string.Equals(traceFlags, TraceFlagsNotSampled, StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        // If the trace flags field is not "01" or "00", we try to parse it as a hex number.
+        // This is a fallback for cases where the trace flags field is not in the expected format.
+        if (!byte.TryParse(traceFlags, NumberStyles.HexNumber, CultureInfo.InvariantCulture, out byte traceFlagsBytes))
+        {
+            // If it's not a valid hex number, we can't parse it.
+            return null;
+        }
+
+        // The first bit of the trace flags field indicates whether the trace is sampled.
+        // We use bitwise AND to check if the first bit is set.
+        return (traceFlagsBytes & 0x01) == 1;
+    }
+}

test/Sentry.AspNetCore.Tests/SentryMiddlewareTests.cs

@@ -682,8 +682,10 @@ public async Task InvokeAsync_InstrumenterOpenTelemetry_SavesScope()
         }
     }
 
-    [Fact]
-    public async Task InvokeAsync_RequestContainsSentryHeaders_ContinuesTrace()
+    [Theory]
+    [InlineData("Sentry-Trace", "4b4d2878507b43d3af7dd8c4ab7a96d9-3cc6fd1337d243de", "4b4d2878507b43d3af7dd8c4ab7a96d9")]
+    [InlineData("traceparent", "00-4b4d2878507b43d3af7dd8c4ab7a96d8-3cc6fd1337d243de-00", "4b4d2878507b43d3af7dd8c4ab7a96d8")]
+    public async Task InvokeAsync_RequestContainsSentryHeaders_ContinuesTrace(string headerName, string headerValue, string expectedTraceId)
     {
         SentryTraceHeader capturedTraceHeader = null;
         BaggageHeader capturedBaggageHeader = null;
@@ -698,7 +700,7 @@ public async Task InvokeAsync_RequestContainsSentryHeaders_ContinuesTrace()
         var request = Substitute.For<HttpRequest>();
         var fakeHeaders = new HeaderDictionary
         {
-            { "Sentry-Trace", "4b4d2878507b43d3af7dd8c4ab7a96d9-3cc6fd1337d243de"},
+            { headerName, headerValue},
             { "Baggage", "sentry-trace_id=4b4d2878507b43d3af7dd8c4ab7a96d9, sentry-public_key=eb18e953812b41c3aeb042e666fd3b5c"},
         };
         _ = request.Headers.Returns(fakeHeaders);
@@ -710,19 +712,21 @@ public async Task InvokeAsync_RequestContainsSentryHeaders_ContinuesTrace()
         _fixture.Hub.Received().ContinueTrace(Arg.Any<SentryTraceHeader>(), Arg.Any<BaggageHeader>());
 
         Assert.NotNull(capturedTraceHeader);
-        Assert.Equal("4b4d2878507b43d3af7dd8c4ab7a96d9", capturedTraceHeader.TraceId.ToString());
+        Assert.Equal(expectedTraceId, capturedTraceHeader.TraceId.ToString());
         Assert.NotNull(capturedBaggageHeader);
         Assert.Equal("sentry-trace_id=4b4d2878507b43d3af7dd8c4ab7a96d9, sentry-public_key=eb18e953812b41c3aeb042e666fd3b5c", capturedBaggageHeader.ToString());
     }
 
-    [Fact]
-    public async Task InvokeAsync_RequestContainsSentryHeaders_AddsHeadersAndTransactionContextToItems()
+    [Theory]
+    [InlineData("Sentry-Trace", "4b4d2878507b43d3af7dd8c4ab7a96d9-3cc6fd1337d243de", "4b4d2878507b43d3af7dd8c4ab7a96d9")]
+    [InlineData("traceparent", "00-4b4d2878507b43d3af7dd8c4ab7a96d8-3cc6fd1337d243de-00", "4b4d2878507b43d3af7dd8c4ab7a96d8")]
+    public async Task InvokeAsync_RequestContainsSentryHeaders_AddsHeadersAndTransactionContextToItems(string headerName, string headerValue, string expectedTraceId)
     {
         var sut = _fixture.GetSut();
         var request = Substitute.For<HttpRequest>();
         var fakeHeaders = new HeaderDictionary
         {
-            { "Sentry-Trace", "4b4d2878507b43d3af7dd8c4ab7a96d9-3cc6fd1337d243de"},
+            { headerName, headerValue},
             { "Baggage", "sentry-trace_id=4b4d2878507b43d3af7dd8c4ab7a96d9, sentry-public_key=eb18e953812b41c3aeb042e666fd3b5c"},
         };
         var contextItems = new Dictionary<object, object>();
@@ -741,22 +745,24 @@ public async Task InvokeAsync_RequestContainsSentryHeaders_AddsHeadersAndTransac
 
         var traceHeader = contextItems[SentryMiddleware.TraceHeaderItemKey] as SentryTraceHeader;
         Assert.NotNull(traceHeader);
-        Assert.Equal("4b4d2878507b43d3af7dd8c4ab7a96d9", traceHeader.TraceId.ToString());
+        Assert.Equal(expectedTraceId, traceHeader.TraceId.ToString());
         var baggageHeader = contextItems[SentryMiddleware.BaggageHeaderItemKey] as BaggageHeader;
         Assert.NotNull(baggageHeader);
         Assert.Equal("sentry-trace_id=4b4d2878507b43d3af7dd8c4ab7a96d9, sentry-public_key=eb18e953812b41c3aeb042e666fd3b5c", baggageHeader.ToString());
         var transactionContext = contextItems[SentryMiddleware.BaggageHeaderItemKey] as BaggageHeader;
         Assert.NotNull(transactionContext);
     }
 
-    [Fact]
-    public async Task InvokeAsync_InvokingWithTheSameContextTwice_DoesNotThrow()
+    [Theory]
+    [InlineData("Sentry-Trace", "4b4d2878507b43d3af7dd8c4ab7a96d9-3cc6fd1337d243de")]
+    [InlineData("traceparent", "00-4b4d2878507b43d3af7dd8c4ab7a96d8-3cc6fd1337d243de-01")]
+    public async Task InvokeAsync_InvokingWithTheSameContextTwice_DoesNotThrow(string headerName, string headerValue)
     {
         var sut = _fixture.GetSut();
         var request = Substitute.For<HttpRequest>();
         var fakeHeaders = new HeaderDictionary
         {
-            { "Sentry-Trace", "4b4d2878507b43d3af7dd8c4ab7a96d9-3cc6fd1337d243de"},
+            { headerName, headerValue},
             { "Baggage", "sentry-trace_id=4b4d2878507b43d3af7dd8c4ab7a96d9, sentry-public_key=eb18e953812b41c3aeb042e666fd3b5c"},
         };
         var contextItems = new Dictionary<object, object>();