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.
Create a Backtrace instance for yourself at https://register.backtrace.io/signup/ - Once you log in, you can view a quick start for how to integrate with Unity in the Project Settings / Integration Guide page.
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 OpenUPM and the Unity Package Manager
- Identify and measure crash-free statistics against unique users or sessions
- 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
- Breadcrumbs, screenshots, log or config files, other attachments
- Android NDK Crashes; iOS Native Crashes, Windows Native Crashes
- Client-side features
- Deduplication options and custom client side fingerprinting
- Client side filters and sampling controls
- 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
- A Backtrace instance (created through https://register.backtrace.io/signup/ i.e. https://mygame.sp.backtrace.io)
- Unity environment 2017+
- .NET 3.5/4.5/Standard 2.0 scripting runtime version
- Mono or IL2CPP scripting backend
Setup and Installation
You have three options, we recommend using OpenUPM for most users.
OpenUPM
- See our package and installation instructions on OpenUPM.
Git Url
Since Unity 2018.3 the Unity Package Manager allows you to install a package directly via Git. You can use the clone URL on the main page of our repository.
Manual download
- Download the backtrace-unity zip file. Unzip it and keep the folder in a known location. It can be downloaded here
- Open your Unity project
- Use the Unity Package Manager to install the backtrace-unity library (Window -> Package Manager -> Add Package From Disk ->
KnownFolder/package.json)
For more information, see the README on GitHub.
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 - PlayStation 4, PlayStation 5, Xbox One, Xbox Series X | S, Nintendo Switch, Google Stadia
There are some differences in capabilities that backtrace-unity provides based on the platform. Major capabilities are summarized as follows:
- All Platforms - Errors, Unhandled Exceptions, Handled Exceptions, Custom Indexable Metadata, File Attachments*, Breadcrumbs, Automatic attachment of Screenshots, Client Side Deduplication Rules*, Client Side Submission Filtering, Client Side Submission Limits, Crash Free Metrics (except WebGL), 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), NDK crashes, low memory warnings. - iOS - Identified by attribute
uname.sysname= IOS; ANRs (Hangs), Native Engine, Memory and Plugin Crashes. - WebGL - Identified by attribute
uname.sysname= WebGL. The attributedevice.modelis currently used to share the browser information. Note that stacktraces for WebGL errors are only available if you choose to enable them in the Publishing Settings / Enable Exceptions drop down. More details here. - 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. If this is set, the call stack will be empty and no log lines section will be included in Breadcrumbs.
Basic integration into your Project
Watch the following 120-second explainer video to takes you through the step-by-step process of integrating Backtrace to the Unity editor.
- 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.
See this screenshot for an example:
Additional Topics
For more information on features such as Crash Free Metrics, Breadcrumbs, Offline Database, architecture related details and much more, please see the Readme on GitHub.
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. We can also see the call stack and details of the selected frame.