feat: Add propagating of traceparent

CHANGELOG.md

@@ -18,6 +18,7 @@
 ### Features
 
 - Add SentryDistribution as Swift Package Manager target (#6149)
+- Add option `enablePropagateTraceparent` to support OTel/W3C trace propagation (#6356)
 
 ### Fixes
 

Sources/Sentry/Public/SentryOptions.h

@@ -695,6 +695,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 this option 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.

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];
 }

Sources/Sentry/SentryOptions.m

@@ -114,6 +114,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;

Sources/Sentry/SentryTracePropagation.m

@@ -4,10 +4,13 @@
 #import <SentryTraceHeader.h>
 #import <SentryTracePropagation.h>
 
+static NSString *const SENTRY_TRACEPARENT = @"traceparent";
+
 @implementation SentryTracePropagation
 
 + (void)addBaggageHeader:(SentryBaggage *)baggage
                 traceHeader:(SentryTraceHeader *)traceHeader
+       propagateTraceparent:(BOOL)propagateTraceparent
     tracePropagationTargets:(NSArray *)tracePropagationTargets
                   toRequest:(NSURLSessionTask *)sessionTask
 {
@@ -21,7 +24,7 @@
 
     if (baggage != nil) {
         NSDictionary *originalBaggage = [SentryBaggageSerialization
             decode:sessionTask.currentRequest.allHTTPHeaderFields[SENTRY_BAGGAGE_HEADER]];
 
         if (originalBaggage[@"sentry-trace_id"] == nil) {
             baggageHeader = [baggage toHTTPHeaderWithOriginalBaggage:originalBaggage];
@@ -33,14 +36,10 @@
     // 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 +48,10 @@
         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];
@@ -69,10 +64,33 @@
                tracePropagationTargets:(NSArray *)tracePropagationTargets
 {
     return sessionTask.currentRequest != nil &&
         [SentryTracePropagation isTargetMatch:sessionTask.currentRequest.URL
                                   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) {
+
+        NSString *traceparent = [NSString stringWithFormat:@"00-%@-%@-%02x",
+            traceHeader.traceId.sentryIdString, traceHeader.spanId.sentrySpanIdString,
+            traceHeader.sampled == kSentrySampleDecisionYes ? 1 : 0];
+
+        [request setValue:traceparent 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) {

Sources/Sentry/SentyOptionsInternal.m

@@ -386,6 +386,9 @@ + (BOOL)validateOptions:(NSDictionary<NSString *, id> *)options
     [self setBool:options[@"enableAutoBreadcrumbTracking"]
             block:^(BOOL value) { sentryOptions.enableAutoBreadcrumbTracking = value; }];
 
+    [self setBool:options[@"enablePropagateTraceparent"]
+            block:^(BOOL value) { sentryOptions.enablePropagateTraceparent = value; }];
+
     if ([options[@"tracePropagationTargets"] isKindOfClass:[NSArray class]]) {
         sentryOptions.tracePropagationTargets
             = SENTRY_UNWRAP_NULLABLE(NSArray, options[@"tracePropagationTargets"]);

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;
 

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,50 @@ 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 traceHeader = transaction.toTraceHeader()
+        let expectedTraceHeader = "00-\(traceHeader.traceId.sentryIdString)-\(networkSpan.spanId.sentrySpanIdString)-00"
+        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()

Tests/SentryTests/Integrations/Performance/Network/SentryTracePropagationTests.swift

@@ -2,6 +2,76 @@ 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_UndecidedSampled() 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.undecided)
+
+        // 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 +147,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)
+    }
+
 }

Tests/SentryTests/SentryOptionsTest.m

@@ -212,6 +212,11 @@ - (void)testEnableAutoBreadcrumbTracking
     [self testBooleanField:@"enableAutoBreadcrumbTracking"];
 }
 
+- (void)testEnablePropagateTraceparent
+{
+    [self testBooleanField:@"enablePropagateTraceparent" defaultValue:NO];
+}
+
 - (void)testEnableCoreDataTracking
 {
     [self testBooleanField:@"enableCoreDataTracing" defaultValue:YES];