Add support for printing crash stack traces to the game log (Microsoft) (#1177)

* Add new plugin setting allowing to opt-in logging during crash handling

* Add crash stacktrace logger for Windows

* Fix printing native logs during memory-related crash handling

* Fix issue with stacktrace logging in packaged dev build

* Add memory corruption test util

* Fix UE4 compat issues

* Clean up includes

* Format code

* Clean up

* Add integration tests for more crash types (stack overflow, memory corruption)

* Format code

* Update changelog

* Update snapshot

* Fix issue with logging during running tests in UE 4.27 on Linux

* Disable auto init in sample app when running integration tests

* Make sleep before crash Android-only step

* Refactor desktop tests

* Fix PR suggestions

* Fix else-if chain in sample app

* Add null check for exception address

* Rename test args

* Transfer ownership of crashed thread handle to logger

* Format code

* Fix clear

* Enable logging during crash handling for tests

* Add more checks

* Format code

* Test generic crash logger

* Format code

* Fix

* Test

* Add unified logger implementation fox Windows and Xbox

* Test ci

* Fix build errors

* Update package snapshot

* Revert ci trigger

* Update changelog

* Test sleep for init-only mode

* Change max stacktrace depth (test)

* Remove dsn input arg parsing from sample

* Update readme

---------

Co-authored-by: Sentry Github Bot <[email protected]>

Author: tustanivsky

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Features
 
-- Add support for printing crash stack traces to the game log (Windows) ([#1170](https://github.com/getsentry/sentry-unreal/pull/1170))
+- Add support for printing crash stack traces to the game log (Windows, Xbox) ([#1177](https://github.com/getsentry/sentry-unreal/pull/1177))
 
 ### Fixes
 

integration-test/Integration.Desktop.Tests.ps1

@@ -134,9 +134,9 @@ Describe "Sentry Unreal Desktop Integration Tests (<Platform>)" -ForEach $TestTa
             )
 
             # Override default project settings
-            $appArgs += '-ini:Engine:[/Script/Sentry.SentrySettings]:InitAutomatically=False'       # Prevents double initialization
-            $appArgs += '-ini:Engine:[/Script/Sentry.SentrySettings]:EnableOnCrashLogging=True'     # Enables crash logging
-            $appArgs += '-ini:Engine:[/Script/Sentry.SentrySettings]:EnableAutoLogAttachment=True'  # Enables log attachment
+            $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:Dsn=$script:DSN"               # Prevents double initialization
+            $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:EnableOnCrashLogging=True"     # Enables crash logging
+            $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:EnableAutoLogAttachment=True"  # Enables log attachment
 
             # $crashTypeArg triggers specific crash type scenario in the sample app
             $script:CrashResult = Invoke-DeviceApp -ExecutablePath $script:AppPath -Arguments ((@($crashTypeArg) + $appArgs) -join ' ')
@@ -240,7 +240,7 @@ Describe "Sentry Unreal Desktop Integration Tests (<Platform>)" -ForEach $TestTa
             )
 
             # Override default project settings to avoid double initialization
-            $appArgs += '-ini:Engine:[/Script/Sentry.SentrySettings]:InitAutomatically=False'
+            $appArgs += "-ini:Engine:[/Script/Sentry.SentrySettings]:Dsn=$script:DSN"
 
             # -message-capture triggers integration test message scenario in the sample app
             $script:MessageResult = Invoke-DeviceApp -ExecutablePath $script:AppPath -Arguments ((@('-message-capture') + $appArgs) -join ' ')

…frastructure/WindowsSentryConverters.cpp …astructure/MicrosoftSentryConverters.cppplugin-dev/Source/Sentry/Private/Windows/Infrastructure/WindowsSentryConverters.cpp renamed to plugin-dev/Source/Sentry/Private/Microsoft/Infrastructure/MicrosoftSentryConverters.cpp plugin-dev/Source/Sentry/Private/Windows/Infrastructure/WindowsSentryConverters.cpp renamed to plugin-dev/Source/Sentry/Private/Microsoft/Infrastructure/MicrosoftSentryConverters.cpp

@@ -1,10 +1,10 @@
 // Copyright (c) 2025 Sentry. All Rights Reserved.
 
-#include "WindowsSentryConverters.h"
+#include "MicrosoftSentryConverters.h"
 
 #if USE_SENTRY_NATIVE
 
-/* static */ void FWindowsSentryConverters::SentryCrashContextToString(const sentry_ucontext_t* crashContext, TCHAR* outErrorString, int32 errorStringBufSize)
+/* static */ void FMicrosoftSentryConverters::SentryCrashContextToString(const sentry_ucontext_t* crashContext, TCHAR* outErrorString, int32 errorStringBufSize)
 {
 	EXCEPTION_RECORD* ExceptionRecord = crashContext->exception_ptrs.ExceptionRecord;
 	if (!ExceptionRecord)

plugin-dev/Source/Sentry/Private/Microsoft/Infrastructure/MicrosoftSentryConverters.h

@@ -0,0 +1,28 @@
+// Copyright (c) 2025 Sentry. All Rights Reserved.
+
+#pragma once
+
+#if USE_SENTRY_NATIVE
+
+#include "CoreMinimal.h"
+
+#include "GenericPlatform/Convenience/GenericPlatformSentryInclude.h"
+
+/**
+ * Utility class for converting Sentry crash context to human-readable strings.
+ * Shared across all Microsoft platforms (Windows, Xbox).
+ */
+class FMicrosoftSentryConverters
+{
+public:
+	/**
+	 * Converts Sentry crash context to a human-readable exception string.
+	 *
+	 * @param crashContext - Sentry crash context containing exception information
+	 * @param outErrorString - Output buffer for the error string
+	 * @param errorStringBufSize - Size of the output buffer
+	 */
+	static void SentryCrashContextToString(const sentry_ucontext_t* crashContext, TCHAR* outErrorString, int32 errorStringBufSize);
+};
+
+#endif // USE_SENTRY_NATIVE

…y/Private/Windows/WindowsCrashLogger.cpp …Microsoft/MicrosoftSentryCrashLogger.cppplugin-dev/Source/Sentry/Private/Windows/WindowsCrashLogger.cpp renamed to plugin-dev/Source/Sentry/Private/Microsoft/MicrosoftSentryCrashLogger.cpp plugin-dev/Source/Sentry/Private/Windows/WindowsCrashLogger.cpp renamed to plugin-dev/Source/Sentry/Private/Microsoft/MicrosoftSentryCrashLogger.cpp

@@ -1,19 +1,21 @@
 // Copyright (c) 2025 Sentry. All Rights Reserved.
 
-#include "WindowsCrashLogger.h"
+#include "MicrosoftSentryCrashLogger.h"
 
 #if USE_SENTRY_NATIVE
 
 #include "SentryDefines.h"
 
-#include "Windows/Infrastructure/WindowsSentryConverters.h"
+#include "Infrastructure/MicrosoftSentryConverters.h"
 
 #include "CoreGlobals.h"
+#include "HAL/PlatformStackWalk.h"
 #include "Misc/EngineVersionComparison.h"
 #include "Misc/OutputDeviceRedirector.h"
-#include "Windows/WindowsPlatformStackWalk.h"
 
-FWindowsCrashLogger::FWindowsCrashLogger()
+#include "Microsoft/AllowMicrosoftPlatformTypes.h"
+
+FMicrosoftSentryCrashLogger::FMicrosoftSentryCrashLogger()
 	: CrashLoggingThread(nullptr)
 	, CrashLoggingThreadId(0)
 	, CrashEvent(nullptr)
@@ -23,9 +25,9 @@ FWindowsCrashLogger::FWindowsCrashLogger()
 	, SharedCrashedThreadHandle(nullptr)
 {
 	// Create synchronization events
-	CrashEvent = CreateEvent(nullptr, Windows::FALSE, Windows::FALSE, nullptr);			 // Auto-reset event
-	CrashCompletedEvent = CreateEvent(nullptr, Windows::FALSE, Windows::FALSE, nullptr); // Auto-reset event
-	StopThreadEvent = CreateEvent(nullptr, Windows::TRUE, Windows::FALSE, nullptr);		 // Manual-reset event
+	CrashEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);		   // Auto-reset event
+	CrashCompletedEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr); // Auto-reset event
+	StopThreadEvent = CreateEvent(nullptr, TRUE, FALSE, nullptr);	   // Manual-reset event
 
 	if (!CrashEvent || !CrashCompletedEvent || !StopThreadEvent)
 	{
@@ -55,7 +57,7 @@ FWindowsCrashLogger::FWindowsCrashLogger()
 	}
 }
 
-FWindowsCrashLogger::~FWindowsCrashLogger()
+FMicrosoftSentryCrashLogger::~FMicrosoftSentryCrashLogger()
 {
 	if (StopThreadEvent)
 	{
@@ -89,7 +91,7 @@ FWindowsCrashLogger::~FWindowsCrashLogger()
 	}
 }
 
-bool FWindowsCrashLogger::LogCrash(const sentry_ucontext_t* CrashContext, HANDLE CrashedThreadHandle, DWORD TimeoutMs)
+bool FMicrosoftSentryCrashLogger::LogCrash(const sentry_ucontext_t* CrashContext, HANDLE CrashedThreadHandle, DWORD TimeoutMs)
 {
 	if (!CrashLoggingThread || !CrashEvent || !CrashCompletedEvent)
 	{
@@ -116,9 +118,9 @@ bool FWindowsCrashLogger::LogCrash(const sentry_ucontext_t* CrashContext, HANDLE
 	return (WaitResult == WAIT_OBJECT_0);
 }
 
-DWORD WINAPI FWindowsCrashLogger::CrashLoggingThreadProc(LPVOID Parameter)
+DWORD WINAPI FMicrosoftSentryCrashLogger::CrashLoggingThreadProc(LPVOID Parameter)
 {
-	FWindowsCrashLogger* Logger = static_cast<FWindowsCrashLogger*>(Parameter);
+	FMicrosoftSentryCrashLogger* Logger = static_cast<FMicrosoftSentryCrashLogger*>(Parameter);
 	if (!Logger)
 	{
 		return 1;
@@ -129,7 +131,7 @@ DWORD WINAPI FWindowsCrashLogger::CrashLoggingThreadProc(LPVOID Parameter)
 	while (true)
 	{
 		// Wait for either a crash event or stop event
-		DWORD WaitResult = WaitForMultipleObjects(2, Events, Windows::FALSE, INFINITE);
+		DWORD WaitResult = WaitForMultipleObjects(2, Events, FALSE, INFINITE);
 
 		if (WaitResult == WAIT_OBJECT_0)
 		{
@@ -154,7 +156,7 @@ DWORD WINAPI FWindowsCrashLogger::CrashLoggingThreadProc(LPVOID Parameter)
 	return 0;
 }
 
-void FWindowsCrashLogger::PerformCrashLogging()
+void FMicrosoftSentryCrashLogger::PerformCrashLogging()
 {
 	// Perform stack walking and fill GErrorHist
 	// This happens in a separate thread to avoid stack overflow issues
@@ -183,7 +185,7 @@ void FWindowsCrashLogger::PerformCrashLogging()
 	SharedCrashedThreadHandle = nullptr;
 }
 
-void* FWindowsCrashLogger::GetExceptionAddress(const sentry_ucontext_t* CrashContext)
+void* FMicrosoftSentryCrashLogger::GetExceptionAddress(const sentry_ucontext_t* CrashContext)
 {
 	if (CrashContext && CrashContext->exception_ptrs.ExceptionRecord)
 	{
@@ -193,10 +195,10 @@ void* FWindowsCrashLogger::GetExceptionAddress(const sentry_ucontext_t* CrashCon
 	return nullptr;
 }
 
-void FWindowsCrashLogger::WriteToErrorBuffers(const sentry_ucontext_t* CrashContext, HANDLE CrashedThreadHandle)
+void FMicrosoftSentryCrashLogger::WriteToErrorBuffers(const sentry_ucontext_t* CrashContext, HANDLE CrashedThreadHandle)
 {
 	// Step 1: Write exception description to GErrorExceptionDescription
-	FWindowsSentryConverters::SentryCrashContextToString(
+	FMicrosoftSentryConverters::SentryCrashContextToString(
 		CrashContext,
 		GErrorExceptionDescription,
 		UE_ARRAY_COUNT(GErrorExceptionDescription));
@@ -219,24 +221,19 @@ void FWindowsCrashLogger::WriteToErrorBuffers(const sentry_ucontext_t* CrashCont
 
 	if (CrashedThreadHandle && CrashContext->exception_ptrs.ContextRecord)
 	{
-		// Create thread context wrapper for safe cross-thread stack walking
-		void* ContextWrapper = FWindowsPlatformStackWalk::MakeThreadContextWrapper(
+		// Create platform-specific context wrapper for cross-thread stack walking
+		FPlatformStackWalk StackWalker;
+		void* ContextWrapper = StackWalker.MakeThreadContextWrapper(
 			CrashContext->exception_ptrs.ContextRecord,
 			CrashedThreadHandle);
 
 		if (ContextWrapper)
 		{
-			// Perform stack walking using the crashed thread's context
-			void* ProgramCounter = GetExceptionAddress(CrashContext);
-
-#if !UE_VERSION_OLDER_THAN(5, 0, 0)
-			FPlatformStackWalk::StackWalkAndDump(StackTrace, StackTraceSize, ProgramCounter, ContextWrapper);
-#else
-			FPlatformStackWalk::StackWalkAndDump(StackTrace, StackTraceSize, 0, ContextWrapper);
-#endif
+			// Platform-specific stack walking (Xbox overrides this)
+			PerformStackWalk(StackTrace, StackTraceSize, ContextWrapper, CrashContext, CrashedThreadHandle);
 
-			// Release the context wrapper
-			FWindowsPlatformStackWalk::ReleaseThreadContextWrapper(ContextWrapper);
+			// Release the platform-specific context wrapper
+			StackWalker.ReleaseThreadContextWrapper(ContextWrapper);
 		}
 	}
 
@@ -248,4 +245,36 @@ void FWindowsCrashLogger::WriteToErrorBuffers(const sentry_ucontext_t* CrashCont
 #endif
 }
 
+void FMicrosoftSentryCrashLogger::PerformStackWalk(ANSICHAR* StackTrace, SIZE_T StackTraceSize, void* ContextWrapper, const sentry_ucontext_t* CrashContext, HANDLE CrashedThreadHandle)
+{
+	// Unified implementation for all Microsoft platforms (Windows, Xbox)
+	// Use CaptureThreadStackBackTrace which properly handles context wrappers on all platforms
+
+	const uint32 MaxDepth = 64;
+	uint64 BackTrace[MaxDepth];
+
+	// Get the thread ID from the thread handle
+	DWORD CrashedThreadId = GetThreadId(CrashedThreadHandle);
+
+	// CaptureThreadStackBackTrace properly determines for which thread stack walking should be performed
+#if !UE_VERSION_OLDER_THAN(5, 0, 0)
+	uint32 Depth = FPlatformStackWalk::CaptureThreadStackBackTrace(CrashedThreadId, BackTrace, MaxDepth, ContextWrapper);
+#else
+	uint32 Depth = FPlatformStackWalk::CaptureThreadStackBackTrace(CrashedThreadId, BackTrace, MaxDepth);
+#endif
+
+	// Format the captured addresses into human-readable strings
+	for (uint32 i = 0; i < Depth; i++)
+	{
+		FPlatformStackWalk::ProgramCounterToHumanReadableString(i, BackTrace[i], StackTrace, StackTraceSize, nullptr);
+#if !UE_VERSION_OLDER_THAN(5, 6, 0)
+		FCStringAnsi::StrncatTruncateDest(StackTrace, (int32)StackTraceSize, LINE_TERMINATOR_ANSI);
+#else
+		FCStringAnsi::Strncat(StackTrace, LINE_TERMINATOR_ANSI, (int32)StackTraceSize);
+#endif
+	}
+}
+
+#include "Microsoft/HideMicrosoftPlatformTypes.h"
+
 #endif // USE_SENTRY_NATIVE

…try/Private/Windows/WindowsCrashLogger.h …e/Microsoft/MicrosoftSentryCrashLogger.hplugin-dev/Source/Sentry/Private/Windows/WindowsCrashLogger.h renamed to plugin-dev/Source/Sentry/Private/Microsoft/MicrosoftSentryCrashLogger.h plugin-dev/Source/Sentry/Private/Windows/WindowsCrashLogger.h renamed to plugin-dev/Source/Sentry/Private/Microsoft/MicrosoftSentryCrashLogger.h

@@ -9,21 +9,22 @@
 #include "GenericPlatform/Convenience/GenericPlatformSentryInclude.h"
 
 /**
- * Class that manages a dedicated thread for safe crash logging on Windows.
+ * Base class for crash logging on Microsoft platforms (Windows, Xbox).
  *
  * This class creates a separate thread that performs stack walking and logging
  * during crash handling. By using a separate thread, we:
  * - Avoid stack overflow issues (thread has its own stack)
  * - Can safely walk the crashed thread's stack
  * - Write crash information to game log file without risking secondary crashes
  *
- * The implementation mirrors Unreal's own Crash Reporter design (see WindowsPlatformCrashContext.cpp).
+ * Platform-specific implementations override context wrapper management functions
+ * to handle differences in stack walking APIs between platforms.
  */
-class FWindowsCrashLogger
+class FMicrosoftSentryCrashLogger
 {
 public:
-	FWindowsCrashLogger();
-	~FWindowsCrashLogger();
+	FMicrosoftSentryCrashLogger();
+	virtual ~FMicrosoftSentryCrashLogger();
 
 	/**
 	 * Logs crash information from a separate thread.
@@ -43,6 +44,20 @@ class FWindowsCrashLogger
 	 */
 	bool IsThreadRunning() const { return CrashLoggingThread != nullptr; }
 
+protected:
+	/**
+	 * Performs stack walking on the crashed thread.
+	 * Uses FPlatformStackWalk::CaptureThreadStackBackTrace which properly handles context wrappers
+	 * on all Microsoft platforms (Windows, Xbox).
+	 *
+	 * @param StackTrace - Output buffer for the stack trace string
+	 * @param StackTraceSize - Size of the output buffer
+	 * @param ContextWrapper - Context wrapper for cross-thread stack walking
+	 * @param CrashContext - The crash context
+	 * @param CrashedThreadHandle - Handle to the crashed thread
+	 */
+	void PerformStackWalk(ANSICHAR* StackTrace, SIZE_T StackTraceSize, void* ContextWrapper, const sentry_ucontext_t* CrashContext, HANDLE CrashedThreadHandle);
+
 private:
 	/**
 	 * Thread procedure that waits for crash events and performs logging.

plugin-dev/Source/Sentry/Private/Microsoft/MicrosoftSentrySubsystem.cpp

@@ -4,23 +4,41 @@
 
 #if USE_SENTRY_NATIVE
 
-#include "Misc/Paths.h"
-
 #include "SentryDefines.h"
 #include "SentryModule.h"
 #include "SentrySettings.h"
 
+#include "Microsoft/MicrosoftSentryCrashLogger.h"
+
 #include "GenericPlatform/GenericPlatformSentryAttachment.h"
 
 #include "GenericPlatform/GenericPlatformOutputDevices.h"
 #include "Misc/EngineVersionComparison.h"
+#include "Misc/Paths.h"
+
+#include "Microsoft/AllowMicrosoftPlatformTypes.h"
 
 #if !UE_VERSION_OLDER_THAN(5, 2, 0)
 #include "GenericPlatform/GenericPlatformMisc.h"
 #endif
 
 void FMicrosoftSentrySubsystem::InitWithSettings(const USentrySettings* Settings, USentryBeforeSendHandler* BeforeSendHandler, USentryBeforeBreadcrumbHandler* BeforeBreadcrumbHandler, USentryBeforeLogHandler* BeforeLogHandler, USentryTraceSampler* TraceSampler)
 {
+	// Initialize crash logger if enabled
+	if (Settings->EnableOnCrashLogging)
+	{
+		CrashLogger = MakeUnique<FMicrosoftSentryCrashLogger>();
+		if (CrashLogger->IsThreadRunning())
+		{
+			UE_LOG(LogSentrySdk, Log, TEXT("Crash logging enabled - stack traces will be written to game log during crashes"));
+		}
+		else
+		{
+			UE_LOG(LogSentrySdk, Warning, TEXT("Crash logging requested but thread failed to initialize"));
+			CrashLogger.Reset();
+		}
+	}
+
 	FGenericPlatformSentrySubsystem::InitWithSettings(Settings, BeforeSendHandler, BeforeBreadcrumbHandler, BeforeLogHandler, TraceSampler);
 
 #if !UE_VERSION_OLDER_THAN(5, 2, 0)
@@ -84,4 +102,47 @@ void FMicrosoftSentrySubsystem::AddByteAttachment(TSharedPtr<ISentryAttachment>
 	attachments.Add(platformAttachment);
 }
 
+sentry_value_t FMicrosoftSentrySubsystem::OnCrash(const sentry_ucontext_t* uctx, sentry_value_t event, void* closure)
+{
+	// If crash logging is enabled, log the crash callstack to game log
+	if (CrashLogger)
+	{
+		// Get a pseudo-handle to the current thread (the crashed thread)
+		// We need a real handle for cross-thread stack walking
+		HANDLE CurrentThreadPseudoHandle = GetCurrentThread();
+		HANDLE CrashedThreadHandle = nullptr;
+
+		// Duplicate the pseudo-handle to get a real handle
+		if (DuplicateHandle(
+				GetCurrentProcess(),	   // Source process
+				CurrentThreadPseudoHandle, // Source handle (pseudo)
+				GetCurrentProcess(),	   // Target process
+				&CrashedThreadHandle,	   // Target handle (real)
+				0,						   // Desired access (ignored when using DUPLICATE_SAME_ACCESS)
+				FALSE,					   // Inherit handle
+				DUPLICATE_SAME_ACCESS	   // Options
+				))
+		{
+			// Log the crash (with timeout to prevent hanging)
+			// This waits for the logging thread to complete stack walking, fill GErrorHist and dump callstack to logs
+			// Logging thread is responsible for closing CrashedThreadHandle when done
+			CrashLogger->LogCrash(uctx, CrashedThreadHandle, 5000);
+		}
+	}
+
+	return FGenericPlatformSentrySubsystem::OnCrash(uctx, event, closure);
+}
+
+void FMicrosoftSentrySubsystem::Close()
+{
+	if (CrashLogger)
+	{
+		CrashLogger.Reset();
+	}
+
+	FGenericPlatformSentrySubsystem::Close();
+}
+
+#include "Microsoft/HideMicrosoftPlatformTypes.h"
+
 #endif // USE_SENTRY_NATIVE