Configuration options

Discover configuration options for your BugSnag integration.

Setting configuration options

Many configuration options can be set in your App Manifest (AndroidManifest.xml):

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.API_KEY"
             android:value="your-api-key-here"/>
</application>

With your settings in the app manifest file, BugSnag can simply be started using:

BugsnagPerformance.start(this);

BugsnagPerformance.start(this)

Alternatively, configuration options can be specified in code by passing configuration into BugsnagPerformance.start:

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setAppVersion("1.0.0-alpha");
BugsnagPerformance.start(this, config);

val config = PerformanceConfiguration.load(this)
config.appVersion = "1.0.0-alpha"
BugsnagPerformance.start(this, config)

PerformanceConfiguration.load uses your app manifest to set initial configuration values, allowing you to augment and override the values before they are used to start BugSnag. You can use the PerformanceConfiguration constructor to avoid using the manifest file.

Available options

 API key

The API key used for performance data sent to BugSnag.

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.apiKey = "your-api-key-here";
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
config.apiKey = "your-api-key-here"
})

Or in the app manifest:

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.API_KEY"
             android:value="your-api-key-here"/>
</application>

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:

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.appVersion = "1.0.0-alpha";
config.versionCode = 55;
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
config.appVersion = "1.0.0-alpha"
config.versionCode = 55
})

By default, the app version and version code will be set automatically using android:versionName and android:versionCode from your app’s manifest file. They can also be set independently:

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.APP_VERSION"
             android:value="1.0.0-alpha"/>
  <meta-data android:name="com.bugsnag.performance.android.VERSION_CODE"
             android:value="55"/>
</application>

Auto instrumentation

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

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.autoInstrumentAppStarts = false;
config.autoInstrumentActivities = AutoInstrument.OFF;
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    autoInstrumentAppStarts = false
    autoInstrumentActivities = AutoInstrument.OFF
})

Or in the app manifest:

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.AUTO_INSTRUMENT_APP_STARTS"
             android:value="false"/>
  <meta-data android:name="com.bugsnag.performance.android.AUTO_INSTRUMENT_ACTIVITIES"
             android:value="false"/>
</application>

For control over which Activity and Fragment classes are measured when auto instrumentation is enabled, see the doNotAutoInstrument and doNotEndAppStart configuration options.

By default, the Activity load measurement will be ended when the onActivityPostResumed lifecycle callback is called. You can control the point it is ended directly by setting autoInstrumentActivities to AutoInstrument.START_ONLY and calling BugsnagPerformance.endViewLoadSpan yourself.

If you set autoInstrumentActivities to AutoInstrument.OFF you can instead send these measurements by calling BugsnagPerformance.startViewLoadSpan and endViewLoadSpan methods in the appropriate places in your app.

Do Not Auto Instrument

The doNotAutoInstrument configuration option can be used for more fine-grained control over which Activity and Fragment classes get instrumented. You can either add the @DoNotAutoInstrument annotation directly to the Activity or Fragment class or pass the fully-qualified class name(s) to the doNotAutoInstrument configuration option:

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.doNotAutoInstrument(new HashSet<Pattern>() {{
    add(ActivityToExclude.class);
}});
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    doNotAutoInstrument = setOf(ActivityToExclude::class.java)
})

Do Not End App Start

By default BugSnag will consider an app start to have ended upon the first Activity.onResume call. If you wish to consider specific Activities part of the app start period (for example a loading screen), and so prevent their onResume call from ending the app start, you can either add the @DoNotEndAppStart annotation directly to the Activity class or pass the fully-qualified class name(s) to the doNotEndAppStart configuration option:

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.doNotEndAppStart(new HashSet<Pattern>() {{
    add(ActivityToIncludeInAppStart.class);
}});
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    doNotEndAppStart = setOf(ActivityToIncludeInAppStart::class.java)
})

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.

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.endpoint("https://otlp.example.com/v1/traces");
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    endpoint = "https://otlp.example.com/v1/traces"
})

Or in the app manifest:

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.ENDPOINT"
             android:value="https://otlp.example.com/v1/traces"/>
</application>

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

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setNetworkRequestCallback(requestInfo -> {
    String url = requestInfo.getUrl();

    if (Uri.parse(url).getHost().equals("no-track.com")) {
        requestInfo.setUrl(null);
    } else if (url != null) {
        requestInfo.setUrl(url.replaceAll("/account/[0-9]+", "account/[account-id]"));
    }
});
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    networkRequestCallback = NetworkRequestInstrumentationCallback { requestInfo ->
        val url = requestInfo.url
        if (Uri.parse(url).host == "no-track.com") {
            requestInfo.url = null
        } else if (url != null) {
            requestInfo.url = url.replace(Regex("/account/[0-9]+"), "account/[account-id]")
        }
    }
})

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:

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setReleaseStage("testing");
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    releaseStage = "testing"
})

Or in the app manifest:

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.RELEASE_STAGE"
             android:value="testing"/>
</application>

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

PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setEnabledReleaseStages(Set.of("production", "development", "testing"));
BugsnagPerformance.start(config);

BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
    enabledReleaseStages = setOf("production", "development", "testing")
})

Or in the app manifest:

<application ...>
  <meta-data android:name="com.bugsnag.performance.android.ENABLED_RELEASE_STAGES"
             android:value="production,development,testing"/>
</application>

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