Backtrace's integration with Unity allows developers to capture and report log errors, handled and unhandled Unity exceptions, and native crashes to their Backtrace instance, instantly offering the ability to prioritize and debug software errors.
Download the backtrace-unity library from our GitHub location here or install it via OpenUPM.
Feature Summary
- Lightweight library that quickly submits log errors, handled and unhandled exceptions, and native crashes to Backtrace
- Supports wide range of Unity versions (2017.4+) and deployments (iOS, Android, Windows, Mac, WebGL, PS4/5 Xbox One/S/X, Nintendo Switch, Stadia)
- Install via Universal Package Manager
- Collect detailed context
- Callstacks, including function names and line numbers where possible
- System metadata including device GUID, OS version, memory usage, process age
- Custom metadata including app version, scene info, device drivers
- Last # log lines, screenshots, log or config files, other attachments
- Android NDK Crashes; iOS Native Crashes, Windows Native Crashes
- Client-side features
- Client side filters and sampling controls
- Deduplication options and custom client side fingerprintins
- Offline crash capture/storage for future collection
- Customizable event handlers and base classes
- Performance statistics collection option for timing observability
- Unity IDE integration to configure Backtrace behaviors in your game.
Prerequisites
- Unity environment 2017+
- .NET 2.0/3.5/4.5/Standard 2.0 scripting runtime version
- Mono or IL2CPP scripting backend
Setup and Installation
- Install via OpenUPM or download the backtrace-unity zip file from our GitHub, unzip it, and keep the folder in a known location.
- Open your Unity project
- Use the Unity Package Manager to install backtrace-unity (Window -> Package Manager -> Add Package From Disk). The Unity editor will refresh and the Backtrace Plugin should become available in the editor.
Platforms Supported
Backtrace-unity has been tested and certified for games deployed on the following platforms:
- Mobile - Android, iOS
- PC - Windows, Mac
- Web - WebGL
- Game Consoles - PlayStation4, Xbox One, Nintendo Switch
There are some differences in capabilities that backtrace-unity provides based on the platform. Major capabilities are summarized as follows:
- All Platforms - Unhandled Exceptions, Handled Exceptions, Custom Indexable Metadata, File Attachments*, Last N Log Lines, Automatic attachment of Screenshots, Client Side Deduplication Rules*, Client Side Submission Filtering, Client Side Submission Limits, Performance Diagnostics, Offline Database*(Except Nintendo Switch)
- Android -Identified by attribute uname.sysname = Android; ANRs (Hangs), Native Process and Memory Information, Java Exception Handler (Plugins, Exported Game in Android Studio)
- iOS - Identified by attribute uname.sysname = IOS
- WebGL - Identified by attribute uname.sysname = WebGL. The attribute device.model is currently used to share the browser informatio.
- Switch - Identified by attribute uname.sysname = Switch. Note that the attribute GUID is regenerated with each Switch restart (It is not an accurate count of number of Users or Devices. It is a count of Switch Sessions). Note that the current release does no support Offline Database or related features.
- PlayStation4 - Identified by attribute uname.sysname = PS4
- Windows - Identified by attribute uname.sysname = Windows. Provides an option to capture Minidumps for Engine Crashes.
- MacOS - Identified by attribute uname.sysname = MacOS.
Note: Unity allows you to disable stack trace information in player properties. As a result backtrace-unity, the call stack and the log lines section will be empty.
Integrating into your Project
- Under the Assets Menu, there is now a Backtrace -> Configuration option. Choose that option to have a Backtrace Configuration is generated in the Assets folder.
- Next, select an object from the Scene Hierarchy to associate the Backtrace reporting client to. In the example below, we use the _Manager object., Using the Inspector panel, click the Add Component button and search for the Backtrace Client object.
- Within the Backtrace Client panel, there is a Backtrace Configuration field. Drag and drop the Backtrace Configuration from the Assets folder to that field. More fields will appear for you to fill in to configure the Backtrace Client and Offline Database options.
Watch this 1 minute silent video to see the Integration and Configuration in action. The first 20 seconds of the video shows the above Integrating steps, and the second part shows details of the below Client and Database Settings.
Note: Please review details for the Server Address and Token fields below.
Backtrace Client and Offline Database Settings
The following is a reference guide to the Backtrace Client fields:
- Server Address: This field is required to submit exceptions from your Unity project to your Backtrace instance. The Server Address to use for your instance is provided in the Web Console under Project Settings -> Integration Guides -> Unity.
NOTE: If Backtrace is hosting your instance, the Server Address will probably be based on https://submit.backtrace.io, and it will include your project name and submission token embedded in URL. Alternatively, you may see the Integration Guides provides a Server Address to .sp.backtrace.io:6098 . If this is the case, a separate Token field will also be provided. - Token: If your Server Address is https://submit.backtrace.io, then you do NOT need to enter a separate token here. If your Project Settings -> Integration Guides -> Unity page in the web console has a separate line for token, then copy that value here.
- Reports per minute: Limits the number of reports the client will send per minutes. If set to 0, there is no limit. If set to a higher value and the value is reached, the client will not send any reports until the next minute. Further, the BacktraceClient.Send/BacktraceClient.SendAsync method will return false.
- Capture unhandled exceptions: Toggle this on or off to set the library to handle unhandled exceptions that are not captured by try-catch blocks.
- Enable Database: When this setting is toggled, the backtrace-unity plugin will configure an offline database that will store reports if they can't be submitted do to being offline or not finding a network. When toggled on, there are a number of Database settings to configure.
- Backtrace Database path: This is the path to directory where the Backtrace database will store reports on your game. NOTE: Backtrace database will remove all existing files on database start
- Create database directory toggle: If toggled, the library will create the offline database directory if the provided path doesn't exists,
- Auto Send Mode: When toggled on, the database will send automatically reports to Backtrace server based on the Retry Settings below. When toggled off, the developer will need to use the Flush method to attempt to send and clear. Recommend that this is toggled on.
- Maximum number of records: This is one of two limits you can impose for controlling the growth of the offline store. This setting is the maximum number of stored reports in database. If value is equal to zero, then limit not exists, When the limit is reached, the database will remove the oldest entries.
- Maximum database size: This is the second limit you can impose for controlling the growth of the offline store. This setting is the maximum database size in MB. If value is equal to zero, then size is unlimited, When the limit is reached, the database will remove the oldest entries.
- Retry interval: If the database is unable to send its record, this setting specifies how many seconds the library should wait between retries.
- Maximum retries: If the database is unable to send its record, this setting specifies the maximum number of retries before the system gives up.
- Retry order: This specifies in which order records are sent to the Backtrace server.
Using in your C# code
You can further configure your game to submit crashes by making further changes in the C# code for your game. Include the following using statements to be able to use the library
using Backtrace.Unity;
using Backtrace.Unity.Model;
Configuring specific try-catch blocks
If you setup Backtrace client and Backtrace database configuration you can retrieve database and client instances by using GameObject. When you retrieve client instance you can start sending reports from try/catch block in your game! The BacktraceClient.Send method will send an error report to the Backtrace endpoint specified.
//Read from manager BacktraceClient instance
var backtraceClient = GameObject.Find("_Manager").GetComponent();
//Read from manager BacktraceClient instance
var database = GameObject.Find("_Manager").GetComponent();
try{
//throw exception here
}
catch(Exception exception){
var report = new BacktraceReport(exception);
backtraceClient.Send(report);
}
BacktraceReport Options
The BacktraceReport class represents a single error report. You can submit custom attributes using the attributes parameter, or attach files by supplying an array of file paths in the attachmentPaths parameter.
try
{
//throw exception here
}
catch (Exception exception)
{
var report = new BacktraceReport(
exception: exception,
attributes: new Dictionary<string, object>() { { "key", "value" } },
attachmentPaths: new List() { @"file_path_1", @"file_path_2" }
);
backtraceClient.Send(backtraceReport);
}
Notes:
- If you setup BacktraceClient with BacktraceDatabase and your application is offline or you pass invalid credentials to Backtrace server, reports will be stored in database directory path.
Attaching custom event handlers
Backtrace Client allows you to attach your custom event handlers. For example, you can trigger actions before the Send method:
//Add your own handler to client API
backtraceClient.BeforeSend =
(Model.BacktraceData model) =>
{
var data = model;
//do something with data for example:
data.Attributes.Add("eventAtrtibute", "EventAttributeValue");
if(data.Classifier == null || !data.Classifier.Any())
{
data.Attachments.Add("path to attachment");
}
return data;
};
Backtrace Client currently supports the following events:
- BeforeSend
- OnClientReportLimitReached
- OnServerResponse
- OnServerError
Reporting unhandled application exceptions
BacktraceClient supports reporting of unhandled application exceptions not captured by your try-catch blocks. To enable reporting of unhandled exceptions even if you don't set this option in Backtrace configuration window use code below:
backtraceClient.HandleApplicationException();
Flush database
When your application starts, database can send stored offline reports. If you want to do make it manually you can use Flush method that allows you to send report to server and then remove it from hard drive. If Send method fails, database will no longer store data.
backtraceDatabase.Flush();
Clearing database
You can clear all data from database without sending it to server by using Clear method. BacktraceDatabase will remove all files and won't send it to server.
backtraceDatabase.Clear();
Advanced Topics
For more information on advanced features and architecture related details, please see the Readme on github - https://github.com/backtrace-labs/backtrace-unity/blob/master/README.md
Investigating an Error in Backtrace
Once errors are being reported to your Backtrace instance, you should see them in your Triage and Web Debugger view. See below for a screenshot of the Triage view with some Unity exceptions reported.
The developer who is debugging the error may find it useful to view more details of Exception. They choose the 'View Latest Trace' action to see more details in the Backtrace Web Debugger. Below we can see a list of all attributes submitted with a report. (Note the yield signs are just an indicator that this value is not indexed in Backtrace). We can also see the call stack and details of the selected frame.
Below we see more details above the Environment Variables from the Web Debugger to further assist with investigation.
