Configuration options

Discover configuration options to customize your BugSnag integration.

Setting configuration options

Setting configuration in the Unity Editor

Most configuration options can be configured through the Unity Editor, in the BugSnag Configuration window:

The “Start Automatically” option is enabled by default and will start sending performance data just before the first scene is loaded, provided your API key has also been set.

If you are using the BugSnag Error Monitoring SDK, the API key and other common configuration options can either be shared or set separately.

Setting configuration in code

To set configuration options in code, first ensure the “Start Automatically” project setting is disabled in the BugSnag Performance Configuration window. Then create a PerformanceConfiguration object, initialized from the Unity Editor, which can then be overridden in code:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.ReleaseStage = "Production";
BugsnagPerformance.Start(config);

If you do not wish to use the Unity Editor configuration at all, simply create a PerformanceConfiguration object using the object constructor, passing in your API key.

Available options

 API key

The API key used for performance data sent to BugSnag.

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.ApiKey = "YOUR-API-KEY";
BugsnagPerformance.Start(config);

 App version information

Setting your app’s version information in configuration allows you to see performance data for a specific release.

BugSnag captures this automatically from your Unity player settings, but it can be overridden in configuration if required:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.AppVersion = "5.3.55";
config.BundleVersion = "5.3.55.2";
config.VersionCode = 55;
BugsnagPerformance.Start(config);

Auto instrumentation

The instrumentation added to your app to capture measurements can be disabled entirely using the following configuration options:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.AutoInstrumentAppStart = AutoInstrumentAppStartSetting.OFF;
BugsnagPerformance.Start(config);

You can control the point it is ended directly by setting the configuration to .START_ONLY and calling BugsnagPerformance.ReportAppStarted() yourself.

Custom attribute limits

The following configuration options can be used to increase the size of custom attribute data that can be stored in each span:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.AttributeCountLimit = 200;
config.AttributeStringValueLimit = 5000;
config.AttributeArrayLengthLimit = 5000;
BugsnagPerformance.Start(config);

The number of attributes is limited to 128 by default and subsequent attributes are dropped. The limit can be increased up to 1000.

Individual string values are limited to 1024 by default and array values to 1000 with excess characters and elements being truncated. These limits can both be increased up to 10,000.

The key used for the attribute has a fixed limit of 1024. Attributes with a longer key will be dropped.

Endpoint

By default we will send trace and span data to the bugsnag.com web service address for traces.

If you are using BugSnag On-premise you’ll need to set this to your Trace Server endpoint.

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.Endpoint = "https://otlp.example.com/v1/traces";
BugsnagPerformance.Start(config);

Network request callback

If you are using the BugsnagUnityWebRequest wrapper, you can control which network requests are captured and sanitize the URL string sent to your BugSnag dashboard using the NetworkRequestCallback configuration option. The network request span will be transmitted to BugSnag using the url in the returned object, or will not be sent at all if the url is set to null:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.NetworkRequestCallback = requestInfo => {
    if (requestInfo.Url.Contains("no-track.com"))  // Don't send network request span
    {
        return null;
    } 
    if (Regex.IsMatch(requestInfo.Url, @"account\/[0-9]+"))  // Remove user ID
    {
        requestInfo.Url = Regex.Replace(requestInfo.Url,
                                        @"account\/[0-9]+",
                                        @"account/[account-id]");
    }
    return requestInfo;
};

Release stages

Setting a release stage in your configuration allows you to filter performance data by different stages of the application release process (development, production, etc) in the BugSnag dashboard. The release stage is automatically set to “production”, unless the app is built with debug enabled in which case it will be set to “development”.

If you wish to override this, you can do so by setting the ReleaseStage configuration option:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.ReleaseStage = "testing";
BugsnagPerformance.Start(config);

You can also limit which builds send performance data by setting the EnabledReleaseStages configuration option:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.EnabledReleaseStages = new [] { "production", "development", "testing" };
BugsnagPerformance.Start(config);

By default, performance data will be sent for all stages.

Sampling probability

By default, the SDK uses BugSnag’s sampling mechanism to spread the span quota in your plan over a month with a constantly adjusted probability that a given user interaction will be recorded. If you are controlling the sampling yourself – such as using an OTel Collector – the sampling probability can be fixed to a value between 0 and 1 to send a fixed proportion.

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.SamplingProbability = 1.0;
BugsnagPerformance.Start(config);

When a sampling probability is set explicitly, the captured spans will be counted towards your unmanaged quota. See the Sampling of performance data guide for details.

Service name

A readable identifier for your app to populate the service.name attribute in captured spans.

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.ServiceName = "ZippyApp";
BugsnagPerformance.Start(config);

If you are using a collector, you must configure a service name mapping to match spans from your application to the correct project in BugSnag. By default, the service name is set to the application identifier (if available) or the product name. Otherwise the service name is set to ‘unknown_service’.

Span callbacks

Callback functions can be registered to tranform and filter spans before they are sent to BugSnag:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.AddOnSpanEnd(@span => {
    @span.SetAttribute("device.locale", "en-US");
    return true;
})
BugsnagPerformance.Start(config);

You can perform any operation on the span during the callback, but you should avoid ending the span from inside the callback to prevent a recursive loop.

The return value from the callback determines whether the span will be sent. When a span is discarded, it doesn’t affect other spans in the trace. Therefore returning false in your callback will result in an incomplete trace being shown in your dashboard. In general we recommend returning true in all cases to allow the built-in probability-based sampling to run without potential biases in the aggregated data.

Trace propagation

Enabling this option sends OpenTelemetry compatible trace context headers on network requests made to your servers.

If you are using the BugsnagUnityWebRequest wrapper this is enabled by setting the TracePropagationUrls configuration option to control which URLs should include the header:

var config = BugsnagPerformanceSettingsObject.LoadConfiguration();
config.TracePropagationUrls = new Regex[] {
    new Regex("^(http(s)?(://))?(www\\.)?example\\.com(/.*)?$") };
BugsnagPerformance.Start(config);

We only recommend sending this information to servers that are under your control and instrumented by OpenTelemetry. Once configured, you will be able to see full distributed traces in BugSnag.