feat: Add support for w3c trace parent headers for outgoing requests (#4661)

* feat: Add support for w3c trace parent headers for outgoing requests

* Add changelog

* Verify & bindable options

* Add more tests

* Update src/Sentry/SentryOptions.cs

---------

Co-authored-by: bitsandfoxes <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -12,6 +12,17 @@
   - Removed `SentrySdk.CaptureUserFeedback` and all associated members. Use the newer `SentrySdk.CaptureFeedback` instead.
 - Backpressure handling is now enabled by default, meaning that the SDK will monitor system health and reduce the sampling rate of events and transactions when the system is under load. When the system is determined to be healthy again, the sampling rates are returned to their original levels. ([#4615](https://github.com/getsentry/sentry-dotnet/pull/4615))
 - ScopeExtensions.Populate is now internal ([#4611](https://github.com/getsentry/sentry-dotnet/pull/4611))
+- Add support for W3C traceparent header for outgoing requests ([#4661](https://github.com/getsentry/sentry-dotnet/pull/4661))
+  This feature is disabled by default. When enabled, outgoing requests will include the W3C traceparent header.
+  ```csharp
+  SentrySdk.Init(options =>
+  {
+      // ...
+      options.PropagateTraceparent = true;
+  });
+  ```
+
+  See https://develop.sentry.dev/sdk/telemetry/traces/distributed-tracing/#w3c-trace-context-header for more details.
 
 ### Fixes
 

src/Sentry/BindableSentryOptions.cs

@@ -42,6 +42,7 @@ internal partial class BindableSentryOptions
     public bool? EnableTracing { get; set; }
     public double? TracesSampleRate { get; set; }
     public List<string>? TracePropagationTargets { get; set; }
+    public bool? PropagateTraceparent { get; set; }
     public double? ProfilesSampleRate { get; set; }
     public StackTraceMode? StackTraceMode { get; set; }
     public long? MaxAttachmentSize { get; set; }
@@ -98,6 +99,7 @@ public void ApplyTo(SentryOptions options)
         options.TracesSampleRate = TracesSampleRate ?? options.TracesSampleRate;
         options.ProfilesSampleRate = ProfilesSampleRate ?? options.ProfilesSampleRate;
         options.TracePropagationTargets = TracePropagationTargets?.Select(s => new StringOrRegex(s)).ToList() ?? options.TracePropagationTargets;
+        options.PropagateTraceparent = PropagateTraceparent ?? options.PropagateTraceparent;
         options.StackTraceMode = StackTraceMode ?? options.StackTraceMode;
         options.MaxAttachmentSize = MaxAttachmentSize ?? options.MaxAttachmentSize;
         options.DetectStartupTime = DetectStartupTime ?? options.DetectStartupTime;

src/Sentry/Extensibility/DisabledHub.cs

@@ -99,6 +99,11 @@ public void BindException(Exception exception, ISpan span)
     /// </summary>
     public BaggageHeader? GetBaggage() => null;
 
+    /// <summary>
+    /// Returns null.
+    /// </summary>
+    public W3CTraceparentHeader? GetTraceparentHeader() => null;
+
     /// <summary>
     /// Returns sampled out transaction context.
     /// </summary>

src/Sentry/Extensibility/HubAdapter.cs

@@ -140,6 +140,13 @@ public void BindException(Exception exception, ISpan span) =>
     public BaggageHeader? GetBaggage()
         => SentrySdk.GetBaggage();
 
+    /// <summary>
+    /// Forwards the call to <see cref="SentrySdk"/>.
+    /// </summary>
+    [DebuggerStepThrough]
+    public W3CTraceparentHeader? GetTraceparentHeader()
+        => SentrySdk.GetTraceparentHeader();
+
     /// <summary>
     /// Forwards the call to <see cref="SentrySdk"/>.
     /// </summary>

src/Sentry/IHub.cs

@@ -59,6 +59,11 @@ public ITransactionTracer StartTransaction(
     /// </summary>
     public BaggageHeader? GetBaggage();
 
+    /// <summary>
+    /// Gets the W3C Trace Context traceparent header that allows tracing across services
+    /// </summary>
+    public W3CTraceparentHeader? GetTraceparentHeader();
+
     /// <summary>
     /// Continues a trace based on HTTP header values provided as strings.
     /// </summary>

src/Sentry/Internal/Hub.cs

@@ -314,6 +314,18 @@ public BaggageHeader GetBaggage()
         return propagationContext.GetOrCreateDynamicSamplingContext(_options, _replaySession).ToBaggageHeader();
     }
 
+    public W3CTraceparentHeader? GetTraceparentHeader()
+    {
+        if (GetSpan()?.GetTraceHeader() is { } traceHeader)
+        {
+            return new W3CTraceparentHeader(traceHeader.TraceId, traceHeader.SpanId, traceHeader.IsSampled);
+        }
+
+        // We fall back to the propagation context
+        var propagationContext = CurrentScope.PropagationContext;
+        return new W3CTraceparentHeader(propagationContext.TraceId, propagationContext.SpanId, null);
+    }
+
     public TransactionContext ContinueTrace(
         string? traceHeader,
         string? baggageHeader,

src/Sentry/SentryMessageHandler.cs

@@ -137,6 +137,10 @@ private void PropagateTraceHeaders(HttpRequestMessage request, string url, ISpan
         {
             AddSentryTraceHeader(request, parentSpan);
             AddBaggageHeader(request);
+            if (_options?.PropagateTraceparent is true)
+            {
+                AddTraceparentHeader(request, parentSpan);
+            }
         }
     }
 
@@ -181,4 +185,16 @@ private void AddBaggageHeader(HttpRequestMessage request)
         // Set the baggage header
         request.Headers.Add(BaggageHeader.HttpHeaderName, baggage.ToString());
     }
+
+    private void AddTraceparentHeader(HttpRequestMessage request, ISpan? parentSpan)
+    {
+        // Set W3C traceparent header if it hasn't already been set
+        if (!request.Headers.Contains(W3CTraceparentHeader.HttpHeaderName) &&
+            // Use the span created by this integration as parent, instead of its own parent
+            (parentSpan?.GetTraceHeader() ?? _hub.GetTraceHeader()) is { } traceHeader)
+        {
+            var traceparentHeader = new W3CTraceparentHeader(traceHeader.TraceId, traceHeader.SpanId, traceHeader.IsSampled);
+            request.Headers.Add(W3CTraceparentHeader.HttpHeaderName, traceparentHeader.ToString());
+        }
+    }
 }

src/Sentry/SentryOptions.cs

@@ -995,6 +995,18 @@ public IList<StringOrRegex> TracePropagationTargets
         set => _tracePropagationTargets = value.WithConfigBinding();
     }
 
+    /// <summary>
+    /// Whether to send W3C Trace Context traceparent headers in outgoing HTTP requests for distributed tracing.
+    /// When enabled, the SDK will send the <c>traceparent</c> header in addition to the <c>sentry-trace</c> header
+    /// for requests matching <see cref="TracePropagationTargets"/>.
+    /// </summary>
+    /// <remarks>
+    /// The default value is <c>false</c>. Set to <c>true</c> to enable W3C Trace Context propagation
+    /// for interoperability with services that support OpenTelemetry standards.
+    /// </remarks>
+    /// <seealso href="https://develop.sentry.dev/sdk/telemetry/traces/#propagatetraceparent"/>
+    public bool PropagateTraceparent { get; set; }
+
     internal ITransactionProfilerFactory? TransactionProfilerFactory { get; set; }
 
     private StackTraceMode? _stackTraceMode;

src/Sentry/SentrySdk.cs

@@ -716,6 +716,13 @@ public static void BindException(Exception exception, ISpan span)
     public static BaggageHeader? GetBaggage()
         => CurrentHub.GetBaggage();
 
+    /// <summary>
+    /// Gets the W3C Trace Context traceparent header that allows tracing across services
+    /// </summary>
+    [DebuggerStepThrough]
+    public static W3CTraceparentHeader? GetTraceparentHeader()
+        => CurrentHub.GetTraceparentHeader();
+
     /// <summary>
     /// Continues a trace based on HTTP header values provided as strings.
     /// </summary>

src/Sentry/W3CTraceparentHeader.cs

@@ -0,0 +1,39 @@
+namespace Sentry;
+
+/// <summary>
+/// W3C Trace Context traceparent header.
+/// </summary>
+public class W3CTraceparentHeader
+{
+    internal const string HttpHeaderName = "traceparent";
+
+    /// <summary>
+    /// Trace ID.
+    /// </summary>
+    public SentryId TraceId { get; }
+
+    /// <summary>
+    /// Span ID.
+    /// </summary>
+    public SpanId SpanId { get; }
+
+    /// <summary>
+    /// Whether the trace is sampled.
+    /// </summary>
+    public bool? IsSampled { get; }
+
+    /// <summary>
+    /// Initializes an instance of <see cref="W3CTraceparentHeader"/>.
+    /// </summary>
+    public W3CTraceparentHeader(SentryId traceId, SpanId spanId, bool? isSampled)
+    {
+        TraceId = traceId;
+        SpanId = spanId;
+        IsSampled = isSampled;
+    }
+
+    /// <inheritdoc />
+    public override string ToString() => IsSampled is { } isSampled
+        ? $"00-{TraceId}-{SpanId}-{(isSampled ? "01" : "00")}"
+        : $"00-{TraceId}-{SpanId}-00";
+}