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

tustanivsky · getsentry-bot · bitsandfoxes · web-flow · commit 5efbee808d69 · 2026-06-25T11:48:08.000+03:00
* Add out-of-process hang tracking with `Native` backend on Windows and Mac

* Format code

* Update changelog

* Exclude Windows-specific API

* bumped to 'feat/app-hang-linux'

* moved to inproc implementation

* bumped again

* Bump submodule (test)

* Fix setting name

* Fix platform include

* Fix option name

* Rework hang tests

* Fix test shutdown

* Simplify hang tests

* Fix event's IsAnr check for native

* Clean up

---------

Co-authored-by: Sentry Github Bot &lt;bot+github-bot@sentry.io&gt;
Co-authored-by: bitsandfoxes &lt;reg@bitfox.at&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@
 ### Features
 
 - Add Unreal Engine 5.8 support ([#1440](https://github.com/getsentry/sentry-unreal/pull/1440))
+- Add opt-in native app-hang tracking on Windows, Mac and Linux ([#1427](https://github.com/getsentry/sentry-unreal/pull/1427))
 
 ### Dependencies
 
diff --git a/integration-test/Integration.Desktop.Tests.ps1 b/integration-test/Integration.Desktop.Tests.ps1
@@ -80,6 +80,21 @@ BeforeDiscovery {
         # Memory overcommit makes OOM conditions unreliable to trigger in tests on Linux and macOS
         $TestCrashTypes = $TestCrashTypes | Where-Object { $_.Name -ne 'OutOfMemory' }
     }
+
+    # Define hang detection mechanisms to test
+    $TestHangMechanisms = @(
+        @{ Name = 'Engine'; ExceptionType = 'App Hanging'; ExceptionValuePattern = '^Application not responding$'; ExpectsCrashTypeTag = $true  }
+        @{ Name = 'Native'; ExceptionType = 'AppHang';     ExceptionValuePattern = 'App hung for at least \d+ ms';   ExpectsCrashTypeTag = $false }
+    )
+
+    if ($IsMacOS) {
+        if ($script:IsNativeBackend) {
+            $TestHangMechanisms = @($TestHangMechanisms | Where-Object { $_.Name -eq 'Native' })
+        }
+        else {
+            $TestHangMechanisms = @()
+        }
+    }
 }
 
 BeforeAll {
@@ -378,13 +393,12 @@ Describe "Sentry Unreal Desktop Integration Tests (<Platform>)" -ForEach $TestTa
         }
     }
 
-    # Hang tracking is not supported on macOS (sentry-cocoa has its own AppHang detection)
-    Context "Hang Tracking Tests" -Skip:$IsMacOS {
+    Context "Hang Tracking Tests - <Name>" -ForEach $TestHangMechanisms {
         BeforeAll {
             $script:HangResult = $null
             $script:HangEvent = $null
 
-            Write-Host "Running hang tracking test..." -ForegroundColor Yellow
+            Write-Host "Running hang tracking test ($($_.Name))..." -ForegroundColor Yellow
 
             $appArgs = @(
                 '-nullrhi',     # Runs without graphics rendering (headless mode)
@@ -396,6 +410,9 @@ Describe "Sentry Unreal Desktop Integration Tests (<Platform>)" -ForEach $TestTa
             # Override default project settings
             $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:Dsn=$script:DSN"
             $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:EnableHangTracking=True"
+            if ($_.Name -eq 'Native') {
+                $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:UseNativeHangTracking=True"
+            }
 
             # -hang-capture triggers hang test scenario in the sample app
             $script:HangResult = Invoke-DeviceApp -ExecutablePath $script:AppPath -Arguments ((@('-hang-capture') + $appArgs) -join ' ')
@@ -449,12 +466,12 @@ Describe "Sentry Unreal Desktop Integration Tests (<Platform>)" -ForEach $TestTa
             $script:HangEvent.platform | Should -Be 'native'
         }
 
-        It "Should have exception with App Hanging type" {
+        It "Should have exception with expected type and value" {
             $script:HangEvent.exception | Should -Not -BeNullOrEmpty
             $script:HangEvent.exception.values | Should -Not -BeNullOrEmpty
             $exception = $script:HangEvent.exception.values[0]
-            $exception.type | Should -Be 'App Hanging'
-            $exception.value | Should -Be 'Application not responding'
+            $exception.type | Should -Be $ExceptionType
+            $exception.value | Should -Match $ExceptionValuePattern
         }
 
         It "Should have AppHang mechanism" {
@@ -474,7 +491,7 @@ Describe "Sentry Unreal Desktop Integration Tests (<Platform>)" -ForEach $TestTa
             ($tags | Where-Object { $_.key -eq 'test.suite' }).value | Should -Be 'integration'
         }
 
-        It "Should have CrashType tag" {
+        It "Should have CrashType tag" -Skip:(-not $ExpectsCrashTypeTag) {
             $tags = $script:HangEvent.tags
             ($tags | Where-Object { $_.key -eq 'CrashType' }).value | Should -Be 'Hang'
         }
diff --git a/plugin-dev/Source/Sentry/Private/Android/AndroidSentrySubsystem.cpp b/plugin-dev/Source/Sentry/Private/Android/AndroidSentrySubsystem.cpp
@@ -342,6 +342,11 @@ bool FAndroidSentrySubsystem::IsHangTrackingSupported() const
 	return false;
 }
 
+bool FAndroidSentrySubsystem::IsNativeHangTrackingEnabled() const
+{
+	return false;
+}
+
 void FAndroidSentrySubsystem::CaptureFeedback(TSharedPtr<ISentryFeedback> feedback)
 {
 	TSharedPtr<FAndroidSentryFeedback> feedbackAndroid = StaticCastSharedPtr<FAndroidSentryFeedback>(feedback);
diff --git a/plugin-dev/Source/Sentry/Private/Android/AndroidSentrySubsystem.h b/plugin-dev/Source/Sentry/Private/Android/AndroidSentrySubsystem.h
@@ -32,6 +32,7 @@ class FAndroidSentrySubsystem : public ISentrySubsystem
 	virtual TSharedPtr<ISentryId> CaptureEnsure(const FString& type, const FString& message) override;
 	virtual TSharedPtr<ISentryId> CaptureHang(uint32 HungThreadId) override;
 	virtual bool IsHangTrackingSupported() const override;
+	virtual bool IsNativeHangTrackingEnabled() const override;
 	virtual void CaptureFeedback(TSharedPtr<ISentryFeedback> feedback) override;
 	virtual void SetUser(TSharedPtr<ISentryUser> user) override;
 	virtual void RemoveUser() override;
diff --git a/plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.cpp b/plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.cpp
@@ -463,6 +463,11 @@ bool FAppleSentrySubsystem::IsHangTrackingSupported() const
 	return false;
 }
 
+bool FAppleSentrySubsystem::IsNativeHangTrackingEnabled() const
+{
+	return false;
+}
+
 void FAppleSentrySubsystem::CaptureFeedback(TSharedPtr<ISentryFeedback> feedback)
 {
 	TSharedPtr<FAppleSentryFeedback> feedbackApple = StaticCastSharedPtr<FAppleSentryFeedback>(feedback);
diff --git a/plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.h b/plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.h
@@ -31,6 +31,7 @@ class FAppleSentrySubsystem : public ISentrySubsystem
 	virtual TSharedPtr<ISentryId> CaptureEnsure(const FString& type, const FString& message) override;
 	virtual TSharedPtr<ISentryId> CaptureHang(uint32 HungThreadId) override;
 	virtual bool IsHangTrackingSupported() const override;
+	virtual bool IsNativeHangTrackingEnabled() const override;
 	virtual void CaptureFeedback(TSharedPtr<ISentryFeedback> feedback) override;
 	virtual void SetUser(TSharedPtr<ISentryUser> user) override;
 	virtual void RemoveUser() override;
diff --git a/plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentryEvent.cpp b/plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentryEvent.cpp
@@ -314,8 +314,10 @@ bool FGenericPlatformSentryEvent::IsAnr() const
 		return false;
 	}
 
+	// The engine FThreadHeartBeat watcher reports "App Hanging" (see CaptureHang) while sentry-native's
+	// app-hang watchdog reports "AppHang" - accept either so both detection mechanisms are recognized
 	const char* type = sentry_value_as_string(sentry_value_get_by_key(firstException, "type"));
-	bool isAppHangException = type && FCStringAnsi::Strcmp(type, "App Hanging") == 0;
+	bool isAppHangException = type && (FCStringAnsi::Strcmp(type, "App Hanging") == 0 || FCStringAnsi::Strcmp(type, "AppHang") == 0);
 
 	sentry_value_t mechanism = sentry_value_get_by_key(firstException, "mechanism");
 	const char* mechanismType = sentry_value_as_string(sentry_value_get_by_key(mechanism, "type"));
diff --git a/plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.cpp b/plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.cpp
@@ -483,6 +483,7 @@ FGenericPlatformSentrySubsystem::FGenericPlatformSentrySubsystem()
 	, isScreenshotAttachmentEnabled(false)
 	, isSessionReplayAttachmentEnabled(false)
 	, isGpuDumpAttachmentEnabled(false)
+	, bNativeHangTracking(false)
 	, initTimestamp(FDateTime::UtcNow())
 {
 }
@@ -560,6 +561,15 @@ void FGenericPlatformSentrySubsystem::InitWithSettings(const USentrySettings* se
 	ConfigureNetworkConnectFunc(options);
 	ConfigureStackCaptureStrategy(options);
 
+#if PLATFORM_WINDOWS || PLATFORM_MAC || PLATFORM_LINUX
+	bNativeHangTracking = settings->EnableHangTracking && settings->UseNativeHangTracking;
+	if (bNativeHangTracking)
+	{
+		sentry_options_set_enable_app_hang_tracking(options, 1);
+		sentry_options_set_app_hang_timeout(options, static_cast<uint64_t>(settings->HangTimeoutDuration * 1000.0));
+	}
+#endif
+
 	if (settings->EnableExternalCrashReporter)
 	{
 		ConfigureCrashReporterPath(options);
@@ -621,6 +631,16 @@ void FGenericPlatformSentrySubsystem::InitWithSettings(const USentrySettings* se
 	isStackTraceEnabled = settings->AttachStacktrace;
 	isPiiAttachmentEnabled = settings->SendDefaultPii;
 
+	if (bNativeHangTracking && isEnabled)
+	{
+		// OnEndFrame is broadcast on the game thread, so the first invocation latches it as the monitored
+		// thread and every subsequent frame refreshes the heartbeat the daemon watches for staleness
+		AppHangHeartbeatHandle = FCoreDelegates::OnEndFrame.AddLambda([]()
+		{
+			sentry_app_hang_heartbeat();
+		});
+	}
+
 	// Best-effort at writing user consent to disk so that user consent can change at runtime and persist
 	// We should never have a valid user consent state return "Unknown", so assume that no consent value is written if we see this
 	if (settings->bRequireUserConsent && GetUserConsent() == EUserConsent::Unknown)
@@ -657,6 +677,12 @@ void FGenericPlatformSentrySubsystem::InitWithSettings(const USentrySettings* se
 
 void FGenericPlatformSentrySubsystem::Close()
 {
+	if (AppHangHeartbeatHandle.IsValid())
+	{
+		FCoreDelegates::OnEndFrame.Remove(AppHangHeartbeatHandle);
+		AppHangHeartbeatHandle.Reset();
+	}
+
 	isEnabled = false;
 
 #ifdef USE_SENTRY_SESSION_REPLAY
diff --git a/plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.h b/plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.h
@@ -71,6 +71,7 @@ class FGenericPlatformSentrySubsystem : public ISentrySubsystem
 
 	virtual void HandleAssert() override {}
 	virtual bool IsHangTrackingSupported() const override { return false; }
+	virtual bool IsNativeHangTrackingEnabled() const override { return bNativeHangTracking; }
 	virtual FString GetDeviceType() const override { return TEXT("Desktop"); }
 
 	USentryBeforeSendHandler* GetBeforeSendHandler() const;
@@ -154,6 +155,10 @@ class FGenericPlatformSentrySubsystem : public ISentrySubsystem
 	bool isSessionReplayAttachmentEnabled;
 	bool isGpuDumpAttachmentEnabled;
 
+	bool bNativeHangTracking;
+
+	FDelegateHandle AppHangHeartbeatHandle;
+
 	FDateTime initTimestamp;
 
 	FString databaseParentPath;
diff --git a/plugin-dev/Source/Sentry/Private/Interface/SentrySubsystemInterface.h b/plugin-dev/Source/Sentry/Private/Interface/SentrySubsystemInterface.h
@@ -77,5 +77,6 @@ class ISentrySubsystem
 	/** Unreal-specific methods that are not part of the platform's Sentry SDK API */
 	virtual void HandleAssert() = 0;
 	virtual bool IsHangTrackingSupported() const = 0;
+	virtual bool IsNativeHangTrackingEnabled() const = 0;
 	virtual FString GetDeviceType() const = 0;
 };
diff --git a/plugin-dev/Source/Sentry/Private/Null/NullSentrySubsystem.h b/plugin-dev/Source/Sentry/Private/Null/NullSentrySubsystem.h
@@ -55,6 +55,7 @@ class FNullSentrySubsystem : public ISentrySubsystem
 
 	virtual void HandleAssert() override {}
 	virtual bool IsHangTrackingSupported() const override { return false; }
+	virtual bool IsNativeHangTrackingEnabled() const override { return false; }
 	virtual FString GetDeviceType() const override { return TEXT("Unknown"); }
 };
 
diff --git a/plugin-dev/Source/Sentry/Private/SentrySettings.cpp b/plugin-dev/Source/Sentry/Private/SentrySettings.cpp
@@ -60,6 +60,7 @@ USentrySettings::USentrySettings(const FObjectInitializer& ObjectInitializer)
 	, EnableExternalCrashReporter(false)
 	, EnableHangTracking(false)
 	, HangTimeoutDuration(5.0f)
+	, UseNativeHangTracking(false)
 	, AttachSessionReplay(false)
 	, SessionReplayDurationMs(5000)
 	, EnableOfflineCaching(false)
diff --git a/plugin-dev/Source/Sentry/Private/SentrySubsystem.cpp b/plugin-dev/Source/Sentry/Private/SentrySubsystem.cpp
@@ -167,7 +167,7 @@ void USentrySubsystem::Initialize()
 		SubsystemNativeImpl->CaptureEnsure(TEXT("Ensure failed"), EnsureMessage.TrimStartAndEnd());
 	});
 
-	if (Settings->EnableHangTracking && SubsystemNativeImpl->IsHangTrackingSupported())
+	if (Settings->EnableHangTracking && SubsystemNativeImpl->IsHangTrackingSupported() && !SubsystemNativeImpl->IsNativeHangTrackingEnabled())
 	{
 		ConfigureHangTracking();
 	}
diff --git a/plugin-dev/Source/Sentry/Public/SentrySettings.h b/plugin-dev/Source/Sentry/Public/SentrySettings.h
@@ -546,15 +546,19 @@ class SENTRY_API USentrySettings : public UObject
 	FSentryCrashReporterAppearance CrashReporterAppearance;
 
 	UPROPERTY(Config, EditAnywhere, Category = "General|Native",
-		Meta = (DisplayName = "Enable hang tracking",
-			ToolTip = "Track application hangs (unresponsive game thread) using Unreal Engine's built-in FThreadHeartBeat. Only effective in packaged builds."))
+		Meta = (DisplayName = "Enable hang tracking", ToolTip = "Track application hangs (unresponsive game thread) using Unreal Engine's built-in FThreadHeartBeat. Only effective in packaged builds."))
 	bool EnableHangTracking;
 
 	UPROPERTY(Config, EditAnywhere, Category = "General|Native",
 		Meta = (DisplayName = "Hang timeout (seconds)", ToolTip = "Duration in seconds that a thread must be unresponsive before a hang event is captured.",
 			EditCondition = "EnableHangTracking", ClampMin = 1.0f))
 	float HangTimeoutDuration;
 
+	UPROPERTY(Config, EditAnywhere, Category = "General|Native",
+		Meta = (DisplayName = "Use native hang tracking", ToolTip = "Detect hangs with the sentry-native SDK's built-in app-hang watchdog instead of Unreal Engine's FThreadHeartBeat-based watcher. Works with any crash handler backend (both Crashpad and Native). Supported on Windows, macOS and Linux; ignored on other platforms.",
+			EditCondition = "EnableHangTracking"))
+	bool UseNativeHangTracking;
+
 	UPROPERTY(Config, EditAnywhere, Category = "General|Session Replay",
 		Meta = (DisplayName = "Enable session replay (experimental)", ToolTip = "Captures gameplay video and attaches it to crash reports. On desktop platforms (Windows/Mac/Linux), requires the AVCodecsCore plugin plus a codec plugin matching the GPU vendor (NVCodecs for NVIDIA on Windows/Linux, AMFCodecs for AMD on Windows, VTCodecs on Mac) and rebuild after changing. On Xbox, development kits only. On Android, a 30s clip sampled at 1 frame/second.",
 			ConfigRestartRequired = true))
diff --git a/sample/Source/SentryPlayground/IntegrationTests/SentryHangTest.cpp b/sample/Source/SentryPlayground/IntegrationTests/SentryHangTest.cpp
@@ -28,12 +28,27 @@ void FSentryHangTest::Run()
 
 	Subsystem->SetTag(TEXT("test.hang_id"), EventId);
 
-	// Defer the hang trigger until after engine loop init so that the heartbeat
-	// monitor thread is running and threads have registered their heartbeats.
+	// The hang must be triggered only after the game thread has ticked a few frames.
 	// Capture AsShared() so this test stays alive past RunIntegrationTest returning.
 	TSharedRef<FSentryBaseIntegrationTest> Self = AsShared();
-	FCoreDelegates::OnFEngineLoopInitComplete.AddLambda([Self]()
+	TSharedRef<int32> FrameCounter = MakeShared<int32>(0);
+	TSharedRef<bool> bHangTriggered = MakeShared<bool>(false);
+
+	FCoreDelegates::OnEndFrame.AddLambda([Self, FrameCounter, bHangTriggered]()
 	{
+		if (*bHangTriggered)
+		{
+			return;
+		}
+
+		constexpr int32 FramesBeforeHang = 3;
+		if (++(*FrameCounter) < FramesBeforeHang)
+		{
+			return;
+		}
+
+		*bHangTriggered = true;
+
 		USentryPlaygroundCrashUtils::Terminate(ESentryAppTerminationType::Hang);
 
 		Self->GetSubsystem()->Close();

Original file line number	Diff line number	Diff line change
`@@ -342,6 +342,11 @@ bool FAndroidSentrySubsystem::IsHangTrackingSupported() const`
`342`	`342`	`return false;`
`343`	`343`	`}`
`344`	`344`
	`345`	`+bool FAndroidSentrySubsystem::IsNativeHangTrackingEnabled() const`
	`346`	`+{`
	`347`	`+ return false;`
	`348`	`+}`
	`349`	`+`
`345`	`350`	`void FAndroidSentrySubsystem::CaptureFeedback(TSharedPtr<ISentryFeedback> feedback)`
`346`	`351`	`{`
`347`	`352`	`TSharedPtr<FAndroidSentryFeedback> feedbackAndroid = StaticCastSharedPtr<FAndroidSentryFeedback>(feedback);`
Original file line number	Diff line number	Diff line change
`@@ -463,6 +463,11 @@ bool FAppleSentrySubsystem::IsHangTrackingSupported() const`
`463`	`463`	`return false;`
`464`	`464`	`}`
`465`	`465`
	`466`	`+bool FAppleSentrySubsystem::IsNativeHangTrackingEnabled() const`
	`467`	`+{`
	`468`	`+ return false;`
	`469`	`+}`
	`470`	`+`
`466`	`471`	`void FAppleSentrySubsystem::CaptureFeedback(TSharedPtr<ISentryFeedback> feedback)`
`467`	`472`	`{`
`468`	`473`	`TSharedPtr<FAppleSentryFeedback> feedbackApple = StaticCastSharedPtr<FAppleSentryFeedback>(feedback);`