Configuration options

BugSnag has many configuration options that can be set to customize the content of events and sessions and how they are sent.

Setting configuration options

Setting configuration in Unreal Editor

Most configuration options can be configured through the Unreal Editor, in the Project Settings window:

Settings configured this way are persisted in your project’s Config/DefaultEngine.ini file, which can also be edited directly:

[/Script/Bugsnag.BugsnagSettings]
bStartAutomaticallyAtLaunch=True
ApiKey=YOUR-API-KEY
bAutoTrackSessions=False
SendThreads=UnhandledOnly
MaxBreadcrumbs=100

The “Start Automatically” option is enabled by default and will start BugSnag recording events and sessions when the app is launched, provided your API key has also been set.

Setting configuration in code

You can further configure BugSnag by loading the FBugsnagConfiguration object and modifying it before starting BugSnag manually:

TSharedPtr<FBugsnagConfiguration> Configuration = FBugsnagConfiguration::Load();
if (Configuration.IsValid())
{
    Configuration->SetAppVersion(FString(TEXT("1.0.0-alpha")));
    UBugsnagFunctionLibrary::Start(Configuration.ToSharedRef());
}

When started in this way, any values set in your Project Settings will be applied unless overridden or augmented in code.

Available options

API Key

The API key used for events sent to BugSnag.

TSharedRef<FBugsnagConfiguration> Configuration = FBugsnagConfiguration::Load();
Configuration->SetApiKey(TEXT("YOUR-API-KEY"));

You can find your API key in Project Settings from your BugSnag dashboard.

App Hang Threshold

Enables reporting of non-fatal app hangs (see iOS guide) from which your app recovered before being terminated by the user or the iOS watchdog.

By default this is set to the constant FBugsnagConfiguration::AppHangThresholdFatalOnly, meaning that an error will only be sent to BugSnag if your app hang is fatal.

// Configure an app hang threshold to enable non-fatal app hangs
Configuration->SetAppHangThresholdMillis(5000);

App Type

If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.

This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appTypes.

Configuration->SetAppType(FString(TEXT("lite")));

App Version

The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally BugSnag can re-open closed errors if a later version of the app has a regression.

BugSnag will automatically determine your app’s version. On Android, the versionName field from your app’s manifest file is used. On iOS and macOS, CFBundleShortVersionString from Info.plist is used.

If you’d like to override this you can set the App Version configuration option:

Configuration->SetAppVersion(FString(TEXT("1.2.3-alpha")));

Auto Detect Errors

By default, we will automatically notify BugSnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.

Configuration->SetAutoDetectErrors(false);

Auto Track Sessions

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

Configuration->SetAutoTrackSessions(false);

If you want control over what is deemed a session, you can switch off the automatic session tracking option and manage the session manually. See Capturing sessions for more information.

Auto Upload Symbol Mapping Files

Automatically upload Android mapping files for showing full file paths and line numbers in events. This setting is enabled by default.

See Showing full stacktraces for more information on mapping files.

Bundle Version

The bundle version of the application.

We’ll automatically set this from the CFBundleVersion value in your Info.plist file. If you’d like to override this you can set the Bundle Version configuration option:

Configuration->SetBundleVersion(FString(TEXT("3.22.0")));

Context

The “context” is a string that indicates what the user was doing when an error occurs and is given high visual prominence in the dashboard. Set an initial context that you want to send with events – see Setting context for more information.

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

Discard Classes

Allows you to specify which events should be automatically discarded based on their errorClass.

Configuration->SetDiscardClasses({TEXT("java.net.UnknownHostException"), TEXT("SIGPIPE")});

Enabled Breadcrumb Types

By default BugSnag will automatically add breadcrumbs for common application events whilst your application is running. Set this option to configure which of these are enabled and sent to BugSnag.

Configuration->SetEnabledBreadcrumbTypes(
    EBugsnagEnabledBreadcrumbTypes::Navigation |
    EBugsnagEnabledBreadcrumbTypes::Request);

Automatically captured breadcrumbs can be disabled as follows:

Configuration->SetEnabledBreadcrumbTypes(EBugsnagEnabledBreadcrumbTypes::None);

The following automatic breadcrumb types can be enabled:

Captured errors

Error breadcrumbs (EBugsnagEnabledBreadcrumbTypes::Error) are left when an error event is sent to the BugSnag API.

Navigation changes

Navigation breadcrumbs (EBugsnagEnabledBreadcrumbTypes::Navigation) are left for navigation-related notifications to track the user’s journey in the app.

State changes

State breadcrumbs (EBugsnagEnabledBreadcrumbTypes::State) are left for system broadcast events. For example: network connectivity changes, orientation changes, etc. See Automatically captured data for more information.

User interaction

User breadcrumbs (EBugsnagEnabledBreadcrumbTypes::User) are left when the user performs certain system operations. See Automatically captured data for more information.

Enabled Error Types

BugSnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.

FBugsnagErrorTypes EnabledErrorTypes; // All types are enabled by default
EnabledErrorTypes.bANRs = false;
EnabledErrorTypes.bAppHangs = false;
EnabledErrorTypes.bCrashes = false;
EnabledErrorTypes.bOOMs = false;
EnabledErrorTypes.bThermalKills = false;
Configuration->SetEnabledErrorTypes(EnabledErrorTypes);

Enabled Release Stages

By default, BugSnag will be notified of events that happen in any releaseStage. Set this option if you would like to change which release stages notify BugSnag.

Configuration->SetEnabledReleaseStages({TEXT("beta"), TEXT("prod")});

Endpoints

Control where data from BugSnag will be sent.

If you are using BugSnag On-premise you’ll need to set these to match your server configuration.

Your Releases and Symbol File Upload endpoints are required to enable automatic upload of Android mapping files and release information.

The Notify and Session endpoints are used at runtime by your app and can also be set in code:

Configuration->SetEndpoints(
    TEXT("https://notify.example.com"),
    TEXT("https://sessions.example.com"));

If the Notify endpoint is set but the Sessions endpoint is not, session tracking will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.

Feature Flags

AddFeatureFlag

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

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

AddFeatureFlags

Declare multiple feature flags or experiments.

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

If AddFeatureFlags is called again, the new data will be merged with any existing feature flags with the newer variant values taking precedence.

ClearFeatureFlag

Remove a single feature flag or experiment.

Configuration->ClearFeatureFlag(TEXT("Checkout button color"));

ClearFeatureFlags

Remove all feature flags and experiments.

Configuration->ClearFeatureFlags();

See the Feature flags & experiments guide for more information.

Launch Duration

The amount of time (in milliseconds) after starting BugSnag that should be considered part of the app’s launch.

By default this value is 5000 milliseconds.

Configuration->SetLaunchDurationMillis(0);

// Once your app has finished launching;
UBugsnagFunctionLibrary::MarkLaunchCompleted();

Events that occur during app launch will have their app.isLaunching property set to true.

Setting this to 0 will cause BugSnag to consider the app to be launching until MarkLaunchCompleted() has been called. See Identifying crashes at launch for further information.

Max Breadcrumbs

Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.

By default, 50 breadcrumbs are stored; this can be amended up to a maximum of 500.

Configuration->SetMaxBreadcrumbs(75);

For crashes on Android, the maximum number of breadcrumbs is fixed at 50.

Max Persisted Events

Sets the maximum number of events which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest events will be deleted.

By default, 32 events are stored.

Configuration->SetMaxPersistedEvents(50);

Max Persisted Sessions

Sets the maximum number of sessions which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest sessions will be deleted.

By default, 128 sessions are stored.

Configuration->SetMaxPersistedSessions(50);

Max String Value Length

The maximum length of a string in metadata. To help avoid excessive event payload sizes, any strings exceeding this length will be truncated.

This limit defaults to 10,000 characters.

Configuration->SetMaxStringValueLength(5000);

Metadata

Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.

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);

You can also clear previously set metadata as follows:

Configuration->ClearMetadata(TEXT("account"));
// or
Configuration->ClearMetadata(TEXT("account"), TEXT("name"));

On Breadcrumb Callbacks

Add callbacks to modify or discard breadcrumbs before they are recorded — see Customizing breadcrumbs for more information.

Configuration->AddOnBreadcrumb([](TSharedRef<IBugsnagBreadcrumb> Breadcrumb)
{
    if (Breadcrumb->GetMessage() == TEXT("Noisy breadcrumb"))
    {
        return false; // ignore the breadcrumb
    }
    else
    {
        return true; // capture the breadcrumb
    }
});

On Send Error Callbacks

Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.

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;
});

On Session Callbacks

Add callbacks to modify or discard sessions before they are sent to BugSnag — see Capturing sessions for more information.

Configuration->AddOnSession([](TSharedRef<IBugsnagSession> Session)
{
    FString UserId = GetMyUserIdentifier(); // a custom user resolver
    Session->SetUser(UserId);
    return true; // return false to discard
});

Persistence Directory

Sets the directory where BugSnag data, such as event and session payloads, are cached on disk. User information is also persisted here if the Persist User configuration option is true.

Configuration->SetPersistenceDirectory(FString(TEXT("/my-custom-dir")));

The default directory for this property is Android’s cache directory.

Persist User

Set whether or not BugSnag should persist user information between application launches.

Configuration->SetPersistUser(false);

If enabled then any user information set will be re-used until the user information is removed manually by calling SetUser with null arguments.

Project Packages

Sets which package names BugSnag should consider as a part of the running application. We mark stacktrace lines as in-project if they originate from any of these packages and this allows us to improve the visual display of the stacktrace on the dashboard.

By default this is set to the package from which you initialized BugSnag.

Redacted Keys

Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.

Any property whose key matches a redacted key will be filtered and replaced with [REDACTED]. By default, any key that contains “password” will be redacted. Be aware that if you set this configuration option, it will replace the default, so you may want to replace “password” in your own set if you want to filter that.

Configuration->SetRedactedKeys({TEXT("password"), TEXT("credit_card_number")});

By default, RedactedKeys is set to "password"

Release Stage

Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).

Configuration->SetReleaseStage(FString(TEXT("testing")));

This is automatically configured by the notifier to be “production” if the app is built with Shipping configuration, otherwise it will be set to “development”.

You can control whether events are sent for specific release stages using the Enabled Release Stages configuration option.

Send Launch Crashes Synchronously

Determines whether launch crashes should be sent synchronously whilst BugSnag starts.

If this option is enabled and the previous run terminated due to a crash during app launch, BugSnag will block the calling thread when it starts for up to 2 seconds while the crash report is sent.

This behavior is enabled by default.

// To prevent sending launch crashes synchronously
Configuration->SetSendLaunchCrashesSynchronously(false);

Send Threads

Controls whether we should capture and serialize the state of all threads at the time of an exception.

Configuration->SetSendThreads(EBugsnagSendThreadsPolicy::UnhandledOnly);

By default this option is set to EBugsnagSendThreadsPolicy::All. This can be set to EBugsnagSendThreadsPolicy::Never to disable the sending of threads entirely or EBugsnagSendThreadsPolicy::UnhandledOnly to only send threads for unhandled errors.

Start Automatically

Automatically start BugSnag recording events and sessions when the game is launched, provided an API key is specified in Project Settings. This setting is enabled by default.

Telemetry

Internal errors

Internal errors are sent when an error is detected within BugSnag, for example when a crash report cannot be processed.

To prevent these from being sent:

FBugsnagTelemetryTypes TelemetryTypes;
TelemetryTypes.bInternalErrors = false;
Configuration->SetTelemetry(TelemetryTypes);

Usage

Usage telemetry helps us improve BugSnag by providing information on how you are configuring the SDK. We record:

• when your config differs from the defaults
• BugSnag functionality utilized

We collect only bools, ints and enums. We do not collect any information personal to you or your users. The information is sent as part of error events; there is no additional network call made.

To prevent this from being sent:

FBugsnagTelemetryTypes TelemetryTypes;
TelemetryTypes.bUsage = false;
Configuration->SetTelemetry(TelemetryTypes);

User

Set global user data that you want to send with all captured events – see Adding user data for more information.

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

Version Code

We’ll automatically pull the versionCode field from your app manifest file. If you’d like to override this you can set this option manually.

Configuration->SetVersionCode(55);