This guide will show you how to integrate your Unreal application or game into the Backtrace platform for the purposes of crash reporting.

Backtrace has first-class support for the native crash reporting format of the Unreal Engine. It will automatically extract all metadata attributes so you are able to query against them (from graphics card to game version) and will include file attachments such as game logs, the original report XML file (with user input) and more. The basic integration consists of modifying a configuration file setting, or using our UE4 Editor Plugin to automate the configuration when building/compiling the game from the Editor. 

Supported Platforms

• Unreal Engine: 4.16 - 5.0

• Windows: Using the native CrashReporter by editing the configuration files (recommended) or the plugin method described in this guide.
• iOS Users: see iOS - backtrace-cocoa library.
• Android: see Android - backtrace-android library.
• macOS Users: Use PLCrashReporter. No Unreal specific instructions available at this point.
• Linux Users: Use crashpad.
• Game Consoles (PS4, PS5, Xbox One, Series X | S, Nintendo Switch): Use Backtrace's Game Console Integrations
• On Premise (self hosted) Users: Unreal crash ingestion requires specific packages. Please reach out to support for details and instructions. 

How to Integrate

Register for a Backtrace account

If you have not done so already, register for a Backtrace account here. You are provided a dedicated tenant with a sub-domain along with a token for which to submit crashes to.

Your server instance will have a domain in the following form:

https://<AAAA>.sp.backtrace.io


Your submission token is accessible under your project configuration menu (see here) and will look like this:

45e44f361045ae4343e4113e77e0ea3eee1043367342c3f03c3a273cb3e433ae

It only takes a few minutes to integrate your application into Backtrace if you want to utilize the Unreal Engine crash reporter.

Windows - Configuration File Edits (recommended)

The Configuration File mechanism is the the recommended integration method for Unreal applications running on Windows. It allows you flexibility by manually editing the UE4 configuration files responsible for routing crash reports to a crash reporting server like Backtrace. This method is supported for all versions of UE4.

First, make sure you have enabled crash reporting in your project settings. Go to Project > Packaging and check the Include Crash Report checkbox.

NOTE: if you're building from the command line, this flag won't be enough for you, and you should also add the -crashreporter flag when building.

Next, there are two configuration files you need to update.  One of these configures the crash reporter for when your game is run within the Unreal Editor.  The other takes effect in packaged builds of your game.

For crashes in the Editor

Note: the Unreal Engine location (referred to as [UNREAL_ENGINE] in this guide) by default is %USERPROFILE%\Unreal Engine but it can also be found at these locations:

• %USERPROFILE%\Documents\Unreal Engine
•  C:\Program Files\Epic Games\UE_[ENGINE_VERSION]\ 

In order to have crashes be sent to Backtrace when the game crashes in-editor:

1. Within your project directory, within the [UNREAL_ENGINE]\Config\ folder, you should see a configuration file called DefaultEngine.ini.
2. Make a copy of this file to the [UNREAL_ENGINE]\Engine\Config\ folder (note, these parent folders may not already exist - create them if needed)
3. Rename to UserEngine.ini

Within this UserEngine.ini, add the following section:

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/<universe>/<token>"

For example, assuming your Backtrace instance is: https://AAAA.sp.backtrace.ioand that your submission token is 0123456789abcdef, then your section would look like:

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/AAAA/0123456789abcdef"

Once this is set, when your game crashes in the Unreal Editor, you should see the crash reporting dialog and have it send a crash report to your Backtrace instance. You are able to see crashes by logging into your instance.

On Premise (self hosted) Users: Your DataRouterUrl value will differ. Please reach out to support for details and instructions. 

For crashes in packaged builds - DefaultEngine.ini  (UE4 4.16-UE5 Early Access)

Option A - global default for all builds

It's possible to override the configuration for ALL BUILDS on your device (this is useful in CICD environments), follow the steps in the previous section, but instead copy the DefaultEngine.ini file to the following directory:

• [UNREAL_ENGINE]\UnrealEngine\Engine\Programs\CrashReportClient\Config
  • Note that default for this is%USERPROFILE%\Unreal Engine but it can be under %USERPROFILE%\Documents\Unreal Engine or C:\Program Files\Epic Games\UE_[ENGINE_VERSION].

Add the [CrashReportClient] section the same as in the UserEngine.ini section above.

Option B - override in the packaged build

To configure the crash reporter for packaged builds, follow the steps in the previous section, but instead copy the DefaultEngine.ini file to the following directory:

• Unreal 4.25 and earlier
  • [BUILD_DIR]\WindowsNoEditor\Engine\Programs\CrashReportClient\Config\NoRedist 
  • Create any subdirectories that do not exist yet.
• Unreal 4.26 and newer
  • [BUILD_DIR]\WindowsNoEditor\Engine\Restricted\NoRedist\Programs\CrashReportClient\Config
  • Create any subdirectories that do not exist yet.

Add the [CrashReportClient] section the same as in the UserEngine.ini section above.

Upload Symbols

You must now ensure your build environment has been configured to generate debug symbols. The Plugin will offer the option to have the Editor upload Symbol files to Backtrace. Alternatively, you need to make sure your build system generates debug symbols which can then be uploaded to your Backtrace instance, a connected Symbol Server, an Amazon S3 or Google Cloud Bucket. To learn more, please see the Symbolication Guide. You are able to do this in the editor or directly in Visual Studio.

Android - backtrace-android library

1. Find your game's Build.cs
2. Place BacktraceAndroid_UPL.xml in the same directory as your game's Build.cs. Replace the BacktraceCredentials, according to the instructions in the Android Integration guide.
3. Add these lines to your game's Build.cs, at the end of your game's ModuleRules class constructor:

   • • if (Target.Platform == UnrealTargetPlatform.Android) 
       {
       	string PluginPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
       	AdditionalPropertiesForReceipt.Add("AndroidPlugin", System.IO.Path.Combine(PluginPath, "BacktraceAndroid_UPL.xml"));
       }

4. Include BacktraceWrapper.h in your GameInstance.
5. Use BacktraceIO::FInitializeBacktraceClient to start the Backtrace client. We suggest to start this from your game's GameInstance::OnStart() method, however, you might not have this method, and you can start the client in any method you use during your game instantiation process. You can optionally specify custom attributes and file attachment paths to submit with your backtrace reports.
   • NOTE: File attachment paths must be given as the Android paths. For example to specify a file attachment path in your ProjectSavedDir(), you would use the below:

   #include "Misc/App.h"
   #if PLATFORM_ANDROID
   extern FString GFilePathBase;
   FString FileAttachmentPath = GFilePathBase + FString("/UE4Game/") + FApp::GetName() + TEXT("/") + FApp::GetName() + TEXT("/Saved") + TEXT("MyFileName.txt");
   #endif

   It is not always straightforward to convert UE4 paths to Android paths due to UE4 reflection, and Epic makes their Android to UE4 file path conversion functions private. See FAndroidPlatformFile::PathToAndroidPaths from AndroidPlatformFile.cpp

You now have the power of backtrace-android in your Unreal Engine game for better crash reporting and monitoring!

Please see the documentation here, and other links to Backtrace Android documentation for more information. You can change the Backtrace client settings by tweaking the BacktraceAndroid_UPL.xml.

iOS - backtrace-cocoa library

Note! These code examples are tested and work for Unreal 4.26. For other versions, some changes might have to be made.

1. Under Assets, download and extract the Backtrace_PLCrashReporter.framework.zip and Backtrace.framework.zip files. 
2. Copy and paste the Backtrace_PLCrashReporter.framework and Backtrace.framework folders into your game project.
3. Find your game's Build.cs.
4. Add these lines to your game's Build.cs, at the end of your game's ModuleRules class constructor. Make sure to reflect the path to where you've placed both frameworks within your game project.

   • • if (Target.Platform == UnrealTargetPlatform.IOS)
       {
         PublicAdditionalFrameworks.AddRange(
           new Framework[] 
           {
             new Framework("Backtrace", "/Library/Frameworks/Backtrace.framework", "", true),
             new Framework("Backtrace_PLCrashReporter", "/Library/Frameworks/Backtrace_PLCrashReporter.framework", "", true)
           }
         );
       }
       
       

5. Include initialization logic in your game, importing Backtrace-Swift.h (from Backtrace.framework/Headers). For example (minimal usage):

   • #if PLATFORM_IOS
     #import <Backtrace/Backtrace-Swift.h>
     #endif
     
     void UYourGameInstanceBase::OnStart()
     {
     #if PLATFORM_IOS
     
       BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                          initWithSubmissionUrl: [NSURL URLWithString: @"https://submit.backtrace.io/{universe}/{token}/plcrash"]];
       BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                                      initWithCredentials: credentials
                                                      dbSettings: [[BacktraceDatabaseSettings alloc] init] 
                                                      reportsPerMin: 3 
                                                      allowsAttachingDebugger: NO
                                                      detectOOM: TRUE]; 
       BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];
     #endif
     }

You now have the power of backtrace-cocoa in your Unreal Engine game for better crash reporting and monitoring!

For more information, see the full Backtrace cocoa documentation here.

Windows - UE4 Editor Plugin (alternative integration method; up to UE 4.24)

A plugin is also available on the Unreal Marketplace that will automate the configuration file updates as well as symbol uploads. This plugin currently supports up to UE 4.24, with plans to add support for newer versions of UE4 Editor in Q2 2021.

Requirements 

• Windows 7 through 10 on x86
• Unreal Engine 4.16 - 4.24 (4.25, 4.26 & UE5 coming in Q3 2021)
• Visual Studio Community 2017 or up
• A Backtrace instance (sign up here)

The plugin may work on older versions of Unreal, but has not been tested extensively on them.

Functionality

• The plugin will update your .ini files to forward crashes to your Backtrace account.
• The plugin will allow you to configure automated symbol upload. This way you don't have to manually upload symbol files. If you are using your own build system or distributed builds, this does not apply to you and you are better off using the .ini configuration method.

Plugin Installation

You are able to download the latest version of the plugin from the Unreal Marketplace.

Unzip the file and then copy the BacktraceIntegration folder to the Plugins folder within your project folder. The directory structure should look like this: PROJ\my_game.uproject
PROJ\Plugins\BacktraceIntegration\BacktraceIntegration.uplugin


If your project is already open in Unreal Editor, restart it so it detects the plugin.

Right click on your project file and regenerate the Visual Studio files. The plugin will integrate into your build process to automatically upload symbols if you desire.

If you are in a blueprint-only project, you are still required to generate Visual Studio project files. For more information, see Generate Visual Studio Project in the Unreal Community.

At this point, you have completed integration of the plugin. Open the Backtrace plugin and follow the wizard to get started. Follow all the prompts and ensure all the correct information is supplied.

Make sure you have enabled crash reporting in your project settings. Go to Project > Packaging and check the Include Crash Report checkbox.

NOTE: if you're building from the command line, this flag won't be enough for you, and you should also add the -crashreporter flag when building.

Features

Attributes

The Unreal Engine crash reporting infrastructure is able to extract all attributes and metadata that have been submitted as part of the crash report. This allows you to filter, aggregate and facet this data using the Backtrace Query Builder.

Several attributes are mapped to built-in attributes in the Backtrace system. All other attributes are passed through. If you would like to filter, aggregate or facet on this data then you can create attributes corresponding to the attributes specified in the crash report XML file. For example, if you wanted an attribute on GameName, then you can create a Backtrace attribute for it called GameName. Learn more about attributes in the product guide.

Below are the default attributes that are created for your application. The first column is the native property name in Unreal Engine, the second column is the attribute stored in Backtrace and the last column is the description. If an attribute is missing then you are able to create it after the fact and reprocess the objects in the project configuration page.

Unreal Property Backtrace Attribute Description
--------------------------------------------------------------------
MachineID guid A unique identifier to a machine.
SecondsSinceStart process.age The number of seconds the application has been running.
ErrorMessage error.message An additional error message.
MemoryStats.UsedPhysical vm.rss.size Resident memory usage.
MemoryStats.PeakUsedPhysical vm.rss.peak Peak resident memory usage. MemoryStats.UsedVirtual vm.vma.size Virtual memory usage.
MemoryStats.PeakUsedVirtual vm.vma.peak Peak virtual memory usage. MemoryStats.TotalPhysical vm.rss.available Available physical memory.
MemoryStats.TotalVirtual vm.vma.available Available virtual memory.
 
Backtrace Attribute Description
--------------------------------------------------------------------
application The name of the crashing object.
callstack The crashing callstack.
classifiers The minidump exception codes.
cpu.count The count of processors on the system.
fault.address The memory address being accessed at the time of crash.  
fingerprint A callstack fingerprint for deduplication purposes.
hostname The hostname of the crashing system.
uname.machine The processor architecture.
uname.sysname The operating system name.
uname.version The version of the operating system. and more   

Below is a list other common attributes you can add yourself and Backtrace will automatically index them for you. If you add your own properties, you will be able to create attributes for them for indexing purposes.

Unreal Property Recommended Column Type Description
DescriptionCrashGuid dictionary A GUID associated with the crash report.
ProcessId uint64 The process identifier.
IsInternalBuild bitmap Boolean whether the crash was from an internal engine build.

IsPerforceBuild bitmap Boolean whether the crash was from an internal engine build.

IsEnsure bitmap Boolean whether the crash was an Ensure failure.
IsAssert bitmap Boolean whether the crash was an assert failure.
GameName dictionary The name of the Unreal game.
ExecutableName dictionary The name of the executable file of the game.

CrashDumpMode uint8 Marks whether the crash dump is a full or partial dump.

UserActivityHint dictionary A string representing the user activity, if known, when the error occurred. bAllowToBeContacted bitmap Indicates whether the user is fine being contacted about the error. 

See CrashDescription.h for many more...   

Individual crash reports, by default, will include all crash properties. You are able to view them in the Annotations pane in the web debugger.

Advanced Integrations

If you require additional customization of crash reporting, including custom dialogs, more customized file attachments or platforms unsupported by the native unreal crash reporter, please refer to the compiled language and application integration guides for more advanced integrations.

Troubleshooting

What about on-premise?

For on-premise installations, please contact support@backtrace.io for additional information. It is possible to configure custom domain mappings in the Backtrace Unreal crash reporting servers.

How do I add custom crash properties?

Right now, the attributes need to be added for individual platforms.

Windows and Linux

You can add custom attributes using the Unreal API FGenericCrashContext::SetGameData

static void SetGameData
(
    const FString & Key,
    const FString & Value
)

Using this API will add custom properties to the crashContext-runtime.xml which Backtrace will parse. After adding the property, make sure to visit your project configuration attributes page so that they are indexed. 

Android

Add the following code to your initialization:

TMap<FString, FString> BacktraceAttributes;
BacktraceAttributes.Add("key", "value");

BacktraceIO::FInitializeBacktraceClient(BacktraceAttributes, Attachments);

iOS

See here for example code in Swift and ObjectiveC to add custom attributes.

BacktraceClient.shared?.attributes = ["key": "value", "testing": true]

My Android Assert (Check/Ensure/Verify) crashes are not showing up in Backtrace for my debug builds

Backtrace currently doesn't handle the Assert crashes typically associated with Debug builds on Android. This is not a problem in Release builds, where these types of conditions tend to be  compiled out. See here for more information on Asserts.

How can I troubleshoot failures in crash reporting?

Please refer to your crash reporting client logs. You will also want to ensure DefaultEngine.ini  (for crashes in packaged builds) and [ENGINE_DIR]\Engine\Config\UserEngine.ini (for crashes within the editor) have the correct settings. 

When creating cooked builds (see Content Cooking), the contents of [ENGINE_DIR]\Engine\Programs\CrashReportClient\Config\DefaultEngine.ini is getting included as Engine\Programs\CrashReportClient\Config\DefaultEngine.ini the cooked build's path. 

Even though the CrashReportClient.ini files generated under /Saved have the Backtrace URL, it appears to be using the file from thew Unreal Base directory.

Replacing that file's content with our Backtrace version causes the reporter to work as expected. So it looks like cooked builds might require an engine change instead of just a project ini change

You may use networking tools like tcpdump or FiddlerAnywhere to check the CrashReporter is submitting to the correct host.
If you are still running into issues, please contact support through the embedded support chat or e-mail support@backtrace.io.