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.

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:

Configuration->AddOnSendError([](TSharedRef<IBugsnagEvent> Event)
{
    Event->AddMetadata(TEXT("account"), TEXT("name"), TEXT("Acme Co."));
    Event->AddMetadata(TEXT("account"), TEXT("paying_customer"), true);

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

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.

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:

Configuration->AddOnSendError([](TSharedRef<IBugsnagEvent> Event)
{
    return !UserHasOptedOut();
});

Global metadata

If you have metadata that is applicable to all captured events, it can be set globally on the UBugsnagFunctionLibrary 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 an FJsonObject:

Configuration->AddMetadata(TEXT("account"), TEXT("name"), TEXT("Acme Co."));

TSharedRef<FJsonObject> Basket = MakeShared<FJsonObject>();
Basket->SetStringField(TEXT("delivery"), TEXT("express"));
Basket->SetStringField(TEXT("sale"), TEXT("spring"));
Configuration->AddMetadata(TEXT("basket"), Basket);

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

UBugsnagFunctionLibrary::AddMetadata(TEXT("account"), TEXT("name"), TEXT("Acme Co."));
// ...
UBugsnagFunctionLibrary::ClearMetadata(TEXT("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:

Configuration->SetUser(
    FString(TEXT("3")), // User ID
    FString(TEXT("bugs.nag@bugsnag.com")),
    FString(TEXT("Bugs Nag")));

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

UBugsnagFunctionLibrary::SetUser(
    TEXT("3"), // User ID
    TEXT("bugs.nag@bugsnag.com"),
    TEXT("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:

Configuration->SetContext(FString(TEXT("InitialTutorialStep")));

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

UBugsnagFunctionLibrary::SetContext(TEXT("SecondTutorialStep"));

The IBugsnagEvent class

An IBugsnagEvent object represents an error captured by BugSnag and is available as a parameter on an event callback. The following methods are available on an IBugsnagEvent 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:

Event->SetApiKey(TEXT("YOUR-API-KEY"));

App

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

These values can be accessed and amended if necessary:

Event->GetApp()->SetAppVersion(FString(TEXT("1.2.3-alpha")));

Breadcrumbs

A list of breadcrumbs leading up to the event can be found in Event.Breadcrumbs. See the Breadcrumb class for details of the data available.

These values can be accessed and amended if necessary:

Event->GetBreadcrumbs()[0]->SetMessage(TEXT(""));

Context

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

Event->SetContext(FString(TEXT("SecondTutorialStep")));

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:

These values can be accessed and amended if necessary:

Event->GetDevice()->SetLocale(FString(TEXT("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:

Event->GetErrors()[0]->SetErrorClass(TEXT("MyErrorClass"));

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

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

TSharedRef<IBugsnagError> Error = Event->GetErrors()[0];
TArray<TSharedRef<IBugsnagStackframe>> Stacktrace = Error->GetStacktrace();
Stacktrace.RemoveAt(0);
Error->SetStacktrace(Stacktrace);

Feature Flags

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

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

Event->AddFeatureFlag(TEXT("Checkout button color"), FString(TEXT("Blue")));
Event->AddFeatureFlag(TEXT("New checkout flow"));

Declare multiple feature flags or experiments.

Event->::AddFeatureFlags({
    FBugsnagFeatureFlag(TEXT("Checkout button color"), FString(TEXT("Blue"))),
    FBugsnagFeatureFlag(TEXT("Special offer"), FString(TEXT("Free Coffee"))),
    FBugsnagFeatureFlag(TEXT("New checkout flow"))
});

Remove a single feature flag or experiment.

Event->ClearFeatureFlag(TEXT("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
FString GroupingHash = TEXT("f8803769f3e293dfcabdb6dec5100b8c52c6ae6b");
Event->SetGroupingHash(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(TEXT("account"), TEXT("name"), TEXT("Acme Co."));
Event->AddMetadata(TEXT("account"), TEXT("paying_customer"), true);
Event->AddMetadata(TEXT("account"), TEXT("roles"),
    MakeShared<FJsonValueArray>((TArray< TSharedPtr<FJsonValue> >){
        MakeShared<FJsonValueString>(TEXT("basic")),
        MakeShared<FJsonValueString>(TEXT("admin"))}));

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

TSharedRef<FJsonObject> Basket = MakeShared<FJsonObject>();
Basket->SetStringField(TEXT("delivery"), TEXT("express"));
Basket->SetStringField(TEXT("sale"), TEXT("spring"));
Event->AddMetadata(TEXT("basket"), Basket);

Metadata set on the event will be combined with global metadata set on the UBugsnagFunctionLibrary, 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(TEXT("account"));
// or
Event->ClearMetadata(TEXT("account"), TEXT("name"));

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

TSharedPtr<FJsonObject> Metadata = Event->GetMetadata(TEXT("account"));
// or
TSharedPtr<FJsonValue> AccountName = Event->GetMetadata(TEXT("account"), TEXT("name"));

Severity

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

Event->SetSeverity(EBugsnagSeverity::Warning);

Threads

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

Event->GetThreads()[0]->SetName(TEXT("New name"));

Unhandled

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

Event->SetUnhandled(true);

User

The current user information.

Event->SetUser(
    FString(TEXT("3")), // User ID
    FString(TEXT("bugs.nag@bugsnag.com")),
    TOptional<FString>());

TOptional<FString>() can be used as a parameter value to clear the user attribute.