Backtrace Unity Integration

Prerequisites

• Unity Version: 2017.4.x or newer.
• Scripting Runtime: .NET 2.0/3.5/4.5 or Standard 2.0.
• Scripting Backend: Mono or IL2CPP.
• Backtrace Instance: You must have a Backtrace instance (create one at backtrace.io/create-unity).

Platform Support Summary

• All Platforms: Supports errors, unhandled/handled exceptions, custom metadata, file attachments, log lines, screenshots, client-side de-duplication, filtering, and performance diagnostics.
• Android: Supports ANR (hangs), native process/memory info, Java exception handlers, and NDK crashes.
• iOS: Supports ANR (hangs), native engine/memory/plugin crashes.
• WebGL: Supports WebGL errors (ensure 'Enable Exceptions' is enabled in Publishing Settings to see stack traces).
• Nintendo Switch: Supports errors and exceptions. Note: Offline database and related features are not supported on Switch. Device GUID changes on every reboot.
• Windows: Supports engine crash mini-dumps.
• PlayStation 4/5, Xbox One/S/X, Mac: Fully supported.

The Backtrace Unity integration allows you to aggregate identical error reports so that only one message is sent to the Backtrace API. You can configure this using the DeduplicationStrategy enum in the Unity UI.

Available deduplication strategies:

• Ignore: Disables deduplication.
• Default: Searches for duplicate reports using the current stack trace.
• Classifier: Searches for duplicate reports using both the stack trace and the exception type.
• Message: Searches for duplicate reports using both the stack trace and the exception message.

Important Notes:

• When aggregating reports via the Backtrace C# library, the BacktraceDatabaseRecord.Counter property increases.
• The deduplication algorithm uses BacktraceReport, Fingerprint, and Factor properties. The Fingerprint property overrides the algorithm's result, while the Factor property modifies the generated hash.
• If the game is closed before the plugin can send aggregated data to Backtrace, counter information may be lost.
• You can inspect aggregated diagnostic data using BacktraceDatabase. Use the Hash property to check the generated hash and the Counter property to see the number of detected identical records.

# Example of interacting with BacktraceDatabase for aggregated data
// Check the hash and count of aggregated records
var hash = database.BacktraceDatabaseRecord.Hash;
var count = database.BacktraceDatabaseRecord.Counter;

// Get total records in database (including duplicates)
int totalCount = database.Count();

// Delete records (including duplicates)
database.Delete(record);

The Backtrace Unity integration is composed of several key classes:

• BacktraceReport: Represents a single error report.
• BacktraceClient: A MonoBehaviour that manages the connection to the Backtrace endpoint and error report behavior (e.g., saving minidumps, rate limiting). It requires configuration via the Backtrace configuration window.
• BacktraceData: A serializable class holding diagnostic JSON data. You can add pre-processors by attaching event handlers to BacktraceClient.BeforeSend.
• BacktraceApi: Handles the asynchronous transmission of diagnostic JSON to the Backtrace endpoint. It is instantiated when BacktraceClient.Awake is called.
• BacktraceDatabase: Stores error reports locally on the hard drive if network or server issues prevent transmission. It periodically attempts to resend cached reports.
• ReportWatcher: Validates transmission requests against the reportPerMin limit set in the BacktraceClient to prevent rate-limit violations.

To integrate Backtrace programmatically, you should use the BacktraceClient.Initialize method. This allows you to set up the client with a specific server URL, database path, and custom attributes. You can also provide a BacktraceConfiguration ScriptableObject for more advanced settings like sampling rates and database creation.

// Basic initialization
var backtraceClient = BacktraceClient.Initialize(
    url: serverUrl,
    databasePath: "${Application.persistentDataPath}/sample/backtrace/path",
    gameObjectName: "game-object-name",
    attributes: attributes);

// Advanced initialization using BacktraceConfiguration
var configuration = ScriptableObject.CreateInstance<BacktraceConfiguration>();
configuration.ServerUrl = serverUrl;
configuration.Enabled = true;
configuration.DatabasePath = "${Application.persistentDataPath}/sample/backtrace/path";
configuration.CreateDatabase = true;
configuration.Sampling = 0.002;

_backtraceClient = BacktraceClient.Initialize(
    configuration,
    gameObjectName: "game-object-name",
    attributes: attributes);