From 21011959d733a4fc7b4d7fa7d7669dc9c4f46255 Mon Sep 17 00:00:00 2001 From: Kevin Renskers Date: Tue, 10 Jan 2023 11:11:57 +0100 Subject: [PATCH] feat(apple): Rename the OOM integration (#5938) OOM is now called watchdog terminations. See https://github.com/getsentry/sentry-cocoa/pull/2499, which will be part of the 8.0.0 release of sentry-cocoa. Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> Co-authored-by: Philipp Hofmann --- .../configuration/integrations/default.mdx | 4 +- .../common/configuration/out-of-memory.mdx | 23 +++++---- .../configuration/watchdog-terminations.mdx | 48 +++++++++++++++++++ 3 files changed, 63 insertions(+), 12 deletions(-) create mode 100644 src/platforms/apple/common/configuration/watchdog-terminations.mdx diff --git a/src/platforms/apple/common/configuration/integrations/default.mdx b/src/platforms/apple/common/configuration/integrations/default.mdx index 5e22ef9e9513d..efbb00a8c80ce 100644 --- a/src/platforms/apple/common/configuration/integrations/default.mdx +++ b/src/platforms/apple/common/configuration/integrations/default.mdx @@ -19,9 +19,9 @@ This integration will swizzle some methods to create breadcrumbs. For example, f This integration registers for lifecycle notifications and automatically starts and ends sessions required for [Release health](/product/releases/health/#session). -### SentryOutOfMemoryTrackingIntegration +### SentryWatchdogTerminationsTrackingIntegration -This integration tracks out-of-memory crashes based on heuristics. This feature is available for iOS, tvOS, and Mac Catalyst and works only if the application was in the foreground. Check out the configuration information for more details. +This integration tracks watchdog terminations based on heuristics. This feature is available for iOS, tvOS, and Mac Catalyst and works only if the application was in the foreground. Check out the configuration information for more details. ## Disable an Integration diff --git a/src/platforms/apple/common/configuration/out-of-memory.mdx b/src/platforms/apple/common/configuration/out-of-memory.mdx index ddb9e194b681b..1ee29b0fe513e 100644 --- a/src/platforms/apple/common/configuration/out-of-memory.mdx +++ b/src/platforms/apple/common/configuration/out-of-memory.mdx @@ -1,9 +1,13 @@ --- title: Out Of Memory sidebar_order: 10 -description: "Learn how to turn off Out Of Memory" +description: "Learn how to turn off Out Of Memory tracking" --- + +This integration is only available before the 8.0.0 release of the Sentry Apple SDK. We renamed it to watchdog terminations in the 8.0.0 release. + + This integration tracks out-of-memory (OOM) crashes based on heuristics. This feature is available for iOS, tvOS, and Mac Catalyst, works only if the application was in the foreground, and doesn't track OOMs for unit tests. When a typical unhandled error occurs, the Apple SDK writes a report to disk with the current state of your application, with details like the stack trace, tags, breadcrumbs, and so on, before the app terminates. With OOM crashes, the operating system can kill your app without further notice, which means the SDK can't write a report to disk. @@ -11,14 +15,14 @@ As a result, in the Apple SDK, we track OOM crashes during the app start based o When a user launches the app, the SDK checks the following statements and reports an OOM if all of them are true: -* The app didn't crash on the previous run. -* The app was in the foreground/active. -* The user launched the app at least once. When your app produces an OOM during the first launch, the SDK can't detect it. -* There was no debugger attached to the process of the app. If there was, our logic would falsely report OOMs whenever you restarted the app in development. -* The app is not running on a simulator. -* The OS did not update your app. -* The user didn't update the OS of their device. -* The user didn't terminate the app manually, and neither did the OS. +- The app didn't crash on the previous run. +- The app was in the foreground/active. +- The user launched the app at least once. When your app produces an OOM during the first launch, the SDK can't detect it. +- There was no debugger attached to the process of the app. (If there was, our logic would falsely report OOMs whenever you restarted the app in development.) +- The app is not running on a simulator. +- The OS did not update your app. +- The user didn't update the OS of their device. +- The user didn't terminate the app manually, and neither did the OS. If you're interested in the implementation details, you can check out [the code](https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentryOutOfMemoryLogic.m) to find out more. @@ -40,5 +44,4 @@ SentrySDK.start { options in options.dsn = @"___PUBLIC_DSN___"; options.enableOutOfMemoryTracking = NO; }]; - ``` diff --git a/src/platforms/apple/common/configuration/watchdog-terminations.mdx b/src/platforms/apple/common/configuration/watchdog-terminations.mdx new file mode 100644 index 0000000000000..a4a9c7c84210b --- /dev/null +++ b/src/platforms/apple/common/configuration/watchdog-terminations.mdx @@ -0,0 +1,48 @@ +--- +title: Watchdog Terminations +sidebar_order: 10 +description: "Learn how to turn off Watchdog Termination tracking" +--- + + +This integration is available since version 8.0.0 of Sentry Apple SDK. It was named Out of Memory before the 8.0.0 release. + + +This integration tracks [watchdog terminations](https://developer.apple.com/documentation/xcode/addressing-watchdog-terminations) based on heuristics. This feature is available for iOS, tvOS, and Mac Catalyst, works only if the application was in the foreground, and doesn't track watchdog terminations for unit tests. + +When a typical unhandled error occurs, the Apple SDK writes a report to disk with the current state of your application, with details like the stack trace, tags, breadcrumbs, and so on, before the app terminates. When the watchdog terminates your app this happens without further notice, which means the SDK can't write a report to disk. A common reason the watchdog can terminate your app is an Out Of Memory problem. If the app is terminated because it hangs, we don't create a watchdog termination event, but instead an `AppHangs` event is created. + +As a result, in the Apple SDK, we track watchdog terminations during the app start based on heuristics, but getting the state of the app when a watchdog termination occurs is challenging. To provide the same state as we do for a typical crash, we would periodically need to store the app state to disk. This would cause a lot of I/O, which in turn could negatively affect the application's performance. To avoid this, watchdog termination events have less context than typical unhandled errors. Breadcrumbs are stored to disk and are added to watchdog termination events to help you figure out where in the app the event happened. This is done by appending the breadcrumbs to an open file, which should have a marginal impact on your app's performance. + +When a user launches the app, the SDK checks the following statements and reports a watchdog termination if all of them are true: + +- The app didn't crash on the previous run. +- The app was in the foreground/active. +- The user launched the app at least once. When your app was killed by the watchdog during the first launch, the SDK can't detect it. +- There was no debugger attached to the process of the app. (If there was, our logic would falsely report watchdog terminations whenever you restarted the app in development.) +- The app was not running on a simulator. +- The OS didn't update your app. +- The user didn't update the OS of their device. +- The user didn't terminate the app manually, and neither did the OS. + +If you're interested in the implementation details, you can check out [the code](https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentryWatchdogTerminationsLogic.m) to find out more. + +If you'd like to opt out of this feature, you can do so using options: + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.enableWatchdogTerminationTracking = false +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.enableWatchdogTerminationTracking = NO; +}]; +```