Configuration options

Discover configuration options for your BugSnag integration.

Setting configuration options

Many configuration options can be set in your Info.plist file under the bugsnag key. These will be shared with the BugSnag Error Monitoring SDK, if in use.

Configuration options that are for the Performance SDK only – or whose value you require to be different for Performance – are located inside a performance sub-key:

Set the apiKey in your Info.plist

Or in XML:

<key>bugsnag</key>
<dict>
    <key>apiKey</key>
    <string>YOUR-API-KEY</string>
    <key>performance</key>
    <dict>
        <key>autoInstrumentAppStarts</key>
        <true/>
    </dict>
</dict>

The BugsnagPerformance client can then simply be started using:

[BugsnagPerformance start];

BugsnagPerformance.start()

Alternatively, configuration options can be specified in code by creating a BugsnagPerformanceConfiguration object and passing it to the client:

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.appVersion = @"1.0.0-alpha";
[BugsnagPerformance startWithConfiguration:config];

let config = BugsnagPerformanceConfiguration.loadConfig()
config.appVersion = "1.0.0-alpha"
BugsnagPerformance.start(with: config)

loadConfig uses your Info.plist file to set initial configuration values, allowing you to augment and override the values before they are used to start BugSnag. You can use the BugsnagConfiguration initializer with an API key to avoid using the properties file.

Available options

API key

The API key used for performance data sent to BugSnag.

let config = BugsnagPerformanceConfiguration.loadConfig()
config.apiKey = "YOUR-API-KEY";
BugsnagPerformance.start(with: config)

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.apiKey = @"YOUR-API-KEY";
[BugsnagPerformance startWithConfiguration:config];

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>apiKey</key>
    <string>YOUR-API-KEY</string>
</dict>

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

App version information

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

BugSnag captures the built-in values of CFBundleVersion and CFBundleShortVersionString as the app’s version and bundle version by default. This can be overridden in configuration if required:

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.appVersion = @"5.3.55";
config.bundleVersion = @"5.3.55.2";
[BugsnagPerformance startWithConfiguration:config];

let config = BugsnagPerformanceConfiguration.loadConfig()
config.appVersion = "5.3.55"
config.bundleVersion = "5.3.55.2"
BugsnagPerformance.start(configuration: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>appVersion</key>
    <string>5.3.55</string>
    <key>bundleVersion</key>
    <string>5.3.55.2</string>
</dict>

Auto instrumentation

By default we will measure your app’s startup time, view loading and network requests. These measurements can be disabled using the following configuration options:

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.autoInstrumentAppStarts = NO;
config.autoInstrumentViewControllers = NO;
config.autoInstrumentNetworkRequests = NO;
[BugsnagPerformance startWithConfiguration:config];

let config = BugsnagPerformanceConfiguration.loadConfig()
config.autoInstrumentAppStarts = false
config.autoInstrumentViewControllers = false
config.autoInstrumentNetworkRequests = false
BugsnagPerformance.start(configuration: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>performance</key>
    <dict>
        <key>autoInstrumentAppStarts</key>
        <false/>
        <key>autoInstrumentViewControllers</key>
        <false/>
        <key>autoInstrumentNetworkRequests</key>
        <false/>
    </dict>
</dict>

You can instead send these measurements by calling startViewLoadSpan and reportNetworkRequestSpan methods in the appropriate places in your app.

Endpoint

By default we will send trace and span data to otlp.bugsnag.com/v1/traces.

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

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.endpoint = @"https://otlp.example.com/v1/traces";
[BugsnagPerformance startWithConfiguration:config];

let config = BugsnagPerformanceConfiguration.loadConfig()
config.endpoint = "https://otlp.example.com/v1/traces"
BugsnagPerformance.start(configuration: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>apiKey</key>
    <string>YOUR-API-KEY</string>
    <key>performance</key>
    <dict>
        <key>endpoint</key>
        <string>https://otlp.example.com/v1/traces</string>
    </dict>
</dict>

Network request callback

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 nil:

config.networkRequestCallback = ^BugsnagPerformanceNetworkRequestInfo * _Nonnull(BugsnagPerformanceNetworkRequestInfo * _Nonnull info) {
    NSURL *url = info.url;

    if ([url.host isEqual: @"no-track.com"]) {
        info.url = nil;
        return info;
    }

    NSError *error = nil;
    NSRegularExpression *regex = [NSRegularExpression regularExpressionWithPattern:@"account/[0-9]+" options:NSRegularExpressionCaseInsensitive error:&error];
    if (error != nil) {
        return info;
    }
    NSString *urlString = info.url.absoluteString;
    NSString *newUrlString = [regex stringByReplacingMatchesInString:urlString
                                                          options:0
                                                            range:NSMakeRange(0, urlString.length) withTemplate:@"account/[account-id]"];
    info.url = [NSURL URLWithString:newUrlString];
    return info;
};

config.networkRequestCallback = { (info: BugsnagPerformanceNetworkRequestInfo) -> BugsnagPerformanceNetworkRequestInfo in
    let url = info.url!

    if (url.host() == "no-track.com") {
        info.url = nil
        return info
    }

    let urlString = url.absoluteString
    info.url = URL(string: urlString.replacing(/account\/[0-9]+/, with: "account/[account-id]"))
    return info
}

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:

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.releaseStage = @"testing";
[BugsnagPerformance startWithConfiguration:config];

let config = BugsnagPerformanceConfiguration.loadConfig()
config.releaseStage = "testing"
BugsnagPerformance.start(configuration: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>releaseStage</key>
    <string>testing</string>
</dict>

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

BugsnagPerformanceConfiguration *config = [BugsnagPerformanceConfiguration loadConfig];
config.enabledReleaseStages = [NSSet setWithArray:@[@"production", @"development", @"testing"]];
[BugsnagPerformance startWithConfiguration:config];

let config = BugsnagPerformanceConfiguration.loadConfig()
config.enabledReleaseStages = ["production", "development", "testing"]
BugsnagPerformance.start(configuration: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>enabledReleaseStages</key>
    <array>
        <string>production</string>
        <string>development</string>
        <string>testing</string>
    </array>
</dict>

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