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.
Android and Linux Users: Unreal crash reporting on these platforms is currently unsupported, due to the fact that the Unreal engine doesn't generate adequate information in these environments. As an alternative, you can integrate via our Breakpad integration.
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.
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:
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.
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.
UserEngine.ini - For crashes in the Editor
Within your project directory, within the Config folder, you should see a configuration file called
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 - go ahead and create them if needed.
Within this UserEngine.ini, add the following section:
Replacing <instance> and <token>. For example, assuming your Backtrace instance is:
And that your submission token is:
Then your section would look like:
Once this is set, when you 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 at:
DefaultEngine.ini - For crashes in packaged builds
To configure the crash reporter for packaged builds, follow the steps above in the UserEngine.ini section, but instead copy the DefaultEngine.ini file to
<built_exe_location>\Engine\Programs\CrashReportClient\DefaultEngine.ini - Note here that we're keeping the original name of DefaultEngine.ini instead of renaming it.
[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. 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 in the Product 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 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
- 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:
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 PropertyBacktrace 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. -- 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 PropertyRecommended Column TypeDescriptionCrashGuid 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 compiled language and application integration guides for more advanced integrations.
What about on-premise?
For on-premise installations, please contact
firstname.lastname@example.org 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 are able to add your own properties to the crash for indexing as attributes by using
AddCrashProperty(const TCHAR* PropertyName, const TCHAR* PropertyValue ) as declared in
Engine/Source/Runtime/Core/Public/GenericPlatform/GenericPlatformCrashContext.h. 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
<built_exe_location>\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 <Game Name>/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 email@example.com.