Customizing error reports

In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to your BugSnag dashboard to provide a rich context that is also available for searching and filtering.

You can also amend the events captured by BugSnag to adjust the information shown on the dashboard and even choose not to send the event at all.

This documentation is for version 6+ of the BugSnag Unity notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Updating events using callbacks

If you’d like to add diagnostic data to reports, or adjust event data conditionally, you can register a callback to be run before an error is delivered to your BugSnag dashboard using a callback:

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddOnSendError(@event => {
    @event.AddMetadata("account", "name", "Acme Co.");
    @event.AddMetadata("account", "paying_customer", true);

    // Return `false` if you'd like to stop this error being reported
    return true;
});
Bugsnag.Start(config);

This callback gives you access to an Event object, so you can inspect and modify the error event which is about to be sent to BugSnag.

If the app has crashed, these delivery-time callbacks will be executed in a background thread when the app next launches and has network connectivity. This means the state of the app and device are likely to be different to how they were when the crash occurred and so care must be taken when reading or adding external data in a callback.

On-error callbacks

We also provide an “on-error” callback that is fired immediately after the error has occurred. However these callbacks are not triggered for errors that crash the app (i.e. native crashes).

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddOnError(@event => {
    @event.AddMetadata("game", "current_score", 13);
    return true;
});
Bugsnag.Start(config);

On-error callbacks can be used to augment the event with useful information from the app or device that might be available at the time of the error. However as they are not triggered for all types of error, they should not be relied upon for redacting data from all events; you should consider using on-send callbacks (see above) for this.

We recommend adding on-error callbacks through BugSnag’s initial configuration (AddOnError) to ensure that it is registered as soon as BugSnag starts. However, the following methods are provided to allow callbacks to be added whilst the application is running:

Func<IEvent, bool> cb = @event => { /* ... */ };

Bugsnag.AddOnError(cb);
// ...
Bugsnag.RemoveOnError(cb);

Discarding events

If you want to prevent an event from being sent to BugSnag, you can return false within a callback. This would allow for users to opt out of sending error reports, for example:

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddOnSendError(@event => {
    return !currentUser.optedOut();
});
Bugsnag.Start(config);

Global metadata

If you have metadata that is applicable to all captured events, it can be set globally on the Bugsnag client and will be set on all subsequently generated events. To ensure that events contain metadata as soon as BugSnag starts capturing events, we recommend that you add metadata in your initial BugSnag configuration if the data is available at startup.

Data is added to a specified “section”, which is displayed as a tab in the BugSnag dashboard, and can either be added individually or as a dictionary:

var config = BugsnagSettingsObject.LoadConfiguration();
config.AddMetadata("account", "name", "Acme Co.");
config.AddMetadata("basket", new Dictionary<string, object> {
    { "delivery", "express" },
    { "sale", "spring" }
});
Bugsnag.Start(config);

Metadata can also be managed whilst your application is running using AddMetadata and ClearMetadata on the Bugsnag client:

Bugsnag.AddMetadata("account", "name", "Acme Co.");
// ...
Bugsnag.ClearMetadata("account");

Adding user data

Information about the user affected by errors can be added to events sent to your BugSnag dashboard by setting an initial user ID, email and name in your initial BugSnag configuration when BugSnag starts:

var config = BugsnagSettingsObject.LoadConfiguration();
config.SetUser("3", "bugs.nag@bugsnag.com", "Bugs Nag");
Bugsnag.Start(config);

By default, this user information is persisted between launches and so will be set automatically on subsequent launches of your app. You can disable this behavior using the Persist User configuration option.

You can use metadata to add additional user information to the “user” section.

If the user changes whilst the application is running, for example if a user signs in, you can update the user data on the Bugsnag client for all subsequent events:

Bugsnag.SetUser("3", "bugs.nag@bugsnag.com", "Bugs Nag");

Setting context

BugSnag uses the concept of “contexts” to help display and group your errors. The context represents what was happening in your application at the time an error occurs and is given high visual prominence in the dashboard.

By default this is set this to the name of the currently executing function. If you would like to set this value manually, you can set an initial value in your initial BugSnag configuration when BugSnag starts:

var config = BugsnagSettingsObject.LoadConfiguration();
config.Context = "InitialTutorialStep";
Bugsnag.Start(config);

The context can then be amended through the Bugsnag client as/when it changes for all subsequent events:

Bugsnag.Context = "InitialTutorialStep";

The Event class

An Event object represents an error captured by Bugsnag and is available as a parameter on an event callback. The following methods are available on an Event for you to query and update the captured data.

API Key

The API key used for events sent to BugSnag. Even though the API key is set when BugSnag is initialized, you may choose to send certain events to a different BugSnag project:

var apiKey = @event.APIKey;

App

Information set by the notifier about your app can be found in the App object:

property type description
BinaryArch String The architecture of the running application binary
BuildUuid String The unique identifier for the build of the application (Android only)
BundleVersion String The bundle version used by the application (iOS only)
Duration Number The number of milliseconds the application was running before the event occurred
DurationInForeground Number The number of milliseconds the application was running in the foreground before the event occurred
Id String The package name of the application
InForeground Boolean Whether the application was in the foreground when the event occurred
IsLaunching Boolean Whether the application was still launching when the event occurred
ReleaseStage String The release stage set in Configuration
Type String The application type set in Configuration
Version String The version of the application set in Configuration
VersionCode String The version code of the application set in Configuration (Android only)

These values can be accessed and amended if necessary:

@event.App.BuildUuid = build.BuildNumber;

A list of breadcrumbs leading up to the event can be found in Event.Breadcrumbs:

property type description
Message String The description of the breadcrumb
Metadata Dictionary<string,object> Diagnostic data relating to the breadcrumb
Timestamp DateTime The timestamp that the breadcrumb was left
Type BreadcrumbType The type of breadcrumb left

These values can be accessed and amended if necessary:

@event.Breadcrumbs[0].Message = "Left home screen";

Context

The context represents what was happening in your application at the time an error occurs.

@event.Context = "User settings";

See Setting context for more information.

Device

Information set by the notifier about the device on which the event occurred can be found in Event.Device:

property type description
CpuAbi String[] The Application Binary Interface used (Android only)
FreeDisk Number The number of free bytes of storage available on the device
FreeMemory Number The available RAM on the device (in bytes)
Id String A UUID generated by BugSnag and used for the individual application on a device
Jailbroken String Whether the device has been jailbroken
Locale String The IETF language tag of the locale used
Manufacturer String The manufacturer of the device used
Model String The model name of the device used
ModelNumber String The model number of the device used
Orientation String The orientation of the device when the event occurred: either portrait or landscape
OsName String The name of the operating system running on the device used
OsVersion String The version of the operating system running on the device used
RuntimeVersions Dictionary<string,object> A collection of names and their versions of the primary languages, frameworks or runtimes that the application is running on
Time String The timestamp on the device when the event occurred
TotalMemory Number The total RAM size of the device (in bytes)

These values can be accessed and amended if necessary:

@event.Device.Locale = "de-DE";

Errors

event.errors is an array of one or more Error objects. The first item in the list represents the thrown object. Each subsequent item represents the exception that caused the preceding one.

An Error object contains the following information:

property type description
ErrorClass String The fully-qualified class name of the error generating the event
ErrorMessage String The message string from the error generating the event
Stacktrace List<IStackframe> A representation of the stacktrace
Type ErrorType The type of error based on the originating platform
@event.Errors[0].ErrorClass = "MyError";

In an Error object, the stacktrace is a list of the following Stackframe objects:

property type description
File String The location of the source file
FrameAddress String The stack frame address (iOS only)
InProject Boolean Whether the package is considered to be in your project for the purposes of grouping and readability on the BugSnag dashboard.
IsLr Boolean Whether the frame was within the link register (iOS only)
IsPc Boolean Whether the frame was within the program counter (iOS only)
LineNumber Number The line number within the source file this stackframe refers to
MachoFile String The Mach-O file used by the stackframe (iOS only)
MachoLoadAddress Number The load address of the Mach-O file (iOS only)
MachoUuid String A UUID identifying the Mach-O file used by the stackframe (iOS only)
MachoVmAddress Number The VM address of the Mach-O file (iOS only)
Method String The name of the method that was being executed
SymbolAddress Number The address of the stackframe symbol (iOS only)

It is therefore possible to modify the stacktrace that is associated with the Event object in the following way:

foreach (IStackframe frame in @event.Errors[0].Stacktrace)
{
    // Your code here: e.g. frame.InProject = true
}

Feature Flags

Use the following operations to access and amend the feature flags to be sent with the event.

var features = @event.FeatureFlags;

Declare a single feature flag or experiment with variant as an optional second parameter.

@event.AddFeatureFlag("Checkout button color", "Blue");
@event..AddFeatureFlag("New checkout flow");

Declare multiple feature flags or experiments.

@event.AddFeatureFlags(new FeatureFlag[] {
    new FeatureFlag("Checkout button color","Blue"),
    new FeatureFlag("Special offer","Free Coffee"),
    new FeatureFlag("New checkout flow")
});

Remove a single feature flag or experiment.

@event.ClearFeatureFlag("Checkout button color");

Remove all feature flags and experiments.

@event.ClearFeatureFlags();

For more information, see Feature flags & experiments.

Grouping Hash

The grouping hash of the event to override the default grouping on the dashboard. All events with the same grouping hash will be grouped together into one error. This is an advanced usage of the library and mis-using it will cause your events not to group properly in your dashboard.

As the name implies, this option accepts a hash of sorts.

// ... generate the hash
var groupingHash = "f8803769f3e293dfcabdb6dec5100b8c52c6ae6b";
@event.GroupingHash = groupingHash;

Metadata

Add and remove metadata from a specified section, which is shown as a tab on the BugSnag dashboard.

Data can be added key-by-key with a value that is a primitive type or a collection such as a map, set or array:

@event.AddMetadata("account", "name", "Acme Co.");
@event.AddMetadata("account", "paying_customer", true);

Alternatively a whole map of key-value pairs can be added for a section:

@event.AddMetadata("basket", new Dictionary<string, object> {
    { "delivery", "express" },
    { "sale", "spring" }
});

Metadata set on the event will be combined with global metadata set on the Bugsnag client, with properties on the Event taking precedence.

To remove all the data from the specified section or from a key in the section:

@event.ClearMetadata("basket");

You can also obtain a map of data in the specified section and optionally key:

IDictionary<string, object> metadata = @event.GetMetadata("account");
// or
string accountName = (string) @event.GetMetadata("account", "name");

Severity

The severity of the event. By default, unhandled exceptions will be Severity.Error and handled exceptions sent with Notify will be Severity.Warning.

@event.Severity = Severity.Warning;

Threads

If thread state is being captured along with the event, event.threads will contain a list of Thread objects as follows:

property type description
Id Number The unique ID of the thread
IsErrorReportingThread Boolean Whether the thread was the thread that caused the event
Name String The name of the thread
Stacktrace List<IStackframe> A representation of the stacktrace when the event occurred
State String The state of the thread when the event occurred
Type String The type of thread based on the originating platform
@event.Threads[0].Name = "New name";

Unhandled

Whether the error was detected automatically by BugSnag (true), or reported manually via Bugsnag.Notify (false).

@event.Unhandled = false;

Changing the Unhandled flag for an event will affect how it contributes to your application’s stability score.

User

The current user information.

@event.SetUser("3", "bugs.nag@bugsnag.com", "Bugs Nag");

null can be used as a parameter value to clear the user attribute.