PLEASE VISIT OUR UPDATED UNREAL SUPPORT PAGE AT https://support.backtrace.io/hc/en-us/articles/360040106172-Unreal-Integration-Guide
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.
Windows: Use the Configuration File Edits or Plugin method described in this guide.
iOS Users: Use backtrace-cocoa
macOS Users: Use PLCrashReporter
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
It only takes a few minutes to integrate your application into Backtrace if you want to utilize the Unreal Engine crash reporter.
Configuration File Edits
The Configuration File mechanism is the the recommended integration method for Unreal applications. 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.
UE4 Editor Plugin
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.
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:
Your submission token is accessible under your project configuration menu (see here) and will look like this:
Integration - Via Configuration File Edit
Step 1 - Update your configuration
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 - UserEngine.ini
Within your project directory, within the Config folder, you should see a configuration file called
DefaultEngine.ini . Make a copy of this file to
%userprofile%\Documents\Unreal Engine\Engine\Config\UserEngine.ini. Note that you're changing the name of the file, and that these parent folders may not already exist - create them if needed.
UserEngine.ini, add the following section:
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
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:
Unreal 4.25 and earlier -
Unreal 4.26 and newer -
[CrashReportClient] section the same as in the UserEngine.ini section above.
Step 2: 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.
You're done. Head on to the product guide to learn more about the features of the product.
Integration - Via Plugin
An early access plugin is available for Unreal Editor 4 on Windows 7 through Windows 10. The plugin is available via the Unreal Marketplace.
Windows 7 through 10 on x86
Unreal Engine 4.16 - 4.24 (4.25 and 4.26 coming soon)
Visual Studio Community 2017 or better
A Backtrace instance (sign up here)
The plugin may work on older versions of Unreal, but has not been tested extensively on them.
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.
Step 1. Download Copy the plugin into your project.
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:
If your project is already open in Unreal Editor, restart it so it detects the plugin.
Step 2. Regenerate the Visual Studio Files.
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. Learn how to generate a Visual Studio project file here.
Step 3. Configure crash reporting.
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.
The next time your game crashes, you'll see the crashes appear in your instance!
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
AttributeDescriptionMachineID 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.
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.
What about on-premise?
For on-premise installations, please contact
email@example.com 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?
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.
How can I troubleshoot failures in crash reporting?
Please refer to your crash reporting client logs. You will also want to ensure
\Engine\Programs\CrashReportClient\DefaultEngine.ini (for crashes in packaged builds) and
%USERPROFILE%\Documents\Unreal Engine\Engine\Config\UserEngine.ini (for crashes within the editor) have the correct settings.
When creating cooked builds (see Content Cooking), the contents of Engine/Programs/CrashReportClient/Config/DefaultEngine.ini from Unreal's base directory is getting included as Engine/Programs/CrashReportClient/Config/DefaultEngine.ini under 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
If you are still running into issues, please contact support through the embedded support chat or e-mail firstname.lastname@example.org.