Backtrace's integration with unity games allows customers to capture and report handled and unhandled Unity exceptions to their Backtrace instance, instantly offering the ability to prioritize and debug software errors.
//Read from manager BacktraceClient instance
var backtraceClient = GameObject.Find("_Manager").GetComponent<BacktraceClient>();
try{
//throw exception here
}
catch(Exception exception){
var report = new BacktraceReport(exception);
backtraceClient.Send(report);
}
- Light-weight Unity client that quickly submits crashed generated in Unity environment to your Backtrace dashboard
- Can include callstack, system metadata, custom metadata, custom attributes and file attachments if needed
- Supports a wide range of unity version and environments
- Supports .NET 2.0/3.5/4.5/Standard 2.0 Backend, IL2CPP and Mono environments
- Supports offline database for error report storage and re-submission in case of network outage
- Fully customizable and extendable event handlers
- Custom IDE integrations
- Unity environment 2017.4.x
- .NET 2.0/3.5/4.5/Standard 2.0 scripting runtime version
- Mono or IL2CPP scripting backend
List of steps necessary to setup full Backtrace Unity integration.
- Download the backtrace-unity zip file. Unzip it and keep the folder in a known location. It can be downloaded from https://github.com/backtrace-labs/backtrace-unity/releases
- Open your Unity project
- Copy the unzipped folder to your project's asset folder in the Windows File Explorer. The Unity editor will refresh and the Backtrace Plugin should become available in the editor.
- Under the Assets Menu, there is now a Backtrace -> Configuration option. Choose that option (or Right click on empty space and select from the menu box) to have a Backtrace Configuration is generated in the Assets folder. You can drag and drop generated asset file into Backtrace Client configuration window.
- 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.
- Provide valid Backtrace client configuration and start using library!
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 - https://player.vimeo.com/video/300051476
Plugin allows you to define maximum depth of game objects. By default its disabled (Game object depth is equal to -1). If you would like to include all game objects, please select 0. If you would like to specify game object depth size to n, please insert n in Backtrace configuration text box.
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. More information about how to retrieve this value for your instance is our docs at What is a submission URL and What is a submission token? NOTE: the backtrace-unity plugin will expect full URL with token to your Backtrace instance,
- 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.
- Destroy client on new scene load - Backtrace-client by default will be available on each scene. Once you initialize Backtrace integration, you can fetch Backtrace game object from every scene. In case if you don't want to have Backtrace-unity integration available by default in each scene, please set this value to true.
- Handle unhandled exceptions: Toggle this on or off to set the library to handle unhandled exceptions that are not captured by try-catch blocks.
- Game Object Depth Limit: Allows developer to filter number of game object childrens in Backtrace report.
- Ignore SSL validation: Unity by default will validate ssl certificates. By using this option you can avoid ssl certificates validation. However, if you don't need to ignore ssl validation, please set this option to false.
- Deduplication rules: Backtrace-unity plugin allows you to combine the same reports. By using deduplication rules, you can tell backtrace-unity plugin how we should merge reports.
- Minidump type: Type of minidump that will be attached to Backtrace report in the report generated on Windows machine.
- 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.
You can further configure your game to submit crashes by making further changes in the C# code for your game.
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!
//Read from manager BacktraceClient instance
var backtraceClient = GameObject.Find("manager name").GetComponent<BacktraceClient>();
//Read from manager BacktraceClient instance
var database = GameObject.Find("manager name").GetComponent<BacktraceDatabase>();
try{
//throw exception here
}
catch(Exception exception){
var report = new BacktraceReport(exception);
backtraceClient.Send(report);
}
If you would like to change Backtrace client/database options, we recommend to change these values on the Unity UI via Backtrace Configuration file. However, if you would like to change these values dynamically, please use method Refresh
to apply new configuration changes.
For example:
//Read from manager BacktraceClient instance
var backtraceClient = GameObject.Find("manager name").GetComponent<BacktraceClient>();
//Change configuration value
backtraceClient.Configuration.DeduplicationStrategy = deduplicationStrategy;
//Refresh configuraiton
backtraceClient.Refresh();
BacktraceClient.Send
method will send an error report to the Backtrace endpoint specified. There Send
method is overloaded, see examples below:
The BacktraceReport
class represents a single error report. (Optional) You can also 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<string>() { @"file_path_1", @"file_path_2" }
);
backtraceClient.Send(report);
}
Notes:
- if you setup
BacktraceClient
withBacktraceDatabase
and your application is offline or you pass invalid credentials toBacktrace server
, reports will be stored in database directory path, BacktraceReport
allows you to change default Fingerprint generation algorithm. You can useFingerprint
property if you want to change Fingerprint value. Keep in mind - Fingerprint should be valid sha256 string. By settingFingerprint
you are instructing the client reporting library to only write a single report for the exception as it is encountered, and maintain a counter for every additional time it is encountered, instead of creating a new report. This will allow better control over the volume of reports being generated and sent to Backtrace. The counter is reset when the offline database is cleared (usually when the reports are sent to the server). A new single report will be created the next time the error is encountered.BacktraceReport
allows you to change grouping strategy in Backtrace server. If you want to change how algorithm group your reports in Backtrace server please overrideFactor
property.
If you want to use Fingerprint
and Factor
property you have to override default property values. See example below to check how to use these properties:
try
{
//throw exception here
}
catch (Exception exception)
{
var report = new BacktraceReport(...){
Fingerprint = "sha256 string",
Factor = exception.GetType().Name
};
....
}
BacktraceClient
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("eventAttribute", "EventAttributeValue");
if(data.Classifier == null || !data.Classifier.Any())
{
data.Attachments.Add("path to attachment");
}
return data;
};
BacktraceClient
currently supports the following events:
BeforeSend
OnClientReportLimitReached
OnServerResponse
OnServerError
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
please use code below:
backtraceClient.HandleApplicationException();
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();
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();
Backtrace unity integration allows you to aggregate the same reports and send only one message to Backtrace Api. As a developer you can choose deduplication options. Please use DeduplicationStrategy
enum to setup possible deduplication rules in Unity UI:
Deduplication strategy types:
- Ignore - ignore deduplication strategy,
- Default - deduplication strategy will only use current strack trace to find duplicated reports,
- Classifier - deduplication strategy will use stack trace and exception type to find duplicated reports,
- Message - deduplication strategy will use stack trace and exception message to find duplicated reports,
Notes:
- When you aggregate reports via Backtrace C# library,
BacktraceDatabase
will increase number of reports in BacktraceDatabaseRecord counter property. - Deduplication algorithm will include
BacktraceReport
Fingerprint
andFactor
properties.Fingerprint
property will overwrite deduplication algorithm result.Factor
property will change hash generated by deduplication algorithm. - If Backtrace unity integration combine multiple reports and user will close a game before plugin will send data to Backtrace, you will lose coutner information.
BacktraceDatabase
methods allows you to use aggregated diagnostic data together. You can checkHash
property ofBacktraceDatabaseRecord
to check generated hash for diagnostic data andCounter
to check how much the same records we detect.BacktraceDatabase
Count
method will return number of all records stored in database (included deduplicated records),BacktarceDatabase
Delete
method will remove record (with multiple deduplicated records) at the same time.
BacktraceReport
is a class that describe a single error report.
BacktraceClient
is a class that allows you to send BacktraceReport
to Backtrace
server by using BacktraceApi
. This class sets up connection to the Backtrace endpoint and manages error reporting behavior (for example, saving minidump files on your local hard drive and limiting the number of error reports per minute). BacktraceClient
inherits from Mono behavior
.
BacktraceClient
requires from a Backtrace configuration window
Sever URL
- URL toBacktrace
server,Token
- token toBacktrace
project,ReportPerMin
- A cap on the number of reports that can be sent per minute. IfReportPerMin
is equal to zero then there is no cap.HandleUnhandledExceptions
- flag that allowsBacktraceClient
handling unhandled exception by default.
BacktraceData
is a serializable class that holds the data to create a diagnostic JSON to be sent to the Backtrace endpoint via BacktraceApi
. You can add additional pre-processors for BacktraceData
by attaching an event handler to the BacktraceClient.BeforeSend
event. BacktraceData
require BacktraceReport
and BacktraceClient
client attributes.
BacktraceApi
is a class that sends diagnostic JSON to the Backtrace endpoint. BacktraceApi
is instantiated when the BacktraceClient
awake method is called. BacktraceApi
can asynchronous reports to the Backtrace endpoint.
BacktraceDatabase
is a class that stores error report data in your local hard drive. BacktraceDatabase
stores error reports that were not sent successfully due to network outage or server unavailability. BacktraceDatabase
periodically tries to resend reports
cached in the database. In BacktraceDatabaseSettings
you can set the maximum number of entries (Maximum retries
) to be stored in the database. The database will retry sending
stored reports every Retry interval
seconds up to Retry limit
times, both customizable in the Backtrace database configuration
.
Backtrace database
has the following properties:
Database path
- the local directory path whereBacktraceDatabase
stores error report data when reports fail to send,MaxRecordCount
- Maximum number of stored reports in Database. If value is equal to0
, then there is no limit.MaxDatabaseSize
- Maximum database size in MB. If value is equal to0
, there is no limit.AutoSendMode
- if the value istrue
,BacktraceDatabase
will automatically try to resend stored reports. Default isfalse
.RetryBehavior
- -RetryBehavior.ByInterval
- Default.BacktraceDatabase
will try to resend the reports every time interval specified byRetryInterval
. -RetryBehavior.NoRetry
- Will not attempt to resend reportsRetryInterval
- the time interval between retries, in seconds.RetryLimit
- the maximum number of timesBacktraceDatabase
will attempt to resend error report before removing it from the database.
If you want to clear your database or remove all reports after send method you can use Clear
and Flush
.
ReportWatcher
is a class that validate send requests to the Backtrace endpoint. If reportPerMin
is set in the BacktraceClient
constructor call, ReportWatcher
will drop error reports that go over the limit. BacktraceClient
check rate limit before BacktraceApi
generate diagnostic json.
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.
- Backtrace Unity integration use JSON.NET library to create diagnostic JSON. JSON.NET Source code is available in
src
directory. JSON.NET was modified for Backtrace-plugin purpose.