feat: Add onCrashedLastRun (#808)

Add a callback onCrashedLastRun to SentryOptions that is called by the SDK passing the eventId
when Sentry is initialized and the last program execution terminated with a crash.

Fixes GH-699

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## unreleased
 
+- feat: Add onCrashedLastRun #808
 - feat: Add SentrySdkInfo to SentryOptions #859
 
 ## 6.0.9

Sources/Sentry/Public/SentryDefines.h

@@ -48,6 +48,11 @@ typedef SentryBreadcrumb *_Nullable (^SentryBeforeBreadcrumbCallback)(
  */
 typedef SentryEvent *_Nullable (^SentryBeforeSendEventCallback)(SentryEvent *_Nonnull event);
 
+/**
+ * A callback to be notified when the last program execution terminated with a crash.
+ */
+typedef void (^SentryOnCrashedLastRunCallback)(SentryEvent *_Nonnull event);
+
 /**
  * Block can be used to determine if an event should be queued and stored
  * locally. It will be tried to send again after next successful send. Note that

Sources/Sentry/Public/SentryOptions.h

@@ -79,6 +79,17 @@ NS_SWIFT_NAME(Options)
  */
 @property (nonatomic, copy) SentryBeforeBreadcrumbCallback _Nullable beforeBreadcrumb;
 
+/**
+ * This gets called shortly after the initialization of the SDK when the last program execution
+ * terminated with a crash. It is not guaranteed that this is called on the main thread.
+ *
+ * @discussion This callback is only executed once during the entire run of the program to avoid
+ * multiple callbacks if there are multiple crash events to send. This can happen when the program
+ * terminates with a crash before the SDK can send the crash event. You can look into beforeSend if
+ * you prefer a callback for every event.
+ */
+@property (nonatomic, copy) SentryOnCrashedLastRunCallback _Nullable onCrashedLastRun;
+
 /**
  * Array of integrations to install.
  */

Sources/Sentry/SentryClient.m

@@ -17,6 +17,7 @@
 #import "SentryMessage.h"
 #import "SentryMeta.h"
 #import "SentryOptions.h"
+#import "SentrySDK+Private.h"
 #import "SentryScope.h"
 #import "SentryStacktraceBuilder.h"
 #import "SentryThreadInspector.h"
@@ -175,13 +176,19 @@ - (SentryEvent *)buildErrorEvent:(NSError *)error
     return event;
 }
 
-- (SentryId *)captureEvent:(SentryEvent *)event
-               withSession:(SentrySession *)session
-                 withScope:(SentryScope *)scope
+- (SentryId *)captureCrashEvent:(SentryEvent *)event withScope:(SentryScope *)scope
+{
+    return [self sendEvent:event withScope:scope alwaysAttachStacktrace:NO isCrashEvent:YES];
+}
+
+- (SentryId *)captureCrashEvent:(SentryEvent *)event
+                    withSession:(SentrySession *)session
+                      withScope:(SentryScope *)scope
 {
     SentryEvent *preparedEvent = [self prepareEvent:event
                                           withScope:scope
-                             alwaysAttachStacktrace:NO];
+                             alwaysAttachStacktrace:NO
+                                       isCrashEvent:YES];
     return [self sendEvent:preparedEvent withSession:session];
 }
 
@@ -198,10 +205,22 @@ - (SentryId *)captureEvent:(SentryEvent *)event withScope:(SentryScope *)scope
 - (SentryId *)sendEvent:(SentryEvent *)event
                  withScope:(SentryScope *)scope
     alwaysAttachStacktrace:(BOOL)alwaysAttachStacktrace
+{
+    return [self sendEvent:event
+                     withScope:scope
+        alwaysAttachStacktrace:alwaysAttachStacktrace
+                  isCrashEvent:NO];
+}
+
+- (SentryId *)sendEvent:(SentryEvent *)event
+                 withScope:(SentryScope *)scope
+    alwaysAttachStacktrace:(BOOL)alwaysAttachStacktrace
+              isCrashEvent:(BOOL)isCrashEvent
 {
     SentryEvent *preparedEvent = [self prepareEvent:event
                                           withScope:scope
-                             alwaysAttachStacktrace:alwaysAttachStacktrace];
+                             alwaysAttachStacktrace:alwaysAttachStacktrace
+                                       isCrashEvent:isCrashEvent];
 
     if (nil != preparedEvent) {
         [self.transport sendEvent:preparedEvent];
@@ -289,6 +308,17 @@ - (BOOL)checkSampleRate:(NSNumber *)sampleRate
 - (SentryEvent *_Nullable)prepareEvent:(SentryEvent *)event
                              withScope:(SentryScope *)scope
                 alwaysAttachStacktrace:(BOOL)alwaysAttachStacktrace
+{
+    return [self prepareEvent:event
+                     withScope:scope
+        alwaysAttachStacktrace:alwaysAttachStacktrace
+                  isCrashEvent:NO];
+}
+
+- (SentryEvent *_Nullable)prepareEvent:(SentryEvent *)event
+                             withScope:(SentryScope *)scope
+                alwaysAttachStacktrace:(BOOL)alwaysAttachStacktrace
+                          isCrashEvent:(BOOL)isCrashEvent
 {
     NSParameterAssert(event);
     if ([self isDisabled]) {
@@ -340,12 +370,12 @@ - (SentryEvent *_Nullable)prepareEvent:(SentryEvent *)event
         || (nil != event.exceptions && [event.exceptions count] > 0);
 
     BOOL debugMetaNotAttached = !(nil != event.debugMeta && event.debugMeta.count > 0);
-    if (shouldAttachStacktrace && debugMetaNotAttached) {
+    if (!isCrashEvent && shouldAttachStacktrace && debugMetaNotAttached) {
         event.debugMeta = [self.debugMetaBuilder buildDebugMeta];
     }
 
     BOOL threadsNotAttached = !(nil != event.threads && event.threads.count > 0);
-    if (shouldAttachStacktrace && threadsNotAttached) {
+    if (!isCrashEvent && shouldAttachStacktrace && threadsNotAttached) {
         event.threads = [self.threadInspector getCurrentThreads];
     }
 
@@ -366,6 +396,13 @@ - (SentryEvent *_Nullable)prepareEvent:(SentryEvent *)event
         event = self.options.beforeSend(event);
     }
 
+    if (isCrashEvent && nil != self.options.onCrashedLastRun && !SentrySDK.crashedLastRunCalled) {
+        // We only want to call the callback once. It can occur that multiple crash events are
+        // about to be sent.
+        self.options.onCrashedLastRun(event);
+        SentrySDK.crashedLastRunCalled = YES;
+    }
+
     return event;
 }
 

Sources/Sentry/SentryHub.m

@@ -203,13 +203,13 @@ - (void)captureCrashEvent:(SentryEvent *)event
         // It can be that there is no session yet, because autoSessionTracking was just enabled and
         // there is a previous crash on disk. In this case we just send the crash event.
         if (nil != crashedSession) {
-            [client captureEvent:event withSession:crashedSession withScope:self.scope];
+            [client captureCrashEvent:event withSession:crashedSession withScope:self.scope];
             [fileManager deleteCrashedSession];
             return;
         }
     }
 
-    [self captureEvent:event withScope:self.scope];
+    [client captureCrashEvent:event withScope:self.scope];
 }
 
 - (SentryId *)captureEvent:(SentryEvent *)event

Sources/Sentry/SentryOptions.m

@@ -128,6 +128,10 @@ - (void)validateOptions:(NSDictionary<NSString *, id> *)options
         self.beforeBreadcrumb = options[@"beforeBreadcrumb"];
     }
 
+    if (nil != options[@"onCrashedLastRun"]) {
+        self.onCrashedLastRun = options[@"onCrashedLastRun"];
+    }
+
     if (nil != options[@"integrations"]) {
         self.integrations = options[@"integrations"];
     }

Sources/Sentry/SentrySDK.m

@@ -23,6 +23,7 @@
 @implementation SentrySDK
 
 static SentryHub *currentHub;
+static BOOL crashedLastRunCalled;
 
 @dynamic logLevel;
 
@@ -43,6 +44,16 @@ + (void)setCurrentHub:(SentryHub *)hub
     }
 }
 
++ (BOOL)crashedLastRunCalled
+{
+    return crashedLastRunCalled;
+}
+
++ (void)setCrashedLastRunCalled:(BOOL)value
+{
+    crashedLastRunCalled = value;
+}
+
 + (void)startWithOptions:(NSDictionary<NSString *, id> *)optionsDict
 {
     NSError *error = nil;

Sources/Sentry/include/SentryClient+Private.h

@@ -17,9 +17,11 @@ NS_ASSUME_NONNULL_BEGIN
                    withSession:(SentrySession *)session
                      withScope:(SentryScope *)scope;
 
-- (SentryId *)captureEvent:(SentryEvent *)event
-               withSession:(SentrySession *)session
-                 withScope:(SentryScope *)scope;
+- (SentryId *)captureCrashEvent:(SentryEvent *)event withScope:(SentryScope *)scope;
+
+- (SentryId *)captureCrashEvent:(SentryEvent *)event
+                    withSession:(SentrySession *)session
+                      withScope:(SentryScope *)scope;
 
 @end
 

Sources/Sentry/include/SentrySDK+Private.h

@@ -8,6 +8,11 @@ NS_ASSUME_NONNULL_BEGIN
 
 + (void)captureCrashEvent:(SentryEvent *)event;
 
+/**
+ * SDK private field to store the state if onCrashedLastRun was called.
+ */
+@property (nonatomic, class) BOOL crashedLastRunCalled;
+
 @end
 
 NS_ASSUME_NONNULL_END

Tests/SentryTests/Integrations/SentrySessionTrackerTests.swift

@@ -448,7 +448,7 @@ class SentrySessionTrackerTests: XCTestCase {
     }
 
     private func assertNoInitSessionSent() {
-        let eventWithSessions = fixture.client.captureEventWithSessionArguments.map({ triple in triple.second })
+        let eventWithSessions = fixture.client.captureCrashEventWithSessionArguments.map({ triple in triple.second })
         let errorWithSessions = fixture.client.captureErrorWithSessionArguments.map({ triple in triple.second })
         let exceptionWithSessions = fixture.client.captureExceptionWithSessionArguments.map({ triple in triple.second })
 
@@ -462,7 +462,7 @@ class SentrySessionTrackerTests: XCTestCase {
     }
 
     private func assertSessionsSent(count: Int) {
-        let eventWithSessions = fixture.client.captureEventWithSessionArguments.count
+        let eventWithSessions = fixture.client.captureCrashEventWithSessionArguments.count
         let errorWithSessions = fixture.client.captureErrorWithSessionArguments.count
         let exceptionWithSessions = fixture.client.captureExceptionWithSessionArguments.count
         let sessions = fixture.client.sessions.count
@@ -496,7 +496,7 @@ class SentrySessionTrackerTests: XCTestCase {
         sut.start()
         SentrySDK.captureCrash(Event())
 
-        if let session = fixture.client.captureEventWithSessionArguments.last?.second {
+        if let session = fixture.client.captureCrashEventWithSessionArguments.last?.second {
             assertSession(session: session, started: sessionStartTime, status: SentrySessionStatus.crashed, duration: 5)
         } else {
             XCTFail("No session sent with event.")

Tests/SentryTests/SentryClient+TestInit.h

@@ -1,6 +1,8 @@
 #import "SentryTransport.h"
 #import <Sentry/Sentry.h>
 
+@class SentryCrashAdapter;
+
 NS_ASSUME_NONNULL_BEGIN
 
 /** Expose the internal test init for testing. */