getsentry · bitsandfoxes · Jul 31, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 31, 2026
diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx
@@ -377,6 +377,28 @@ A boolean value that determines whether the app start process will be profiled.
 
 </SdkOption>
 
+## Native App Hang Options
+
+<SdkOption name="enableNdkAppHangTracking" type="bool" defaultValue="false" availableSince="8.48.0">
+
+Enables experimental app hang detection through the NDK integration. The NDK watchdog monitors the thread that calls `sentry_app_hang_heartbeat()` and captures an app hang event when that thread stops sending heartbeats for longer than `ndkAppHangTimeoutIntervalMillis`.
+
+This requires the NDK integration and regular native heartbeats. It is independent of Android ANR detection, which monitors the Android UI thread. See <PlatformLink to="/configuration/using-ndk/#app-hang-detection">App Hang Detection</PlatformLink> for setup instructions.
+
+AndroidManifest.xml key: `io.sentry.ndk.app-hang.enable`.
+
+</SdkOption>
+
+<SdkOption name="ndkAppHangTimeoutIntervalMillis" type="long" defaultValue="5000" defaultNote="milliseconds" availableSince="8.48.0">
+
+Sets how long the monitored native thread can miss heartbeats before the NDK integration captures an app hang event. Values below `1000` ms are clamped to `1000` ms.
+
+Only takes effect when <PlatformIdentifier name="enableNdkAppHangTracking" /> is enabled.
+
+AndroidManifest.xml key: `io.sentry.ndk.app-hang.timeout-interval-millis`.
+
+</SdkOption>
+
 ## ANR Options
 
 <SdkOption name="anrProfilingSampleRate" type="float" defaultValue="null" availableSince="8.35.0">

diff --git a/docs/platforms/android/configuration/using-ndk.mdx b/docs/platforms/android/configuration/using-ndk.mdx
@@ -83,6 +83,57 @@ Java_io_sentry_demo_NativeDemo_crash(JNIEnv *env, jclass cls) {
 }
 ```
 
+## App Hang Detection
+
+The NDK integration can detect when a native or game thread stops responding, even when the app does not crash. Unlike Android ANR detection, which monitors the Android UI thread, app hang detection watches the thread that sends native heartbeats. This is useful for engines or native code with their own main loop.
+
+<Alert title="Experimental">
+
+NDK app hang detection is experimental. It requires Sentry Android SDK version `8.48.0` or later and the NDK integration.
+
+</Alert>
+
+Enable detection when you initialize the SDK, then call `sentry_app_hang_heartbeat()` regularly from the thread you want to monitor:
+
+```kotlin {tabTitle:Kotlin}
+SentryAndroid.init(this) { options ->
+    options.isEnableNdkAppHangTracking = true
+    options.ndkAppHangTimeoutIntervalMillis = 2_000
+}
+```
+
+```java {tabTitle:Java}
+SentryAndroid.init(this, options -> {
+    options.setEnableNdkAppHangTracking(true);
+    options.setNdkAppHangTimeoutIntervalMillis(2_000);
+});
+```
+
+```c
+// Call from the thread whose responsiveness represents your app.
+void game_loop(void) {
+    while (is_running()) {
+        sentry_app_hang_heartbeat();
+        run_one_frame();
+    }
+}
+```
+
+The first heartbeat chooses the monitored thread. If it misses heartbeats for the configured timeout, the NDK integration captures an app hang event with that thread's stack trace. The timeout defaults to `5000` ms and has a minimum of `1000` ms.
+
+Android ANR detection remains independent. If the same freeze blocks both the Android UI thread and your monitored native thread, Sentry can report both an ANR and an app hang.
+
+You can also configure these options in `AndroidManifest.xml`, which is useful when the SDK initializes automatically:
+
+```xml {filename:AndroidManifest.xml}
+<application>
+    <meta-data android:name="io.sentry.ndk.app-hang.enable" android:value="true" />
+    <meta-data android:name="io.sentry.ndk.app-hang.timeout-interval-millis" android:value="2000" />
+</application>
+```
+
+For details about the native watchdog and heartbeat behavior, see the [Native SDK app hang documentation](/platforms/native/app-hangs/).
+
 ## Disable NDK Integration
 
 You can disable the NDK integration by adding the following to your `AndroidManifest.xml`:

diff --git a/docs/platforms/native/usage/app-hangs.mdx → docs/platforms/native/app-hangs.mdx b/docs/platforms/native/usage/app-hangs.mdx → docs/platforms/native/app-hangs.mdx
@@ -13,7 +13,7 @@ In-process app-hang detection is experimental and may change in a future release
 
 An unresponsive application is one of the most frustrating experiences for your users. A long-running computation, a blocking I/O call, or an infinite loop on a critical thread can freeze your app without ever crashing, so it never surfaces as an error. App-hang detection catches these cases and reports them to Sentry as app-hang events.
 
-The Native SDK detects hangs entirely in-process: a background watchdog thread monitors a single thread of your choosing and captures an event when that thread stops making progress. Because the SDK can't know which of your threads represents responsiveness, you tell it by sending heartbeats from the thread you want watched (typically your UI or main loop).
+On macOS, Windows, Linux, and Android, the Native SDK detects hangs entirely in-process: a background watchdog thread monitors a single thread of your choosing and captures an event when that thread stops making progress. Because the SDK can't know which of your threads represents responsiveness, you tell it by sending heartbeats from the thread you want watched (typically your UI or main loop).
 
 ## Enabling App-Hang Detection
 

diff --git a/docs/platforms/native/common/configuration/options.mdx b/docs/platforms/native/common/configuration/options.mdx
@@ -152,7 +152,7 @@ Whether calls to `sentry_log_X()` expect an attributes object as the second argu
 
 ## App Hang Options
 
-These options control in-process app-hang detection. See the [App Hangs page](/platforms/native/usage/app-hangs/) for a full explanation and usage example.
+These options control in-process app-hang detection. See the [App Hangs page](/platforms/native/app-hangs/) for a full explanation and usage example.
 
 <SdkOption name="enable_app_hang_tracking" type="bool" defaultValue="false" availableSince="0.15.2">
 

diff --git a/docs/platforms/unity/app-hangs.mdx b/docs/platforms/unity/app-hangs.mdx
@@ -0,0 +1,51 @@
+---
+title: App Hangs and ANRs
+sidebar_order: 110
+description: "Detect app hangs and ANRs in Unity games."
+sidebar_section: features
+---
+
+An app hang occurs when the Unity main thread stops making progress. On Android, the operating system can also report an Application Not Responding (ANR) event when the Android UI thread is blocked. These detectors can watch different threads, so one freeze can create separate events.
+
+## App Hangs
+
+### Native App Hangs
+
+On Android, Windows, Linux, and macOS with the native backend, the SDK provides app hang tracking through the `EnableAppHangTracking` option. It uses sentry-native and is disabled by default. On Android, it also requires `NdkIntegrationEnabled`. The timeout is `AppHangTimeout`, which defaults to 5 seconds.
+
+These options are available on the Editor Configuration Window in `Advanced` -> `Experimental` or programmatically
+
+```csharp
+options.EnableAppHangTracking = true;
+options.AppHangTimeout = TimeSpan.FromSeconds(5);
+```
+
+On Android with the NDK integration and on sentry-native desktop platforms, the SDK adds a background watchdog and automatically emits heartbeats from the Unity main thread. Cocoa tracks app hangs directly. When app hang tracking is configured, the SDK removes the managed watchdog to avoid duplicate events.
+
+### App Hangs on iOS and macOS
+
+On iOS and macOS, `EnableAppHangTracking` enables app hang tracking through sentry-cocoa. It is disabled by default. The timeout is `AppHangTimeout`, which defaults to 5 seconds. When targeting macOS you can select the native SDK used to `Native` to utilize sentry-native as well.
+
+## ANRs
+
+### Android JVM ANRs
+
+`AndroidNativeAnrEnabled` controls JVM ANR detection and defaults to `true`. Below Android 11, it uses an in-process watchdog. On Android 11 and later, it reads the operating system's ANR exit information on the next app start. The app hang detection runs alongside JVM ANR detection, so a freeze that blocks both threads can create an ANR and an `AppHang` event.
+
+### Unity Watchdog
+
+The managed Unity watchdog is deprecated and disabled by default. Configure its timeout with `AnrTimeout`, which defaults to 5 seconds. Disable it in code with `DisableAnrIntegration()` or through the editor's `AnrDetectionEnabled` setting.
+
+The watchdog uses a coroutine and a background thread. It detects a stalled Unity main thread, but cannot capture that thread's stack trace. Its events use the `MainThreadWatchdog` mechanism.
+
+## Queries and Migration
+
+To find app hang events, search for:
+
+```
+error.mechanism.type:AppHang
+```
+
+Android JVM ANRs remain independent. Filter them with `ANR`, `AppExitInfo`, or `HistoricalAppExitInfo`.
+
+For Android NDK implementation details, see [Android NDK app hang detection](/platforms/android/configuration/using-ndk/#app-hang-detection). For Apple behavior, see [Apple app hangs](/platforms/apple/guides/ios/configuration/app-hangs/).
diff --git a/docs/platforms/unity/configuration/app-not-responding/index.mdx b/docs/platforms/unity/configuration/app-not-responding/index.mdx
diff --git a/docs/platforms/unity/configuration/options/index.mdx b/docs/platforms/unity/configuration/options/index.mdx
@@ -262,3 +262,51 @@ Controls whether the SDK will automatically trace the app's startup.
 Controls whether the SDK will automatically trace when loading scenes.
 
 </SdkOption>
+
+## App Hang and ANR Options
+
+Use these options to configure app hang and ANR detection. For supported platforms, detector behavior, and avoiding duplicate events, see <PlatformLink to="/app-hangs/">App Hangs and ANRs</PlatformLink>.
+
+<SdkOption name="EnableAppHangTracking" type="bool" defaultValue="false">
+
+Enables app hang detection. On iOS and macOS with the default backend, the SDK uses sentry-cocoa. On Android, Windows, Linux, and macOS with the native backend, it uses sentry-native. On Android, this also requires <PlatformIdentifier name="NdkIntegrationEnabled" />.
+
+When the tracked thread is unresponsive for longer than <PlatformIdentifier name="AppHangTimeout" />, the SDK captures an `AppHang` event with a native stack trace.
+
+</SdkOption>
+
+<SdkOption name="AppHangTimeout" type="TimeSpan" defaultValue="TimeSpan.FromSeconds(5)">
+
+Sets how long the main thread must be unresponsive before the SDK captures an app hang. This timeout is also used by native app hang tracking.
+
+</SdkOption>
+
+<SdkOption name="AnrDetectionEnabled" type="bool" defaultValue="false">
+
+Controls the managed Unity watchdog in the Sentry configuration window. To disable this detector programmatically, call `options.DisableAnrIntegration()`.
+
+</SdkOption>
+
+<SdkOption name="AnrTimeout" type="TimeSpan" defaultValue="TimeSpan.FromSeconds(5)">
+
+Sets how long the Unity main thread must be unresponsive before the managed watchdog reports an ANR event.
+
+</SdkOption>
+
+<SdkOption name="AndroidNativeAnrEnabled" type="bool" defaultValue="true">
+
+Enables Android JVM ANR detection. On Android 11 and later, the SDK reports ANRs recorded by the operating system when the app next starts. On earlier Android versions, it uses an in-process watchdog.
+
+</SdkOption>
+
+<SdkOption name="AndroidReportHistoricalAnrs" type="bool" defaultValue="false">
+
+Reports historical Android ANRs recorded by the operating system. This option requires <PlatformIdentifier name="AndroidNativeAnrEnabled" /> and applies only when Android native initialization runs at runtime.
+
+</SdkOption>
+
+<SdkOption name="AndroidAttachAnrThreadDump" type="bool" defaultValue="false">
+
+Attaches the Android operating system's thread dump to ANR events. This option requires <PlatformIdentifier name="AndroidNativeAnrEnabled" />.
+
+</SdkOption>
diff --git a/docs/platforms/unreal/app-hangs.mdx b/docs/platforms/unreal/app-hangs.mdx
@@ -0,0 +1,75 @@
+---
+title: App Hangs and ANRs
+sidebar_order: 5100
+description: "Detect app hangs and app-not-responding events in Unreal Engine games."
+sidebar_section: features
+---
+
+Unreal Engine uses **App Not Responding** for mobile UI-thread detection and **App Hang** for game-thread detection. They are separate feature families with different options and defaults.
+
+## App Hangs
+
+Game-thread app hang tracking is disabled by default:
+
+| Option                  | Default   | Platforms                                                                   |
+| ----------------------- | --------- | --------------------------------------------------------------------------- |
+| `EnableHangTracking`    | Disabled  | Windows, Linux; required for the native watchdog on all supported platforms |
+| `HangTimeoutDuration`   | 5 seconds | Windows, Linux, macOS, Android                                              |
+| `UseNativeHangTracking` | Disabled  | Windows, Linux, macOS, Android                                              |
+
+### Engine Watcher
+
+On Windows and Linux, `EnableHangTracking` uses Unreal Engine's `FThreadHeartBeat` watcher. It requires a packaged build and `HangDuration` greater than `0`:
+
+```ini {filename:DefaultEngine.ini}
+[/Script/Sentry.SentrySettings]
+EnableHangTracking=True
+
+[Core.System]
+HangDuration=25
+```
+
+The engine watcher waits for the greater of `HangTimeoutDuration` and Unreal Engine's `StuckDuration` before capturing a stuck thread's stack trace. It uses Unreal Engine's existing heartbeat system plus a Sentry watchdog thread.
+
+### Native Watchdog
+
+Enable `UseNativeHangTracking` to use sentry-native's watchdog instead:
+
+```ini {filename:DefaultEngine.ini}
+[/Script/Sentry.SentrySettings]
+EnableHangTracking=True
+UseNativeHangTracking=True
+HangTimeoutDuration=5.0
+```
+
+The native watchdog sends an `OnEndFrame` game-thread heartbeat while the app is active and foregrounded, and runs a background watchdog thread. It does not require Unreal Engine's heartbeat configuration. On macOS, it requires the [native backend](/platforms/unreal/configuration/native-backend/). On Android, it runs alongside JVM ANR detection, so a freeze that blocks both threads can create an ANR and an `AppHang` event.
+
+## App Not Responding
+
+App Not Responding detection is enabled by default on mobile platforms:
+
+| Option                           | Default   | Platforms                                           |
+| -------------------------------- | --------- | --------------------------------------------------- |
+| `EnableAppNotRespondingTracking` | Enabled   | Android, iOS, macOS with Cocoa backend              |
+| `AppNotRespondingTimeout`        | 5 seconds | iOS, macOS with Cocoa backend, Android below API 30 |
+
+On iOS and macOS with the default Cocoa backend, these options configure Cocoa app hang detection. On macOS with the native backend, use native hang tracking instead. On Android, they configure JVM ANR detection. Android 11 and later reads ANRs from `ApplicationExitInfo` during a subsequent SDK initialization, so the operating system controls the timeout.
+
+To preserve the behavior from before SDK version `1.13.0`, explicitly disable App Not Responding tracking:
+
+```ini {filename:DefaultEngine.ini}
+[/Script/Sentry.SentrySettings]
+EnableAppNotRespondingTracking=False
+```
+
+## Queries
+
+App hang events use the `AppHang` mechanism. Search for:
+
+```
+error.mechanism.type:AppHang
+```
+
+Android JVM ANRs use `ANR`, `AppExitInfo`, or `HistoricalAppExitInfo` depending on the Android version and event source.
+
+For native watchdog behavior, see [Native SDK app hangs](/platforms/native/app-hangs/). For mobile platform details, see [Android NDK app hang detection](/platforms/android/configuration/using-ndk/#app-hang-detection) and [Apple app hangs](/platforms/apple/guides/ios/configuration/app-hangs/).