| title | description |
|---|---|
Crash Reporter Client |
Learn about Sentry's Unreal Engine integration with Crash Reporter Client. |
Installation of a Sentry SDK is not required in order to capture the crashes of your Unreal Engine application or game, because Sentry supports the UE Crash Reporter.
To integrate your UE game or application with Sentry, the following steps are required:
- Include the UE Crash Reporter in your game or application.
- Include Debug information in the crash reports.
- Add the Unreal Engine Endpoint to the relevant configuration file.
- Upload your games' symbols so Sentry can display function names and line numbers.
- Optionally, enable Event Attachments for your Sentry project.
Below we'll break down each step in detail.
The UE Crash Reporter is provided out of the box by Epic Games. It is able to collect relevant information about the crash and send it to a service like Sentry to process.
Adding it to your game means that in case a crash happens, the following dialog is displayed to the user:
The UE Crash Reporter works if the Sentry SDK is installed. Sentry SDK can help with configuring the UE Crash Reporter, uploading debug symbols, and enriching crash reports with custom data. Starting from UE 5.2 users have to choose between the two available crash capturing mechanisms - the UE Crash Reporter or the sentry-native library that's integrated into the Sentry plugin. By default, the sentry-native library is used instead of the UE Crash Reporter. (See "Enable automatic crash capturing (Windows, UE 5.2+)" in the plugin settings.) The two solutions are mutually exclusive and can't be used simultaneously.
Sentry SDK can integrate with the UE Crash Reporter, but it also offers additional features beyond those provided by the built-in tool. The table below outlines the key feature differences:
| Feature | Sentry SDK | Crash Reporter |
|---|---|---|
| Supported engine versions | All UE 5 and UE 4.27 | Built-in engine tool |
| Supported platforms | Desktop, mobile, consoles | Desktop |
| Crash capturing * | Supported ** | Supported |
| Additonal event context | Supported | Supported |
| Automatic breadcrumbs | Supported | Not supported |
| Screenshot attachment | Supported *** | Not supported |
| Crash events filtering | Supported | Not supported |
| Release health monitoring | Supported | Not supported |
| Performance insights | Supported | Not supported |
Legend:
*: On Windows, the underlying crash capturing mechanisms used in the Sentry SDK and the UE Crash Reporter are mutually exclusive.
**: On Windows, crash capturing is supported out of the box starting from UE 5.2.
***: Currently this feature is supported only on Windows/Linux.
Adding event context (e.g., tags, custom breadcrumbs, or user information) can always be done through the unified Sentry SDK interface. While only one crash-capturing mechanism can be active at a time, both solutions can be used together for context enrichment, helping to improve the debugging process.
Features like crash events filtering, screenshot attachment and release health monitoring require the Sentry SDK to be enabled for crash capturing to work properly.
You can add the Crash Reporter Client to your game in your Project Settings.
The simplest way is to search the option: Crash Reporter:
The option is located under Project > Packaging menu, then select show advanced followed by
checking the box for: Include Crash Reporter.
Now that the Crash Reporter is included, UE needs to know where to send the
crash. For that, we need to add the Sentry Unreal Engine Endpoint from the Client Keys settings page to the game's configuration file. This will include whichever project within Sentry you want to see real-time crashes for. That's accomplished by configuring the CrashReportClient in the DefaultEngine.ini file. You'll need to change the engine to do this to work.
Edit the file:
engine-dir\Engine\Programs\CrashReportClient\Config\DefaultEngine.ini
Add the configuration section:
[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="___UNREAL_URL___"If a [CrashReportClient] section already exists, simply changing the value of DataRouterUrl
is enough.
Alternatively, the endpoint can be added automatically to the DefaultEngine.ini file by using the Sentry configuration window.
Navigate to the editor's menu Project Settings > Plugins > Sentry, set the Sentry Unreal Engine Endpoint in the corresponding input field, and click the Update global settings button to apply changes. The default endpoint value can be restored by clicking the Reset button once the Crash Reporter is no longer needed.
Basic attributes can be reconfigured by providing special game data to the
crash reporter. Do this by setting the __sentry game data key to a JSON value containing
Sentry specific attributes:
#include "GenericPlatform/GenericPlatformCrashContext.h"
#include "Dom/Json.h"
void ConfigureCrashReporter()
{
TSharedPtr<FJsonObject> config = MakeShareable(new FJsonObject);
// sentry specific attributes go here
config->SetStringField("release", "[email protected]");
config->SetStringField("environment", "production");
TSharedPtr<FJsonObject> tags = MakeShareable(new FJsonObject);
tags->SetStringField("tag1", "value1");
tags->SetStringField("tag2", "value2");
config->SetObjectField("tags", tags);
TSharedPtr<FJsonObject> user = MakeShareable(new FJsonObject);
user->SetStringField("ip_address", "{{auto}}");
user->SetStringField("email", "[email protected]");
config->SetObjectField("user", user);
TSharedPtr<FJsonObject> character = MakeShareable(new FJsonObject);
character->SetStringField("name", "Mighty Fighter");
character->SetNumberField("age", 19.0);
TSharedPtr<FJsonObject> contexts = MakeShareable(new FJsonObject);
contexts->SetObjectField("character", character);
config->SetObjectField("contexts", contexts);
FString jsonConfig;
TSharedRef<TJsonWriter<>> jsonWriter = TJsonWriterFactory<>::Create(&jsonConfig);
FJsonSerializer::Serialize(config.ToSharedRef(), jsonWriter);
FGenericCrashContext::SetGameData(TEXT("__sentry"), jsonConfig);
}You need to call the ConfigureCrashReporter some time after your game
starts. Any event attribute can be set.
You should configure Crash Reporter attributes before initializing the Sentry SDK. Otherwise, some information may get overwritten and lost.
The Sentry SDK provides an API which allows you to set Crash Reporter attributes as well.
Depending on the version of Unreal Engine you are using, you may have to
add JSON support to the build script (MyProject.build.cs):
PublicDependencyModuleNames.AddRange(new string[] { ..., "Json" });To allow Sentry to fully process native crashes and provide you with symbolicated stack traces, you need to upload Debug Information Files (sometimes also referred to as Debug Symbols or just Symbols). We recommend uploading debug information during your build or release process.
The Sentry SDK can handle uploading debug symbols automatically at build time.
For all libraries where you'd like to receive symbolication, you need to provide debug information. This includes dependencies and operating system libraries.
In addition to Debug Information Files, Sentry needs Call Frame Information (CFI) to extract accurate stack traces from minidumps of optimized release builds. CFI is usually part of the executables and not copied to debug symbols. Unless you are uploading Breakpad symbols, be sure to also include the binaries when uploading files to Sentry.
For more information on uploading debug information and their supported formats, see Debug Information Files.
Event ingestion imposes size limits on UE crash reports. These limits are subject to future change and defined currently as:
- 20MB for a compressed request
- 100MB for the full crash report after decompression
Check out this community-generated thread in Sentry's forum for UE Crash Reporter troubleshooting tips and solutions.
☝ This feature is supported on Windows, Linux, and Android.