Setup Crash Reporter Client

Installation of a Sentry SDK is not required in order to capture the crashes of your UE4 application or game. Sentry supports the UE4 Crash Reporter.

To integrate your UE4 game or application with Sentry, the following steps are required:

1. Include the UE4 Crash Reporter to 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.

UE4 Crash reporter

The UE4 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:

Include the UE4 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 Sentry, crash reports are required to include debug information. 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 include debug information and also, symbols need to be uploaded to Sentry.

Include Debug Information

The option is also located under Project > Packaging menu, then select show advanced followed by checking the box for: Include Debug Files.

Configure the Crash Reporter Endpoint

Now that the Crash Reporter and Debug Files are included, UE4 needs to know where to send the crash. For that, we add the Sentry Unreal Engine Endpoint from the Client Keys settings page to game's configuration file. This will include which project within Sentry you want to see the crashes arriving in real time. That's accomplished by configuring the CrashReportClient in the DefaultEngine.ini file. Changing the engine is necessary for 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 limits on the size of UE4 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

For tips on troubleshooting the UE4 Crash Reporter, check out this thread in Sentry's forum where community members have delved into potential solutions.