feat(native): Added App Hang capture for macOS

CHANGELOG.md

@@ -14,6 +14,7 @@
 - Apple: use `os_sync_wait_on_address` for the level-triggered waitable flag in the batcher on modern macOS(14.4+) and iOS(17.4+). ([#1765](https://github.com/getsentry/sentry-native/pull/1765))
 - Native/macOS: add thread names. ([#1766](https://github.com/getsentry/sentry-native/pull/1766))
 - Add Upload-Metadata header to TUS requests. ([#1795](https://github.com/getsentry/sentry-native/pull/1795))
+- Native/macOS: add opt-in app-hang detection. When enabled, the out-of-process crash daemon monitors a heartbeat emitted via `sentry_app_hang_heartbeat()` and captures an `AppHang` event with a full stack trace if the monitored thread stops responding for longer than the configured timeout. Configure with `sentry_options_set_app_hang_enabled()` and `sentry_options_set_app_hang_timeout_ms()`. ([#1780](https://github.com/getsentry/sentry-native/pull/1780))
 
 **Fixes**:
 

examples/example.c

@@ -612,6 +612,26 @@ run_threads(thread_func_t func)
 }
 #endif
 
+#if defined(SENTRY_PLATFORM_MACOS)
+static void *
+app_hang_demo_thread(void *arg)
+{
+    (void)arg;
+    /* The first heartbeat latches this thread as the monitored target */
+    for (int i = 0; i < 10; i++) {
+        sentry_app_hang_heartbeat();
+        usleep(50 * 1000);
+    }
+
+    sentry_add_breadcrumb(
+        sentry_value_new_breadcrumb(NULL, "app-hang demo: about to freeze"));
+    sentry_add_breadcrumb(create_debug_crumb("app-hang demo breadcrumb"));
+    /* Freeze for 3x the configured timeout (3000 ms). */
+    usleep(3000 * 1000);
+    return NULL;
+}
+#endif
+
 int
 main(int argc, char **argv)
 {
@@ -863,6 +883,13 @@ main(int argc, char **argv)
             options, SENTRY_CRASH_UPLOAD_MODE_ASYNC);
     }
 
+#if defined(SENTRY_PLATFORM_MACOS)
+    if (has_arg(argc, argv, "app-hang")) {
+        sentry_options_set_app_hang_enabled(options, 1);
+        sentry_options_set_app_hang_timeout_ms(options, 1000);
+    }
+#endif
+
     // E2E test mode: generate unique test ID for event correlation
     char e2e_test_id[37] = { 0 };
     if (has_arg(argc, argv, "e2e-test")) {
@@ -874,6 +901,23 @@ main(int argc, char **argv)
         return EXIT_FAILURE;
     }
 
+#if defined(SENTRY_PLATFORM_MACOS)
+    /* app-hang: spawn the demo thread BEFORE any other post-init work so it
+     * begins heartbeating immediately. The thread freezes for 3x the timeout,
+     * giving the daemon time to detect the hang and ship the envelope. We wait
+     * for it here so main does not exit before the transport has flushed.
+     * NOTE: this mode is intentionally exclusive – do not combine with crash/
+     *       abort/etc. since those would terminate the process first. */
+    if (has_arg(argc, argv, "app-hang")) {
+        pthread_t t;
+        if (0 == pthread_create(&t, NULL, app_hang_demo_thread, NULL)) {
+            pthread_join(t, NULL);
+        }
+        sentry_close();
+        return EXIT_SUCCESS;
+    }
+#endif
+
     if (has_arg(argc, argv, "user-consent-revoke")) {
         sentry_user_consent_revoke();
     }

include/sentry.h

@@ -1699,6 +1699,48 @@ SENTRY_EXPERIMENTAL_API void sentry_options_set_attach_session_replay(
 SENTRY_EXPERIMENTAL_API void sentry_options_set_session_replay_duration(
     sentry_options_t *opts, uint32_t duration_ms);
 
+/**
+ * Enable app-hang detection via the native crash backend.
+ *
+ * When enabled, the out-of-process daemon monitors the thread first emitting
+ * a heatbeat through `sentry_app_hang_heartbeat`.
+ * If the heartbeat goes stale for longer than the configured timeout, the
+ * daemon walks the thread's stack remotely and emits an `AppHang` event.
+ * The host process keeps running.
+ *
+ * Off by default. This setting only has an effect when using the `native`
+ * backend. In this initial release the feature is macOS-only; the call is a
+ * silent no-op on other platforms.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_options_set_app_hang_enabled(
+    sentry_options_t *opts, int enabled);
+
+/**
+ * Sets the heartbeat-staleness threshold (in milliseconds) used by the
+ * app-hang detector. Default 5000 ms.
+ *
+ * Read by the daemon once at startup; changes after `sentry_init` have no
+ * effect.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_options_set_app_hang_timeout_ms(
+    sentry_options_t *opts, uint64_t timeout_ms);
+
+/**
+ * Refresh the heartbeat.
+ *
+ * The first thread to call this becomes the monitored target for the lifetime
+ * of the SDK session (first caller wins, latched atomically). Call it from the
+ * thread you want monitored (typically the main / game thread) and ensure that
+ * thread issues the first heartbeat. Subsequent calls from any other thread are
+ * dropped.
+ *
+ * No-op if
+ * - app-hang detection is not enabled
+ * - the native backend is not active
+ * - the platform is not macOS
+ */
+SENTRY_EXPERIMENTAL_API void sentry_app_hang_heartbeat(void);
+
 /**
  * Sets the path to the crashpad handler if the crashpad backend is used.
  *

src/CMakeLists.txt

@@ -1,6 +1,8 @@
 sentry_target_sources_cwd(sentry
 	sentry_alloc.c
 	sentry_alloc.h
+	sentry_app_hang.c
+	sentry_app_hang.h
 	sentry_attachment.c
 	sentry_attachment.h
 	sentry_backend.c

src/backends/native/sentry_crash_context.h

@@ -327,6 +327,20 @@ typedef struct {
     uint32_t module_count;
     sentry_module_info_t modules[SENTRY_CRASH_MAX_MODULES];
 
+    /* App-hang detection.
+     *
+     * Sync model:
+     *  - app_hang_enabled, app_hang_timeout_ms: written by host before daemon
+     *    is signalled ready; read by daemon at startup. No further mutation.
+     *  - app_hang_target_tid: latched once by host on first heartbeat.
+     *    Daemon reads, never writes.
+     *  - app_hang_last_heartbeat_ms: written on every heartbeat.
+     */
+    bool app_hang_enabled;
+    uint64_t app_hang_timeout_ms;
+    volatile uint64_t app_hang_target_tid;
+    volatile uint64_t app_hang_last_heartbeat_ms;
+
 } sentry_crash_context_t;
 
 // Shared memory size: calculated at compile-time based on actual struct size