Basic configuration
The configuration settings for the Backtrace client and database are defined by the Backtrace Configuration file in the Assets folder of your Unity project. It's recommended to change the configuration settings for the Backtrace client and database in the Unity Inspector:
Alternatively, you can also specify the configuration settings in your C# project.
Enable Stack traces for WebGL
- Open your project in the Unity Editor.
- From the Unity Editor menu, select Edit > Project Settings.
- Under Publishing Settings, set Enable Exceptions to Full With Stacktrace.
Backtrace client settings
Setting | Description | Type | Default |
---|---|---|---|
Server address | The server address (submission URL) is required to submit exceptions from your Unity project to your Backtrace instance. The server address can be generated in Settings > Error Submission > Submission tokens > Generate server address in action menu and will be in the following format: https://submit.backtrace.io/{subdomain}/{submission-token}/json. | String | |
Handle unhandled exceptions | Handles unhandled exceptions that aren’t captured by try/catch statements. | Boolean | True |
Reports per minute | Limits the number of reports the client will send per minute.
The BacktraceClient.Send and BacktraceClient.SendAsync methods will return 'false'. | Number | 50 |
Ignore SSL validation | By default, Unity validates SSL certificates. If you don't want to validate SSL certificates, set the value to 'true'. | Boolean | False |
Backtrace database settings
Setting | Description | Type | Default |
---|---|---|---|
Enable database | Enables an offline database to store reports locally. | Boolean | False |
Backtrace database path | Specifies the absolute path that the local database will use to store reports for your game or app. Note that the Backtrace database will remove all existing files in the database directory when the client is first initialized. You can use interpolated strings such as ${Application.persistentDataPath}/backtrace/database . | String | |
Client-side deduplication | Aggregates duplicated reports. The available options are:
| Enum | Diasble |
Attach Unity player.log | Attaches the Unity player log file to the Backtrace report. Available only for Windows and macOS. | Boolean | False |
Auto send mode | Sends reports to the server based on the retry settings described below. If the value is set to 'False', you can use the Flush or Send methods as an alternative. | Boolean | True |
Create database directory | Creates the offline database directory if the provided path doesn't exist. | Boolean | True |
Attach screenshot | Generates a screenshot and creates an attachment of the frame when an exception occurs in a game scene. | Boolean | False |
Maximum number of records | The maximum number of reports stored in the offline database. When the limit is reached, the oldest reports are removed. If the value is equal to '0', then no limit is set. | Integer | 8 |
Maximum database size (mb) | The maximum database size in MB. When the limit is reached, the oldest reports are removed. If the value is equal to '0', then no limit is set. | Integer | 0 |
Retry interval | The amount of time (in seconds) to wait between retries if the database is unable to send a report. | Integer | 60 |
Maximum retries | The maximum number of retries to attempt if the database is unable to send a report. | Integer | 3 |
Retry order (FIFO/LIFO) | The order in which reports are sent to the Backtrace server:
| Enum | Stack |
Advanced client settings
Setting | Description | Type | Default |
---|---|---|---|
Use normalized exception message | Generates a fingerprint with a normalized exception message if an exception doesn't have a stack trace. | Boolean | False |
Send unhandled native game crashes on startup | Sends native crashes when the game or app starts. Available only for Windows. | Boolean | True |
Filter reports | Ignores managed error reports based on error type:
| Enum | Disable |
Collect last n game logs | Collects the last n number of logs generated in the game. | Integer | 10 |
Enable performance statistics | Allows the Backtrace client to measure execution time and include performance information as report attributes. | Boolean | False |
Destroy client on new scene load | Removes the Backtrace client component when loading a new game scene. By default, the Backtrace client will be available in every game scene. | Boolean | False |
Log random sampling rate | The rate at which random sample reports for DebugLog.error messages are sent to Backtrace. By default, 1% of the DebugLog.error messages will be sent to Backtrace. To send all DebugLog.error messages to Backtrace, set the value to '1'. | Decimal | 0.01 |
Game object depth limit | Filters the number of GameObject children in Backtrace reports. | Integer | -1 |
Disable error reporting integration in editor | Ignores errors encountered while the project is running in the Unity Editor and only reports errors encountered in a build. | Boolean | False |
Crash-free metrics reporting
Once enabled, unique application launches and unique player identifiers (default: guid) will be submitted to Backtrace so you can get an overview of how many errors, hangs, crashes, and memory problems occur compared to all active users for a given platform, version, and more.
Note: This functionality is supported on all platforms except WebGL.
Setting | Description | Type | Default |
---|---|---|---|
Enable crash free metrics reporting | Enables metrics such as crash free users and crash free sessions. | Boolean | True |
Auto send interval in min | Indicates how often crash free metrics are sent to Backtrace. By default, session events are sent on application startup, when the game ends, and every 30 minutes while the game is running. | Integer | 30 |
Native support
Use the Backtrace Unity SDK to capture native crashes for:
Android settings
The Backtrace Unity SDK includes support for capturing native crashes, as well as memory and process information from the underlying Android OS, JNI, and NDK layers, including the following attributes:
system.memory.free
system.memory.swap.free
system.memory.vmalloc.total
sched.cs.involuntary
sched.cs.voluntary
Setting | Description | Type | Default |
---|---|---|---|
Capture native crashes | Captures and symbolicates stack traces for native crashes. A crash report is generated, stored locally, and uploaded on the next game start. | Boolean | True |
Capture ANR (application not responding) | Generates an error report whenever an app hangs for more than 5 seconds. The error.type for these reports will be Hang . | Boolean | True |
Send Out of Memory exceptions to Backtrace | Detects low memory conditions. If the app crashes due to a memory condition, a crash report will be submitted with the memory.warning and memory.warning.date attributes . | Boolean | False |
Enable client-side unwinding | Enables callstack unwinding. If you're unable to upload all debug symbols for your app, you can use this setting to get debug information. Available only for supported versions of Android (NDK 19; Unity 2019+). You can also enable this setting with the BacktraceConfiguration object and the .ClientSideUnwinding = true; option. | Boolean | False |
Symbols upload token | Required to automatically upload debug symbols to Backtrace. To generate a symbol upload token, in the Cloud Diagnostics Advanced dashboard, go to Project Settings > Symbols > Access tokens > and select + to generate a new token. | String |
Uploading debug symbols
You can configure the Backtrace client to automatically upload debug symbols in IL2CPP builds for Android apps.
- Open your project in the Unity Editor.
- From the Unity Editor menu, select File > Build Settings.
- In the Build Settings, set Create symbols.zip to Debugging.
4. From the Build Settings, select Player Settings.
5. In the Player Settings, search for “Scripting Backend”.
6. Under Configuration (in Other Settings), set Scripting Backend to IL2CPP.
For more information about debug symbols, see Debug symbols.
iOS settings
The Backtrace Unity SDK includes support for capturing native crashes, as well as memory and process information from the underlying iOS layer, including the following attributes:
system.memory.free
system.memory.swap.used
system.memory.total
system.memory.active
system.memory.inactive
Setting | Description | Type | Default |
---|---|---|---|
Capture native crashes | Captures and symbolicates stack traces for native crashes. A crash report is generated, stored locally, and uploaded on the next game start. | Boolean | True |
Capture ANR (application not responding) | Generates an error report whenever an app hangs for more than 5 seconds. The error.type for these reports will be Hang . | Boolean | True |
Send Out of Memory exceptions to Backtrace | Detects low memory conditions. If the app crashes due to a memory condition, a crash report will be submitted with the memory.warning and memory.warning.date attributes . | Boolean | False |
Enable client-side unwinding | Enables callstack unwinding. If you're unable to upload all debug symbols for your app, you can use this setting to get debug information. Available only for supported versions of Android (NDK 19; Unity 2019+). You can also enable this setting with the | Boolean | False |
Diasble the CrashReport API
The CrashReport API might prevent the Backtrace client from sending native crashes for iOS.
- Open your project in the Unity Editor.
- From the Unity Editor menu, select File > Build Settings.
- From the Build Settings, select Player Settings.
- In the Player Settings, search for “CrashReport API”.
- Under Crash Reporting (in Debugging and crash reporting), make sure Enable CrashReport API Backend is disabled.
Uploading debug symbols
When building your iOS game in Xcode, make sure to configure the build settings to generate dSYM files for any build that you want to debug. By default, Xcode may only generate DWARF files.
- In Xcode, go to your project target's Build Settings.
- Under Build Options, set Debug Information Format to DWARF with dSYM File.
You can find the dSYM files in the Build folder for your project (.../Build/Products/<build target folder>), which you can then compress into a .zip file and upload to Cloud Diagnostics Advanced.
For more information about debug symbols, see Debug symbols.
Windows settings
The Backtrace Unity SDK includes support for capturing native Windows crashes.
Setting | Description | Type | Default |
---|---|---|---|
Minidump type | The type of memory information to capture from Windows minidump reports. | Enum | None |
Capture native crashes | Captures and symbolicates stack traces for native crashes. A crash report is generated, stored locally, and uploaded on the next game start. | Boolean | True |
Capture ANR (application not responding) | Generates an error report whenever an app hangs for more than 5 seconds. The error.type for these reports will be Hang . | Boolean | True |
Logging breadcrumbs
Setting | Description | Type | Default |
---|---|---|---|
Enable breadcrumbs support | Enable breadcrumbs support logs breadcrumb events, such as the app going to a background process, logging messages, network connectivity lost, and more. By default, breadcrumbs are limited to 64kB and older events will automatically be removed. | Enum | False |
Breadcrumbs event type | Specifies which type of events to log. | Boolean | Everything |
Breadcrumbs log level | Specifies which log level severity to include. | Boolean | Everything |
You can also add custom breadcrumb events, with information like "player completed a level" and sub attributes:
GetComponent<BacktraceClient>().Breadcrumbs.Info("Player Base Upgraded", new Dictionary<string, string>() {
{"base.name", "MtGox"},
{"base.level", "15"}
});