feat: Add propagating of traceparent

philipphofmann · philipphofmann · commit 76588285b097 · 2025-10-06T11:13:36.000+02:00
Add the option propagateTraceparent, which is disabled by default. When enabled, it adds the W3C Trace Context HTTP header traceparent on outgoing HTTP requests. This is useful when the receiving services only support OTel/W3C propagation. Fixes GH-6017
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ Removes `enablePerformanceV2` option and makes this the default. The app start d
 ### Features
 
 - Add SentryDistribution as Swift Package Manager target (#6149)
+- Add option `enablePropagateTraceparent` to support OTel/W3C trace propagation (#6356)
 
 ### Fixes
 
diff --git a/Sources/Sentry/Public/SentryOptions.h b/Sources/Sentry/Public/SentryOptions.h
@@ -699,6 +699,18 @@ typedef void (^SentryProfilingConfigurationBlock)(SentryProfileOptions *_Nonnull
  */
 @property (nonatomic, assign) BOOL enableAutoBreadcrumbTracking;
 
+/**
+ * When enabled, the SDK propagates the W3C Trace Context HTTP header traceparent on outgoing HTTP
+ * requests.
+ *
+ * @discussion This is useful when the receiving services only support OTel/W3C propagation. The
+ * traceparent header is only sent when propagateTraceparent is @c YES and the request matches @c
+ * tracePropagationTargets.
+ *
+ * @note Default value is @c NO.
+ */
+@property (nonatomic, assign) BOOL enablePropagateTraceparent;
+
 /**
  * An array of hosts or regexes that determines if outgoing HTTP requests will get
  * extra @c trace_id and @c baggage headers added.
diff --git a/Sources/Sentry/Public/SentryTraceHeader.h b/Sources/Sentry/Public/SentryTraceHeader.h
@@ -13,6 +13,7 @@
 NS_ASSUME_NONNULL_BEGIN
 
 static NSString *const SENTRY_TRACE_HEADER = @"sentry-trace";
+static NSString *const SENTRY_TRACEPARENT = @"traceparent";
 
 NS_SWIFT_NAME(TraceHeader)
 @interface SentryTraceHeader : NSObject
@@ -46,6 +47,8 @@ SENTRY_NO_INIT
  */
 - (NSString *)value;
 
+- (NSString *)traceParentValue;
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/Sources/Sentry/SentryNetworkTracker.m b/Sources/Sentry/SentryNetworkTracker.m
@@ -189,10 +189,12 @@ - (void)urlSessionTaskResume:(NSURLSessionTask *)sessionTask
         }
 
         SentryBaggage *baggage = [[[SentryTracer getTracer:span] traceContext] toBaggage];
-        [SentryTracePropagation addBaggageHeader:baggage
-                                     traceHeader:[netSpan toTraceHeader]
-                         tracePropagationTargets:SentrySDKInternal.options.tracePropagationTargets
-                                       toRequest:sessionTask];
+        [SentryTracePropagation
+                   addBaggageHeader:baggage
+                        traceHeader:[netSpan toTraceHeader]
+               propagateTraceparent:SentrySDKInternal.options.enablePropagateTraceparent
+            tracePropagationTargets:SentrySDKInternal.options.tracePropagationTargets
+                          toRequest:sessionTask];
 
         SENTRY_LOG_DEBUG(
             @"SentryNetworkTracker automatically started HTTP span for sessionTask: %@",
@@ -226,6 +228,7 @@ - (void)addTraceWithoutTransactionToTask:(NSURLSessionTask *)sessionTask
 
     [SentryTracePropagation addBaggageHeader:[traceContext toBaggage]
                                  traceHeader:[propagationContext traceHeader]
+                        propagateTraceparent:SentrySDKInternal.options.enablePropagateTraceparent
                      tracePropagationTargets:SentrySDKInternal.options.tracePropagationTargets
                                    toRequest:sessionTask];
 }
diff --git a/Sources/Sentry/SentryOptions.m b/Sources/Sentry/SentryOptions.m
@@ -121,6 +121,7 @@ - (instancetype)init
         self.enableAppHangTracking = YES;
         self.appHangTimeoutInterval = 2.0;
         self.enableAutoBreadcrumbTracking = YES;
+        self.enablePropagateTraceparent = NO;
         self.enableNetworkTracking = YES;
         self.enableFileIOTracing = YES;
         self.enableNetworkBreadcrumbs = YES;
diff --git a/Sources/Sentry/SentryTraceHeader.m b/Sources/Sentry/SentryTraceHeader.m
@@ -30,6 +30,12 @@ - (NSString *)value
         : [NSString stringWithFormat:@"%@-%@", _traceId.sentryIdString, _spanId.sentrySpanIdString];
 }
 
+- (NSString *)traceParentValue
+{
+    return [NSString stringWithFormat:@"00-%@-%@-0%i", _traceId.sentryIdString,
+        _spanId.sentrySpanIdString, _sampled == kSentrySampleDecisionYes ? 1 : 0];
+}
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/Sources/Sentry/SentryTracePropagation.m b/Sources/Sentry/SentryTracePropagation.m
@@ -8,6 +8,7 @@ @implementation SentryTracePropagation
 
 + (void)addBaggageHeader:(SentryBaggage *)baggage
                 traceHeader:(SentryTraceHeader *)traceHeader
+       propagateTraceparent:(BOOL)propagateTraceparent
     tracePropagationTargets:(NSArray *)tracePropagationTargets
                   toRequest:(NSURLSessionTask *)sessionTask
 {
@@ -33,14 +34,10 @@ + (void)addBaggageHeader:(SentryBaggage *)baggage
     // header.
     if ([sessionTask.currentRequest isKindOfClass:[NSMutableURLRequest class]]) {
         NSMutableURLRequest *currentRequest = (NSMutableURLRequest *)sessionTask.currentRequest;
-
-        if ([currentRequest valueForHTTPHeaderField:SENTRY_TRACE_HEADER] == nil) {
-            [currentRequest setValue:traceHeader.value forHTTPHeaderField:SENTRY_TRACE_HEADER];
-        }
-
-        if (baggageHeader.length > 0) {
-            [currentRequest setValue:baggageHeader forHTTPHeaderField:SENTRY_BAGGAGE_HEADER];
-        }
+        [SentryTracePropagation addHeaderFieldsToRequest:currentRequest
+                                             traceHeader:traceHeader
+                                           baggageHeader:baggageHeader
+                                    propagateTraceparent:propagateTraceparent];
     } else {
         // Even though NSURLSessionTask doesn't have 'setCurrentRequest', some subclasses
         // do. For those subclasses we replace the currentRequest with a mutable one with
@@ -49,14 +46,10 @@ + (void)addBaggageHeader:(SentryBaggage *)baggage
         SEL setCurrentRequestSelector = NSSelectorFromString(@"setCurrentRequest:");
         if ([sessionTask respondsToSelector:setCurrentRequestSelector]) {
             NSMutableURLRequest *newRequest = [sessionTask.currentRequest mutableCopy];
-
-            if ([newRequest valueForHTTPHeaderField:SENTRY_TRACE_HEADER] == nil) {
-                [newRequest setValue:traceHeader.value forHTTPHeaderField:SENTRY_TRACE_HEADER];
-            }
-
-            if (baggageHeader.length > 0) {
-                [newRequest setValue:baggageHeader forHTTPHeaderField:SENTRY_BAGGAGE_HEADER];
-            }
+            [SentryTracePropagation addHeaderFieldsToRequest:newRequest
+                                                 traceHeader:traceHeader
+                                               baggageHeader:baggageHeader
+                                        propagateTraceparent:propagateTraceparent];
 
             void (*func)(id, SEL, id param)
                 = (void *)[sessionTask methodForSelector:setCurrentRequestSelector];
@@ -73,6 +66,24 @@ + (BOOL)sessionTaskRequiresPropagation:(NSURLSessionTask *)sessionTask
                                   withTargets:tracePropagationTargets];
 }
 
++ (void)addHeaderFieldsToRequest:(NSMutableURLRequest *)request
+                     traceHeader:(SentryTraceHeader *)traceHeader
+                   baggageHeader:(NSString *)baggageHeader
+            propagateTraceparent:(BOOL)propagateTraceparent
+{
+    if ([request valueForHTTPHeaderField:SENTRY_TRACE_HEADER] == nil) {
+        [request setValue:traceHeader.value forHTTPHeaderField:SENTRY_TRACE_HEADER];
+    }
+
+    if (propagateTraceparent && [request valueForHTTPHeaderField:SENTRY_TRACEPARENT] == nil) {
+        [request setValue:traceHeader.traceParentValue forHTTPHeaderField:SENTRY_TRACEPARENT];
+    }
+
+    if (baggageHeader.length > 0) {
+        [request setValue:baggageHeader forHTTPHeaderField:SENTRY_BAGGAGE_HEADER];
+    }
+}
+
 + (BOOL)isTargetMatch:(NSURL *)URL withTargets:(NSArray *)targets
 {
     for (id targetCheck in targets) {
diff --git a/Sources/Sentry/include/SentryTracePropagation.h b/Sources/Sentry/include/SentryTracePropagation.h
@@ -9,6 +9,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 + (void)addBaggageHeader:(SentryBaggage *)baggage
                 traceHeader:(SentryTraceHeader *)traceHeader
+       propagateTraceparent:(BOOL)propagateTraceparent
     tracePropagationTargets:(NSArray *)tracePropagationTargets
                   toRequest:(NSURLSessionTask *)sessionTask;
 
diff --git a/Tests/SentryTests/Integrations/Performance/Network/SentryNetworkTrackerTests.swift b/Tests/SentryTests/Integrations/Performance/Network/SentryNetworkTrackerTests.swift
@@ -39,6 +39,7 @@ class SentryNetworkTrackerTests: XCTestCase {
         init() {
             options = Options()
             options.dsn = SentryNetworkTrackerTests.dsnAsString
+            options.enablePropagateTraceparent = true
             sentryTask = URLSessionDataTaskMock(request: URLRequest(url: URL(string: options.dsn!)!))
             scope = Scope()
             client = TestClient(options: options)
@@ -915,6 +916,48 @@ class SentryNetworkTrackerTests: XCTestCase {
         XCTAssertEqual(task.currentRequest?.allHTTPHeaderFields?["sentry-trace"] ?? "", "test")
     }
 
+    func testPropagateTraceparent() throws {
+        // Arrange
+        let sut = fixture.getSut()
+        let task = createDataTask()
+        let transaction = try XCTUnwrap(startTransaction() as? SentryTracer)
+
+        // Act
+        sut.urlSessionTaskResume(task)
+
+        // Assert
+        let children = try XCTUnwrap(Dynamic(transaction).children.asArray as? [SentrySpan])
+        let networkSpan = try XCTUnwrap(children.first)
+        let expectedTraceHeader = networkSpan.toTraceHeader().traceParentValue()
+        XCTAssertEqual(task.currentRequest?.allHTTPHeaderFields?["traceparent"] ?? "", expectedTraceHeader)
+    }
+
+    func testPropagateTraceparent_WhenDisabled_NotAdded() throws {
+        // Arrange
+        let sut = fixture.getSut()
+        let task = createDataTask()
+        _ = try XCTUnwrap(startTransaction() as? SentryTracer)
+        fixture.options.enablePropagateTraceparent = false
+
+        // Act
+        sut.urlSessionTaskResume(task)
+
+        // Assert
+        XCTAssertNil(task.currentRequest?.allHTTPHeaderFields?["traceparent"])
+    }
+
+    func testDontOverrideTraceparent() {
+        let sut = fixture.getSut()
+        let task = createDataTask {
+            var request = $0
+            request.setValue("test", forHTTPHeaderField: "traceparent")
+            return request
+        }
+        sut.urlSessionTaskResume(task)
+
+        XCTAssertEqual(task.currentRequest?.allHTTPHeaderFields?["traceparent"] ?? "", "test")
+    }
+
     @available(*, deprecated)
     func testDefaultHeadersWhenDisabled() throws {
         let sut = fixture.getSut()
diff --git a/Tests/SentryTests/Integrations/Performance/Network/SentryTracePropagationTests.swift b/Tests/SentryTests/Integrations/Performance/Network/SentryTracePropagationTests.swift
@@ -2,6 +2,58 @@ import XCTest
 
 final class SentryTracePropagationTests: XCTestCase {
 
+    func testAddTraceparent_Sampled() throws {
+        // Arrange
+        let defaultRegex = try XCTUnwrap(NSRegularExpression(pattern: ".*"))
+        let emptyBaggage = Baggage()
+        let sessionTask = try createSessionTask()
+
+        let traceID = SentryId()
+        let spanID = SpanId()
+        let traceHeader = TraceHeader(trace: traceID, spanId: spanID, sampled: SentrySampleDecision.yes)
+
+        // Act
+        SentryTracePropagation.addBaggageHeader(emptyBaggage, traceHeader: traceHeader, propagateTraceparent: true, tracePropagationTargets: [defaultRegex], toRequest: sessionTask)
+
+        // Assert
+        let traceParent = try XCTUnwrap(sessionTask.currentRequest?.allHTTPHeaderFields?["traceparent"])
+        XCTAssertEqual(traceParent, "00-\(traceID.sentryIdString)-\(spanID.sentrySpanIdString)-01")
+    }
+
+    func testAddTraceparent_NotSampled() throws {
+        // Arrange
+        let defaultRegex = try XCTUnwrap(NSRegularExpression(pattern: ".*"))
+        let emptyBaggage = Baggage()
+        let sessionTask = try createSessionTask()
+
+        let traceID = SentryId()
+        let spanID = SpanId()
+        let traceHeader = TraceHeader(trace: traceID, spanId: spanID, sampled: SentrySampleDecision.no)
+
+        // Act
+        SentryTracePropagation.addBaggageHeader(emptyBaggage, traceHeader: traceHeader, propagateTraceparent: true, tracePropagationTargets: [defaultRegex], toRequest: sessionTask)
+
+        // Assert
+        let traceParent = try XCTUnwrap(sessionTask.currentRequest?.allHTTPHeaderFields?["traceparent"])
+        XCTAssertEqual(traceParent, "00-\(traceID.sentryIdString)-\(spanID.sentrySpanIdString)-00")
+    }
+
+    func testAddTraceparent_NotAddedWhenTargetDoesntMatch() throws {
+        // Arrange
+        let emptyBaggage = Baggage()
+        let sessionTask = try createSessionTask()
+
+        let traceID = SentryId()
+        let spanID = SpanId()
+        let traceHeader = TraceHeader(trace: traceID, spanId: spanID, sampled: SentrySampleDecision.no)
+
+        // Act
+        SentryTracePropagation.addBaggageHeader(emptyBaggage, traceHeader: traceHeader, propagateTraceparent: true, tracePropagationTargets: ["localhost"], toRequest: sessionTask)
+
+        // Assert
+        XCTAssertNil(sessionTask.currentRequest?.allHTTPHeaderFields?["traceparent"])
+    }
+
     func testIsTargetMatchWithDefaultRegex_MatchesAllURLs() throws {
         // Arrange
         let defaultRegex = try XCTUnwrap(NSRegularExpression(pattern: ".*"))
@@ -77,4 +129,11 @@ final class SentryTracePropagationTests: XCTestCase {
         XCTAssertTrue(SentryTracePropagation.isTargetMatch(localhostURL, withTargets: targetsWithInvalidType))
     }
 
+    private func createSessionTask(method: String = "GET") throws -> URLSessionDownloadTaskMock {
+        let url = try XCTUnwrap(URL(string: "https://www.domain.com/api?query=value&query2=value2#fragment"))
+        var request = URLRequest(url: url)
+        request.httpMethod = method
+        return URLSessionDownloadTaskMock(request: request)
+    }
+
 }
diff --git a/Tests/SentryTests/SentryOptionsTest.m b/Tests/SentryTests/SentryOptionsTest.m
@@ -207,6 +207,11 @@ - (void)testEnableAutoBreadcrumbTracking
     [self testBooleanField:@"enableAutoBreadcrumbTracking"];
 }
 
+- (void)testEnablePropagateTraceparent
+{
+    [self testBooleanField:@"enablePropagateTraceparent"];
+}
+
 - (void)testEnableCoreDataTracking
 {
     [self testBooleanField:@"enableCoreDataTracing" defaultValue:YES];
