diff --git a/docs/platforms/android/configuration/img/memory-limiter-event-in-sentry.png b/docs/platforms/android/configuration/img/memory-limiter-event-in-sentry.png new file mode 100644 index 0000000000000..1936205b72d50 Binary files /dev/null and b/docs/platforms/android/configuration/img/memory-limiter-event-in-sentry.png differ diff --git a/docs/platforms/android/configuration/img/memory-limiter-grouping.png b/docs/platforms/android/configuration/img/memory-limiter-grouping.png new file mode 100644 index 0000000000000..dea98fc1d6529 Binary files /dev/null and b/docs/platforms/android/configuration/img/memory-limiter-grouping.png differ diff --git a/docs/platforms/android/configuration/memory-limiter.mdx b/docs/platforms/android/configuration/memory-limiter.mdx new file mode 100644 index 0000000000000..9aa04448aba1d --- /dev/null +++ b/docs/platforms/android/configuration/memory-limiter.mdx @@ -0,0 +1,112 @@ +--- +title: Memory Limiter +sidebar_order: 5 +description: Learn how to detect process deaths caused by Android's Memory Limiter with the Sentry Android SDK. +--- + + + +The Memory Limiter integration is experimental. It's available in Sentry Android SDK version ≥ `8.57.0`, and Android API level ≥ 37. + + + +Android 17 introduced the Memory Limiter, a system service available on supported devices that's responsible for managing per-app memory budgets and slowing down or terminating apps that exceed them. Terminations don't produce a Java exception or a stack trace, which makes them easy to miss if you're only looking for traditional crashes. + +Sentry's Memory Limiter integration generates fatal Sentry events for Memory Limiter terminations by scanning [ApplicationExitInfo](https://developer.android.com/reference/android/app/ApplicationExitInfo) records written by the Android OS. + +To learn more about Memory Limiter, see [Google's documentation](https://source.android.com/docs/core/perf/memory-limiter) and the [Android Developers Blog](https://android-developers.googleblog.com/2026/08/app-broader-memory-limits.html). + +## Prerequisites + +- You're using Sentry Android SDK version `8.57.0` or later. +- The device is running Android 17 (API level 37) or later. +- The SDK has a cache directory available. +- You enable the integration explicitly. (It's disabled by default.) + +## Enable the Memory Limiter Integration + +You can enable the integration in your `AndroidManifest.xml`: + +```xml {filename:AndroidManifest.xml} + + + +``` + +Or when you initialize the SDK: + +```kotlin {tabTitle:Kotlin} +SentryAndroid.init(this) { options -> + options.isMemoryLimiterEnabled = true +} +``` + +```java {tabTitle:Java} +SentryAndroid.init(this, options -> { + options.setMemoryLimiterEnabled(true); +}); +``` + +## How It Works + +When the Memory Limiter terminates a process, info about that process is recorded by the Android OS in the form of an `ApplicationExitInfo` entry, tracked by the `ActivityManager` system service. + +On the next app start, the SDK searches all exit info records for Memory Limiter deaths. If it finds a match, the SDK creates a synthetic fatal event with the `MemoryLimitExceeded` exception type. For the latest matching exit, the SDK also backfills persisted context from the previous process when that data is available. + +## Historical Memory Limiter Exits + +By default, the SDK reports only the latest matching Memory Limiter exit. If you also want older retained exits from the same Android history, enable historical reporting: + +```xml {filename:AndroidManifest.xml} + + + + +``` + +```kotlin {tabTitle:Kotlin} +SentryAndroid.init(this) { options -> + options.isMemoryLimiterEnabled = true + options.isReportHistoricalMemoryLimiterExits = true +} +``` + +```java {tabTitle:Java} +SentryAndroid.init(this, options -> { + options.setMemoryLimiterEnabled(true); + options.setReportHistoricalMemoryLimiterExits(true); +}); +``` + +Historical exits are lighter-weight reports. Unlike the latest retained exit, they aren't enriched with persisted Sentry context from the previous process. + +## What You'll See in Sentry + +Memory Limiter reports appear as fatal events with: + +- Exception type `MemoryLimitExceeded` +- Mechanism type `AppExitInfo` for the latest exit, or `HistoricalAppExitInfo` for older retained exits +- The original Android exit description stored on the event's `mechanism` +- Memory Limiter-specific mechanism data such as `memory_limit_class` and `process_importance` + +![Memory Limiter Event in Sentry](./img/memory-limiter-event-in-sentry.png) + +The `memory_limit_class` value is a best-effort classification derived from `process_importance` and the table shown [here](https://source.android.com/docs/core/perf/memory-limiter#process-monitoring). It consists of three buckets: + +- `visible` +- `not_visible` +- `cached` + +These fields can help you approximate the memory capacity allocated to your process before it was killed and whether it was visible to users. + +Values for `process_importance` are taken from [`ApplicationExitInfo.importance`](). Memory Limiter events are grouped by `process_importance` in Sentry's issues feed: + +![Memory Limiter Grouping in Sentry](./img/memory-limiter-grouping.png) + +## Release Health and Sessions + +If you're using Release Health, the latest recovered Memory Limiter exit also marks the previous session as `abnormal` on the next app launch. + +That keeps release health closer to what users experienced instead of treating the terminated session as a healthy exit. + +For more about session states, see Session Status. diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 0b0d5d9b3ad29..6d4b096dd1b18 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -534,6 +534,30 @@ When enabled, the SDK assigns a static fingerprint to ANR events whose stack tra +## Memory Limiter Options + + + +Enables experimental detection of Android Memory Limiter process deaths through retained [ApplicationExitInfo](https://developer.android.com/reference/android/app/ApplicationExitInfo) records. + +When enabled, the SDK checks for Memory Limiter terminations on the next app start and reports the latest match as a fatal event. If release health is enabled, the previous session is also marked as abnormal. + +This feature is available only on supported devices running on Android 17 (API level 37) and higher. See Memory Limiter for setup details and limitations. + +AndroidManifest.xml key: `io.sentry.memory-limiter.enable`. + + + + + +Reports older retained Memory Limiter process deaths in addition to the latest one. + +Historical Memory Limiter terminations are not enriched with persisted context from the previous process. This option only takes effect when is enabled. + +AndroidManifest.xml key: `io.sentry.memory-limiter.report-historical`. + + + ## Transaction-Based Profiling Options This mode will eventually be deprecated, and it's recommended to upgrade to UI Profiling. The same behaviour, without the 30 seconds limitation, can be achieved with the `trace` profile lifecycle option. In order to upgrade to UI Profiling, you also need to remove the transaction-based options from your configuration. diff --git a/docs/platforms/android/features/index.mdx b/docs/platforms/android/features/index.mdx index 252de23cbd1aa..45c58fefb655d 100644 --- a/docs/platforms/android/features/index.mdx +++ b/docs/platforms/android/features/index.mdx @@ -48,6 +48,7 @@ Let us know if you have feedback by filing a Apollo request spans. - Distributed tracing through OkHttp and Apollo integrations. - Application Not Responding (ANR), reported if the application is blocked for more than five seconds. +- Memory Limiter, which reports process kills caused by Android's per-app memory limits on supported devices. - HTTP Client Errors. - Screenshot attachments for errors. - View Hierarchy attachments for errors. diff --git a/docs/platforms/android/index.mdx b/docs/platforms/android/index.mdx index 4187676aa4ddf..73e2a89d819a5 100644 --- a/docs/platforms/android/index.mdx +++ b/docs/platforms/android/index.mdx @@ -188,3 +188,4 @@ class MyActivity : AppCompatActivity() { - Learn how to enhance stack traces of your Sentry errors - Enrich events with additional context to make debugging simpler - Diagnose ANRs with profiling and automatic fingerprinting +- Monitor Memory Limiter process deaths on supported Android 17+ devices