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 support@backtrace.io and your requests will be expedited to the engineering team.

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.

Configuration File

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:

https://<your organization>.sp.backtrace.io

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

45e44f361045ae4343e4113e77e0ea3eee1043367342c3f03c3a273cb3e433ae
Step 2: Update your configuration file

Inside of your project directory, update the Config\DefaultEngine.ini configuration file to point to your Backtrace instance for Unreal crash reporting purposes.

For example, assuming your Backtrace instance is:

https://AAAA.sp.backtrace.io

And that your submission token is:

45e44f361045ae4343e4113e77e0ea3eee1043367342c3f03c3a273cb3e433ae

Then add or edit the [CrashReportClient] section of DefaultEngine.ini 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:

https://AAAA.sp.backtrace.io

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

Bundle the crash reporter

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!

You're done. Head on to the product guide to learn more about the features of the product.

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.

Requirements

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

Functionality
Installation
Step 1. Download Copy the plugin into your project.

You are able to download the latest version of the plugin from: https://get.backtrace.io/unreal/builds/.

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

Copy the directory

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.

Configure the plugin

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.

Configure the plugin

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

Bundle the crash reporter

You're done!

The next time your game crashes, you'll see the crashes appear in your instance!

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 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.
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
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.

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 integration guide for minidump.

FAQ

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?

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 <Project>\Config\DefaultEngine.ini, %USERPROFILE%\Documents\Unreal Engine\Engine\Config\UserEngine.ini (for editor builds) and <GameBinary>\Engine\Programs\CrashReportClient\DefaultEngine.ini (for packaged builds) have the correct settings. If you are still running into issues, please contact support through the embedded support chat or e-mail support@backtrace.io.