Unreal Engine 4
This guide will show you how to integrate your Unreal application or game into the Backtrace platform for the purposes of crash reporting. This is covered in the integrated wizard of the product but a reference exists for folks requiring additional customization or an external reference.
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.
Please note this feature is still in early access. If you run into any issues, please contact firstname.lastname@example.org and your requests will be expedited to the engineering team.
It only takes a few minutes to integrate your application into Backtrace if you are wanting to utilize the Unreal engine crash reporter. The Configuration File mechanism is the currently the recommended integration method for Unreal applications.
An early access plugin is also available that will automate the configuration file updates as well as symbol uploads.
Step 1: Register for a Backtrace account
If you have not done so already, register for a Backtrace account at https://backtrace.io/create. 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 and will look like this:
Step 2: Update your configuration file
Inside of your project directory, update the
file to point to your Backtrace instance for Unreal crash reporting purposes.
For example, assuming your Backtrace instance is:
And that your submission token is:
Then add or edit the
[CrashReportClient] section of
to contain the following:
[CrashReportClient] CrashReportClientVersion=1.0 DataRouterUrl="https://unreal.backtrace.io/post/AAAA/45e44f361045ae4343e4113e77e0ea3eee1043367342c3f03c3a273cb3e433ae"
Your application now automatically routes all crashes to your Backtrace instance if your users agree to submit crash dumps! You are able to see crashes by logging into your instance at:
Step 3: Upload Symbols
You must now ensure your build environment has been configured to generate debug symbols. These symbols can be uploaded to your Backtrace instance manually or directly by your build system. With debug symbols, deduplication accuracy is improved and you are able to view accurate callstacks directly with your web browser. To learn more about symbolification, please see the symbolification 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.
An early access plugin is available for Unreal Editor 4 on Windows 7 through Windows 10. The plugin will eventually be made available directly through the Unreal marketplace.
- Windows 7 through 10 on x86
- Unreal Engine 4.16 or newer
- Visual Studio Community 2017 or better
The plugin may work on older versions of Unreal, but has not been tested extensively.
Step 1. Download Copy the plugin into your project.
You are able to download the latest version of the plugin from:
https://backtrace.io/download/BacktraceIntegration.zip. The SHA256 checksum is
Unzip the file and then copy the
BacktraceIntegration folder to the
folder within your project folder. The directory structure should look like
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.
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.
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 here.
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.|
|--||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.|
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|
|CrashGuid||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||An 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 integration guide for minidump.
What about on-premise?
For on-premise installations, please contact
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 are able to add your own properties to the crash for indexing as
AddCrashProperty(const TCHAR* PropertyName, const TCHAR* PropertyValue ) as declared
After adding the property, make sure to visit your project
configuration attributes page so that they are indexed. If you don't wish
to issue aggregations or filters on the property, then you are done! Individual
crash reports, by default, will include all crash properties. You are able to
view them in the
Annotations pane in the web debugger.
Further modifications are possible with a source build of the engine.
How can I troubleshoot failures in crash reporting?
Please refer to your crash reporting client logs. You will also
want to ensure
<User Profile>/Documents/Unreal Engine/Engine/Config/UserEngine.ini
have the correct settings. If you are still running into issues, please
contact support through the embedded support chat or e-mail