From 7891edb8624d013fad8a1d1bbda8278978613d3d Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Mon, 9 Feb 2026 14:57:42 +0100 Subject: [PATCH 1/9] feat(android): document tombstone support --- .../android/configuration/tombstones.mdx | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/platforms/android/configuration/tombstones.mdx diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx new file mode 100644 index 0000000000000..a2407beb82acc --- /dev/null +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -0,0 +1,70 @@ +--- +title: Android Native Crash reporting (Tombstones) +sidebar_order: 2 +description: Learn how to configure Tombstone support. +--- + +The Tombstone Integration generates events for native crashes based on data, called "tombstones", that Android attaches to [`ApplicationExitInfo.REASON_CRASH_NATIVE`](https://developer.android.com/reference/android/app/ApplicationExitInfo#REASON_CRASH_NATIVE) starting with [Android 12+](https://developer.android.com/reference/android/app/ApplicationExitInfo#getTraceInputStream()). + +The crash context data in this case is collected by the operating system as part of the shutdown of your crashed application, and partially runs out-of-process, which allows for a richer collection of crash context data vs. using the [NDK integration](/platforms/android/configuration/using-ndk/). + +In particular, you will get: + +* stack-traces for each of the threads in your process (which on Android is often key to understanding crashes) +* improved stack traces through Android Runtime stack frames +* client-side symbolication of all system libraries (while still allowing for server-side symbolication of your binaries to keep app size small) + +The Tombstone Integration is disabled by default. You can enable the tombstone integration using + +```xml {filename:AndroidManifest.xml} + + + +``` + +#### Merging Tombstone and NDK crash events + +It is a sensible practice to run the [NDK integration](/platforms/android/configuration/using-ndk/) (`io.sentry.ndk.enable`) and the Tombstone integration at the same time: + +* if you have users on devices < Android 12 (in which case the NDK integration will solely be reporting native crashes) +* if you use functions of the Native SDK from your native code and want your collected context to be reflected in the crash reports + +The reports from both integrations will be merged on the client into a single report, which will later be enriched. This means that whenever the Android version allows it, you will get improved crash reporting from tombstones; otherwise, the SDK falls back to the best-effort implementation from the NDK integration. In both cases, the Native SDK context is preserved in the final report. + +#### Tombstone mechanisms + +We introduced two new mechanisms to help identify the integration from which reports originate: + +* A report originating only from a tombstone will be called `Tombstone` +* A report being a merged result from a tombstone and a Native SDK event will be called `TombstoneMerged` +* A report originating solely from the NDK integration (Native SDK) will continue to be called `signalhandler` + +#### Symbolication + +As mentioned above, Android infrastructure will try to symbolicate as much as possible on the client side. This is particularly important for system and framework symbols, since they can differ considerably across devices. If symbols cannot be resolved on the client - for instance, for your supplied binaries - the [backend symbolication](/platforms/android/configuration/using-ndk/#symbolicate-stack-traces) process follows the same rules as with the NDK integration. + +#### Debug Images + +In contrast to NDK integration, Tombstones retrieve module memory mappings at the time of the crash and are thus always up-to-date. If you use the NDK integration as a fallback for older Android versions, you still need to clear the module cache when dynamically loading libraries after app initialization. + +#### Historical Tombstones + +By default, the SDK only reports and enriches the latest Tombstones. However, there's also a `setReportHistoricalTombstones` option available in `SentryOptions`, which enables the SDK to report all Tombstones from the [getHistoricalExitReasons]() list: + +```kotlin +SentryAndroid.init(context) { options -> + options.isReportHistoricalTombstones = true +} +``` + +```java +SentryAndroid.init(context) { options -> + options.setReportHistoricalTombstones(true) +} +``` + +This option is useful after updating the SDK to the version that introduced the Tombstone integration, to report all Tombstones that occurred before the SDK update. + +It can also make sense if you get recurring reports of native crashes early during app start, or if your app regularly runs and restarts during longer offline periods. + +Other than that, the SDK will always pick up the latest Tombstone from the historical exit reasons list on the next app restart, and there won’t be any historical Tombstones to report. Also keep in mind that historical Tombstones will receive only minimal updates, as the available data is likely out of sync. From 58ca09479b5772d17dce845d444227db651aa4d1 Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:51:17 +0100 Subject: [PATCH 2/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index a2407beb82acc..c3c381a7ad419 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -4,7 +4,7 @@ sidebar_order: 2 description: Learn how to configure Tombstone support. --- -The Tombstone Integration generates events for native crashes based on data, called "tombstones", that Android attaches to [`ApplicationExitInfo.REASON_CRASH_NATIVE`](https://developer.android.com/reference/android/app/ApplicationExitInfo#REASON_CRASH_NATIVE) starting with [Android 12+](https://developer.android.com/reference/android/app/ApplicationExitInfo#getTraceInputStream()). +The Tombstone Integration generates events for native crashes based on data ("tombstones") that Android attaches to [`ApplicationExitInfo.REASON_CRASH_NATIVE`](https://developer.android.com/reference/android/app/ApplicationExitInfo#REASON_CRASH_NATIVE) starting with [Android 12+](https://developer.android.com/reference/android/app/ApplicationExitInfo#getTraceInputStream()). The crash context data in this case is collected by the operating system as part of the shutdown of your crashed application, and partially runs out-of-process, which allows for a richer collection of crash context data vs. using the [NDK integration](/platforms/android/configuration/using-ndk/). From e9f6e4c583d9d33595a54d3b84a8d45d0f6384cd Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:51:54 +0100 Subject: [PATCH 3/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index c3c381a7ad419..8eb1476f4994c 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -6,7 +6,7 @@ description: Learn how to configure Tombstone support. The Tombstone Integration generates events for native crashes based on data ("tombstones") that Android attaches to [`ApplicationExitInfo.REASON_CRASH_NATIVE`](https://developer.android.com/reference/android/app/ApplicationExitInfo#REASON_CRASH_NATIVE) starting with [Android 12+](https://developer.android.com/reference/android/app/ApplicationExitInfo#getTraceInputStream()). -The crash context data in this case is collected by the operating system as part of the shutdown of your crashed application, and partially runs out-of-process, which allows for a richer collection of crash context data vs. using the [NDK integration](/platforms/android/configuration/using-ndk/). +This crash context is collected by the operating system during the app’s shutdown after a crash. Because part of this process runs out of process, it can capture richer crash details than the [NDK integration](/platforms/android/configuration/using-ndk/). In particular, you will get: From e396c6d5568ad1984d1f22594513d36a57247064 Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:52:08 +0100 Subject: [PATCH 4/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index 8eb1476f4994c..b5ce727d88016 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -14,7 +14,7 @@ In particular, you will get: * improved stack traces through Android Runtime stack frames * client-side symbolication of all system libraries (while still allowing for server-side symbolication of your binaries to keep app size small) -The Tombstone Integration is disabled by default. You can enable the tombstone integration using +The Tombstone Integration is disabled by default. You can enable the tombstone integration using: ```xml {filename:AndroidManifest.xml} From 521eae3d8763bdf258870a32767da7e83b2b3f8a Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:52:18 +0100 Subject: [PATCH 5/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index b5ce727d88016..6d4aba4283d2a 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -22,7 +22,7 @@ The Tombstone Integration is disabled by default. You can enable the tombstone i ``` -#### Merging Tombstone and NDK crash events +#### Merging Tombstone and NDK Crash Events It is a sensible practice to run the [NDK integration](/platforms/android/configuration/using-ndk/) (`io.sentry.ndk.enable`) and the Tombstone integration at the same time: From 399186afae56ea3f22c0e41b80b09029d7380963 Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:52:34 +0100 Subject: [PATCH 6/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index 6d4aba4283d2a..96ba9abfba99d 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -24,7 +24,7 @@ The Tombstone Integration is disabled by default. You can enable the tombstone i #### Merging Tombstone and NDK Crash Events -It is a sensible practice to run the [NDK integration](/platforms/android/configuration/using-ndk/) (`io.sentry.ndk.enable`) and the Tombstone integration at the same time: +It generally makes sense run the [NDK integration](/platforms/android/configuration/using-ndk/) (`io.sentry.ndk.enable`) and the Tombstone integration at the same time: * if you have users on devices < Android 12 (in which case the NDK integration will solely be reporting native crashes) * if you use functions of the Native SDK from your native code and want your collected context to be reflected in the crash reports From a6f25b7a89c958c1bd248c53132629fc8be92ff6 Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:52:54 +0100 Subject: [PATCH 7/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index 96ba9abfba99d..c5bdd242883c3 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -63,7 +63,7 @@ SentryAndroid.init(context) { options -> } ``` -This option is useful after updating the SDK to the version that introduced the Tombstone integration, to report all Tombstones that occurred before the SDK update. +This option is useful after upgrading to an SDK version that introduces the Tombstone integration, as it allows you to report any tombstones that occurred before the update. It can also make sense if you get recurring reports of native crashes early during app start, or if your app regularly runs and restarts during longer offline periods. From ee24b7b427e3cecde30da69715c36d2ae195016f Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:53:03 +0100 Subject: [PATCH 8/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index c5bdd242883c3..0d9604bd42776 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -1,5 +1,5 @@ --- -title: Android Native Crash reporting (Tombstones) +title: Android Native Crash Reporting (Tombstones) sidebar_order: 2 description: Learn how to configure Tombstone support. --- From 4903ac3b2814948c331d05ce2a85126cc13ba83a Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Tue, 10 Feb 2026 21:53:12 +0100 Subject: [PATCH 9/9] Update docs/platforms/android/configuration/tombstones.mdx Co-authored-by: Alex Krawiec --- docs/platforms/android/configuration/tombstones.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/tombstones.mdx b/docs/platforms/android/configuration/tombstones.mdx index 0d9604bd42776..d98acfb25264a 100644 --- a/docs/platforms/android/configuration/tombstones.mdx +++ b/docs/platforms/android/configuration/tombstones.mdx @@ -31,7 +31,7 @@ It generally makes sense run the [NDK integration](/platforms/android/configurat The reports from both integrations will be merged on the client into a single report, which will later be enriched. This means that whenever the Android version allows it, you will get improved crash reporting from tombstones; otherwise, the SDK falls back to the best-effort implementation from the NDK integration. In both cases, the Native SDK context is preserved in the final report. -#### Tombstone mechanisms +#### Tombstone Mechanisms We introduced two new mechanisms to help identify the integration from which reports originate: