Skip to content

Add in-process hang tracking with Native backend on Windows, Linux, and Mac - #1427

Merged
tustanivsky merged 20 commits into
mainfrom
feat/native-app-hang-tracking
Jun 25, 2026
Merged

Add in-process hang tracking with Native backend on Windows, Linux, and Mac#1427
tustanivsky merged 20 commits into
mainfrom
feat/native-app-hang-tracking

Conversation

@tustanivsky

@tustanivsky tustanivsky commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

This PR adds opt-in native app-hang detection powered by sentry-native alongside the existing engine FThreadHeartBeat hang watcher.

Key changes

  • Added a new UseNativeHangTracking setting under Hang Tracking (requires EnableHangTracking). When enabled, hangs are detected by sentry-native's in-process app-hang watchdog instead of Unreal Engine's FThreadHeartBeat watcher.
  • Configures sentry_options_set_enable_app_hang_tracking and sentry_options_set_app_hang_timeout before sentry_init, reusing the existing HangTimeoutDuration value.
  • Registers a per-frame heartbeat on FCoreDelegates::OnEndFrame. The first tick marks the game thread as monitored, and subsequent frames refresh the heartbeat via sentry_app_hang_heartbeat.
  • When the heartbeat becomes stale, the watchdog thread captures an App Hang event while the application continues running.
  • The engine-based FSentryHangWatcher remains the default implementation and is disabled only when UseNativeHangTracking is enabled, preventing duplicate hang reports.

Testing

  • Desktop integration tests are data-driven over the two mechanisms (Engine/Native), gated per platform/backend (macOS runs the Native mechanism under the Native backend).

Known limitations

  • Desktop only (Windows/Linux/macOS). On mobile, the platform SDKs' built-in ANR/App Hang detection applies.

Documentation

Relate items

@github-actions

github-actions Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor
Messages
📖 Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against a6f599c

@bitsandfoxes bitsandfoxes changed the title Add out-of-process hang tracking with Native backend on Windows and Mac Add out-of-process hang tracking with Native backend on Windows, Linux, and Mac Jun 10, 2026
@tustanivsky tustanivsky changed the title Add out-of-process hang tracking with Native backend on Windows, Linux, and Mac Add in-process hang tracking with Native backend on Windows, Linux, and Mac Jun 19, 2026
@bitsandfoxes

Copy link
Copy Markdown
Contributor

I wonder whether we should keep this as experimental and opt-in for a bit? The new bits and pieces in sentry-native suspend the main thread, so some real-life validation before enabling this by default would be nice.

That's also the way I intend to do it for Unity: getsentry/sentry-unity#2709

@tustanivsky

Copy link
Copy Markdown
Collaborator Author

I wonder whether we should keep this as experimental and opt-in for a bit?

@bitsandfoxes Yes, it makes sense to add this as an opt-in feature. By default, the SDK continues to use Unreal's hang watcher (FThreadHeartBeat / FSentryHangWatcher) while the native's hang tracking is only enabled when configured explicitly.

@tustanivsky
tustanivsky requested a review from mujacica June 24, 2026 13:50
@tustanivsky
tustanivsky merged commit 5efbee8 into main Jun 25, 2026
489 of 497 checks passed
@tustanivsky
tustanivsky deleted the feat/native-app-hang-tracking branch June 25, 2026 08:48
tustanivsky added a commit to getsentry/sentry-docs that referenced this pull request Jun 25, 2026
…18534)

This PR adds info about opt-in native app-hang detection
(sentry-native's watchdog) via the new `UseNativeHangTracking` setting,
alongside the existing engine watcher, on Windows, Linux, and macOS.

Related items:
- getsentry/sentry-unreal#1427

---------

Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants