From 973ef170561ebd3d5d9c45b6f50231eb7ce7e9bf Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 29 Oct 2024 08:23:52 +0100 Subject: [PATCH 1/3] feat(apple): Add UncaughtNSExceptionReporting Add docs for , which will be available on Cocoa SDK 8.40.0 and above. --- platform-includes/capture-error/apple.mdx | 43 +++++++++++++++++------ 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/platform-includes/capture-error/apple.mdx b/platform-includes/capture-error/apple.mdx index fa5eba77b6732..9f7bd4aa9fb3b 100644 --- a/platform-includes/capture-error/apple.mdx +++ b/platform-includes/capture-error/apple.mdx @@ -103,28 +103,49 @@ The SDK can't install the uncaught exception handler if a debugger is attached. -By default, macOS applications do not crash whenever an uncaught exception occurs. To enable this with Sentry: +By default, macOS applications do not crash whenever an uncaught exception occurs. As the Cocoa Frameworks are generally not [exception-safe on macOS](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Exceptions/Articles/ExceptionsAndCocoaFrameworks.html), we recommend this approach because the application could otherwise end up in a corrupted state. + +To capture uncaught NSExceptions, you can use the `SentryCrashExceptionApplication` or enable the option `enableUncaughtNSExceptionReporting,` available as of version [8.40.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8400). Once you have configured your application to crash whenever an uncaught exception occurs, the Apple SDK will capture those automatically. You don't need to manually call `captureException`. + +### SentryCrashExceptionApplication + + + +Don't use this option together with the `enableUncaughtNSExceptionReporting` option. Enabling both features can lead to duplicated reports. + + + +To enable this with Sentry: 1. Open the application's `Info.plist` file 2. Search for `Principal class` (the entry is expected to be `NSApplication`) 3. Replace `NSApplication` with `SentryCrashExceptionApplication` -Alternatively, you can set the `NSApplicationCrashOnExceptions` flag: +### Uncaught NSException Reporting Option -```swift {tabTitle:Swift} {4-4} -import Sentry + -func applicationDidFinishLaunching(_ aNotification: Notification) { - UserDefaults.standard.register(defaults: ["NSApplicationCrashOnExceptions": true]) +Don't use this option together with the `SentryCrashExceptionApplication`. Enabling both features can lead to duplicated reports. - SentrySDK.start { options in - // ... - } + - return true +As of version [8.40.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8400), you can enable uncaught NSException reporting by setting the `enableUncaughtNSExceptionReporting` option to `true`. This is especially useful for applications using the SwiftUI lifecycle in combination with the [`NSApplicationDelegateAdaptor`](https://developer.apple.com/documentation/swiftui/nsapplicationdelegateadaptor), for which you can't easily use the `SentryCrashExceptionApplication` class. + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.enableUncaughtNSExceptionReporting = true } ``` +```objc {tabTitle:Objective-C} +@import Sentry; -Once you have configured your application to crash whenever an uncaught exception occurs, the Apple SDK will capture those automatically. You don't need to manually call `captureException`. +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.enableUncaughtNSExceptionReporting = YES; +}]; +``` From 878fd7332f4eb743dfeff696d0e572dd94c14e57 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 29 Oct 2024 14:40:57 +0100 Subject: [PATCH 2/3] Update platform-includes/capture-error/apple.mdx Co-authored-by: Karl Heinz Struggl --- platform-includes/capture-error/apple.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/capture-error/apple.mdx b/platform-includes/capture-error/apple.mdx index 9f7bd4aa9fb3b..1eb073f51a030 100644 --- a/platform-includes/capture-error/apple.mdx +++ b/platform-includes/capture-error/apple.mdx @@ -105,7 +105,7 @@ The SDK can't install the uncaught exception handler if a debugger is attached. By default, macOS applications do not crash whenever an uncaught exception occurs. As the Cocoa Frameworks are generally not [exception-safe on macOS](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Exceptions/Articles/ExceptionsAndCocoaFrameworks.html), we recommend this approach because the application could otherwise end up in a corrupted state. -To capture uncaught NSExceptions, you can use the `SentryCrashExceptionApplication` or enable the option `enableUncaughtNSExceptionReporting,` available as of version [8.40.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8400). Once you have configured your application to crash whenever an uncaught exception occurs, the Apple SDK will capture those automatically. You don't need to manually call `captureException`. +To capture uncaught NSExceptions, you can use the `SentryCrashExceptionApplication`, or enable the option `enableUncaughtNSExceptionReporting`, available as of version [8.40.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8400). Once you have configured your application to crash whenever an uncaught exception occurs, the Apple SDK will capture those automatically. You don't need to manually call `captureException`. ### SentryCrashExceptionApplication From 91cf6c754ae27fedfa087a4f281e275b474ae071 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 29 Oct 2024 14:50:26 +0100 Subject: [PATCH 3/3] PR feedback --- platform-includes/capture-error/apple.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform-includes/capture-error/apple.mdx b/platform-includes/capture-error/apple.mdx index 1eb073f51a030..0689a564473f8 100644 --- a/platform-includes/capture-error/apple.mdx +++ b/platform-includes/capture-error/apple.mdx @@ -103,9 +103,9 @@ The SDK can't install the uncaught exception handler if a debugger is attached. -By default, macOS applications do not crash whenever an uncaught exception occurs. As the Cocoa Frameworks are generally not [exception-safe on macOS](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Exceptions/Articles/ExceptionsAndCocoaFrameworks.html), we recommend this approach because the application could otherwise end up in a corrupted state. +By default, macOS applications don't crash whenever an uncaught exception occurs. As the Cocoa Frameworks are generally not [exception-safe on macOS](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Exceptions/Articles/ExceptionsAndCocoaFrameworks.html), the application could end up in a corrupted state when an uncaught exception occurs. Therefore, we recommend changing your application configuration so it crashes on uncaught NSExceptions. To achieve this, you can use the `SentryCrashExceptionApplication`, or enable the option `enableUncaughtNSExceptionReporting`, available as of version [8.40.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8400). Both options set the `NSApplicationCrashOnExceptions` on the `NSUserDefaults` so your application crashes on uncaught NSExceptions and send the crash report to Sentry. -To capture uncaught NSExceptions, you can use the `SentryCrashExceptionApplication`, or enable the option `enableUncaughtNSExceptionReporting`, available as of version [8.40.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#8400). Once you have configured your application to crash whenever an uncaught exception occurs, the Apple SDK will capture those automatically. You don't need to manually call `captureException`. +Once you have configured your application to crash whenever an uncaught exception occurs, the Apple SDK will capture those automatically. You don't need to manually call `captureException`. ### SentryCrashExceptionApplication