feat: auto-populate HTTP hints for network events (#8967)

* feat: add Hints API for beforeSend callbacks

Add a Hint class that provides metadata about the origin of
an event (original error/exception, attachments, key-value
data) flowing alongside events through the capture pipeline.

New beforeSendWithHint and beforeBreadcrumbWithHint callbacks
take precedence over their existing counterparts. The WithHint
variants are deprecated and will be removed in v10 when the
hint parameter is added to beforeSend/beforeBreadcrumb directly.

* docs: add changelog entry for Hints API

* Update changelog

* ref: address hints API review feedback

Guard Hint state with SentryMutex instead of NSLock, and deprecate
the WithHint callback setters via @available and
DEPRECATED_MSG_ATTRIBUTE, since the hint parameter moves into
beforeSend/beforeBreadcrumb in the next major version.

Pre-populate hint.attachments with the scope attachments before
beforeSendWithHint runs and treat the hint list as authoritative
afterwards, so the callback can remove attachments as well as add
them. Add concurrency tests for Hint and attachment add/remove
coverage for the client.

* docs: add changelog entry for capture hints

* feat: add hint to public capture methods

Thread user-provided SentryHint through
SentrySDK -> SentryHub -> SentryClient capture
methods, matching sentry-java's pattern for
beforeSend callbacks.

* feat: auto-populate HTTP hints for network events

Attach URLRequest and HTTPURLResponse to hints for
network breadcrumbs and HTTP client error events so
beforeSendWithHint and beforeBreadcrumbWithHint
callbacks can access the original HTTP context.

* Fix changelog entry

* Run generate api

* feat: expose HTTP hint properties on SentryObjCHint

Add urlRequest and httpResponse to SentryObjCHint so
Objective-C consumers can access auto-populated HTTP
metadata in beforeSend and beforeBreadcrumb callbacks.

Author: itaybre

CHANGELOG.md

@@ -7,6 +7,7 @@
 - Add a `device.event` breadcrumb (`SYSTEM_CLOCK_CHANGE`) when the system clock changes, for example due to a manual time change or NTP sync (#8946)
 - Add Hints API with `beforeSendWithHint` and `beforeBreadcrumbWithHint` callbacks (#8942)
 - Add hint parameter to public capture methods on `SentrySDK` (#8955)
+- Auto-populate HTTP request and response on hints for network breadcrumbs and HTTP client errors (#8967)
 
 ### Fixes
 

SentryTestUtils/Sources/TestHub.swift

@@ -57,12 +57,21 @@ public class TestHub: SentryTestHubWrapper {
     }
 
     @_spi(Private) public var capturedErrorEvents = Invocations<Event>()
+    @_spi(Private) public var capturedErrorHints = Invocations<Hint>()
     public override func captureErrorEvent(event: Event) -> SentryId {
         self.capturedErrorEvents.record((event))
 
         return event.eventId
     }
 
+    public override func captureErrorEvent(_ event: Event, withHint hint: Any?) -> SentryId {
+        self.capturedErrorEvents.record(event)
+        if let hint = hint as? Hint {
+            self.capturedErrorHints.record(hint)
+        }
+        return event.eventId
+    }
+
     public var capturedTransactionsWithScope = Invocations<(transaction: [String: Any], scope: Scope)>()
     public override func capture(_ transaction: Transaction, with scope: Scope) {
         capturedTransactionsWithScope.record((transaction.serialize(), scope))

Sources/Sentry/SentryHub.m

@@ -670,6 +670,20 @@ - (SentryId *)captureErrorEvent:(SentryEvent *)event
     return SentryId.empty;
 }
 
+- (SentryId *)captureErrorEvent:(SentryEvent *)event withHint:(id _Nullable)hint
+{
+    SentryScope *scope = self.scope;
+    SentryClientInternal *client = self.client;
+
+    if (client != nil) {
+        SentryHint *resolvedHint = hint ?: [[SentryHint alloc] init];
+        return [client captureEventIncrementingSessionErrorCount:event
+                                                       withScope:scope
+                                                            hint:resolvedHint];
+    }
+    return SentryId.empty;
+}
+
 - (void)captureFeedback:(SentryFeedback *)feedback
 {
     SentryClientInternal *client = self.client;
@@ -692,15 +706,20 @@ - (void)captureSerializedFeedback:(NSDictionary *)serializedFeedback
 }
 
 - (void)addBreadcrumb:(SentryBreadcrumb *)crumb
+{
+    [self addBreadcrumb:crumb withHint:nil];
+}
+
+- (void)addBreadcrumb:(SentryBreadcrumb *)crumb withHint:(id _Nullable)hint
 {
     SentryOptions *options = [[self client] options];
     if (options.maxBreadcrumbs < 1) {
         return;
     }
     SentryBreadcrumb *_Nullable nullableCrumb = crumb;
     if (options.beforeBreadcrumbWithHint != nil) {
-        SentryHint *hint = [[SentryHint alloc] init];
-        nullableCrumb = options.beforeBreadcrumbWithHint(crumb, hint);
+        SentryHint *resolvedHint = hint ?: [[SentryHint alloc] init];
+        nullableCrumb = options.beforeBreadcrumbWithHint(crumb, resolvedHint);
     } else {
         SentryBeforeBreadcrumbCallback callback = [options beforeBreadcrumb];
         if (callback != nil) {

Sources/Sentry/SentrySDKInternal.m

@@ -498,6 +498,11 @@ + (SentryFeedbackAPI *)feedback
 #endif // TARGET_OS_IOS && SENTRY_HAS_UIKIT
 
 + (void)addBreadcrumb:(SentryBreadcrumb *)crumb
+{
+    [self addBreadcrumb:crumb withHint:nil];
+}
+
++ (void)addBreadcrumb:(SentryBreadcrumb *)crumb withHint:(id _Nullable)hint
 {
     if (![SentrySDKInternal isEnabled]) {
         // We must log with level fatal because only fatal messages get logged even when the SDK
@@ -510,7 +515,7 @@ + (void)addBreadcrumb:(SentryBreadcrumb *)crumb
             @"the SDK before adding breadcrumbs.");
     }
 
-    [SentrySDKInternal.currentHub addBreadcrumb:crumb];
+    [SentrySDKInternal.currentHub addBreadcrumb:crumb withHint:hint];
 }
 
 + (void)configureScope:(void (^)(SentryScope *scope))callback

Sources/Sentry/include/SentryClient+Private.h

@@ -61,6 +61,10 @@ NS_ASSUME_NONNULL_BEGIN
 - (SentryId *)captureEventIncrementingSessionErrorCount:(SentryEvent *)event
                                               withScope:(SentryScope *)scope;
 
+- (SentryId *)captureEventIncrementingSessionErrorCount:(SentryEvent *)event
+                                              withScope:(SentryScope *)scope
+                                                   hint:(SentryHint *)hint;
+
 - (SentryId *)captureError:(NSError *)error
                  withScope:(SentryScope *)scope
           attachAllThreads:(nullable NSNumber *)attachAllThreads

Sources/Sentry/include/SentryHub+Private.h

@@ -77,6 +77,12 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (SentryId *)captureErrorEvent:(SentryEvent *)event NS_SWIFT_NAME(captureErrorEvent(event:));
 
+- (SentryId *)captureErrorEvent:(SentryEvent *)event
+                       withHint:(SENTRY_SWIFT_MIGRATION_ID(SentryHint)_Nullable)hint;
+
+- (void)addBreadcrumb:(SentryBreadcrumb *)crumb
+             withHint:(SENTRY_SWIFT_MIGRATION_ID(SentryHint)_Nullable)hint;
+
 - (SentryId *)captureError:(NSError *)error
                  withScope:(SentryScope *)scope
           attachAllThreads:(nullable NSNumber *)attachAllThreads;

Sources/Sentry/include/SentrySDKInternal.h

@@ -310,6 +310,9 @@ SENTRY_NO_INIT
  */
 + (void)addBreadcrumb:(SentryBreadcrumb *)crumb NS_SWIFT_NAME(addBreadcrumb(_:));
 
++ (void)addBreadcrumb:(SentryBreadcrumb *)crumb
+             withHint:(SENTRY_SWIFT_MIGRATION_ID(SentryHint)_Nullable)hint;
+
 /**
  * Use this method to modify the current Scope of the current Hub. The SDK uses the Scope to attach
  * contextual data to events.

Sources/SentryObjC/Public/SentryObjCHint.h

@@ -24,6 +24,14 @@ NS_ASSUME_NONNULL_BEGIN
 /// The original @c NSException that triggered the event capture, if any.
 @property (nonatomic, strong, nullable) NSException *originalException;
 
+/// The @c NSURLRequest associated with the event or breadcrumb, if it originated from a network
+/// operation.
+@property (nonatomic, strong, nullable) NSURLRequest *urlRequest;
+
+/// The @c NSHTTPURLResponse associated with the event or breadcrumb, if it originated from a
+/// network operation.
+@property (nonatomic, strong, nullable) NSHTTPURLResponse *httpResponse;
+
 /**
  * The attachments that will be sent alongside the event.
  *

Sources/SentryObjCCompat/SentryObjCHint.swift

@@ -35,6 +35,16 @@ import Foundation
         set { wrapped.originalException = newValue }
     }
 
+    @objc public var urlRequest: URLRequest? {
+        get { wrapped.urlRequest }
+        set { wrapped.urlRequest = newValue }
+    }
+
+    @objc public var httpResponse: HTTPURLResponse? {
+        get { wrapped.httpResponse }
+        set { wrapped.httpResponse = newValue }
+    }
+
     @objc public var attachments: [SentryObjCAttachment] {
         get { wrapped.attachments.map { SentryObjCAttachment($0) } }
         set { wrapped.attachments = newValue.map(\.wrapped) }

Sources/Swift/Networking/SentryNetworkTracker.swift

@@ -490,7 +490,12 @@ final class SentryDefaultNetworkTracker<Dependencies: SentryDefaultNetworkTracke
         }
         event.context = context
 
-        _ = hub.captureErrorEvent(event: event)
+        let hint = Hint()
+        hint.urlRequest = currentRequest
+        if let httpResponse = sessionTask.response as? HTTPURLResponse {
+            hint.httpResponse = httpResponse
+        }
+        _ = hub.captureErrorEvent(event: event, hint: hint)
     }
 
     private func containsStatusCode(_ statusCode: Int, options: Options) -> Bool {
@@ -573,7 +578,13 @@ final class SentryDefaultNetworkTracker<Dependencies: SentryDefaultNetworkTracke
 
         let breadcrumb = Breadcrumb(level: level, category: "http", data: data)
         breadcrumb.type = "http"
-        SentrySDKInternal.addBreadcrumb(breadcrumb)
+
+        let hint = Hint()
+        hint.urlRequest = currentRequest
+        if let httpResponse = sessionTask.response as? HTTPURLResponse {
+            hint.httpResponse = httpResponse
+        }
+        SentrySDKInternal.add(breadcrumb, withHint: hint)
     }
 
     // MARK: - Span status