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:

1. Include the UE Crash Reporter in your game or application.
2. Include Debug information in the crash reports.
3. Add the Unreal Engine Endpoint to the relevant configuration file.
4. Upload your games' symbols so Sentry can display function names and line numbers.
5. Optionally, enable Event Attachments for your Sentry project.

Below we'll break down each step in detail.

UE Crash Reporter

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:

Using the UE Crash Reporter on Windows

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.

Include the UE Crash Reporter

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.

Debug Information

To get the most out of captured crash reports debug symbols need to be uploaded to Sentry. In order for Sentry to be able to process the crash report and translate memory addresses to meaningful information like function names, module names and line numbers, the crash itself must be associated with the corresponding debug information first.

Configure the Crash Reporter Endpoint

Now that the Crash Reporter and Debug Files are 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="https://o0.ingest.sentry.io/api/0/unreal/examplePublicKey/"

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.

Configure the Crash Reporter Attributes

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", "my-project-name@2.3.12");
    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", "jane.doe@example.com");
    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.

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" });

Upload Debug Symbols

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.

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.

Size Limits

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

Issues With the Crash Reporter

Check out this community-generated thread in Sentry's forum for UE Crash Reporter troubleshooting tips and solutions.