Discover configuration options for your BugSnag integration.
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>
Configuration options set in the com.bugsnag.android namespace will be applied to both BugSnag Performance and Error Monitoring libraries, where appropriate. You can also set configuration values based on build variants or product flavors, see Customizing by build setting in the Error Monitoring SDK docs.
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.
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.
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>
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.
The following configuration options can be used to increase the size of custom attribute data that can be stored in each span:
PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.attributeCountLimit = 200;
config.attributeStringValueLimit = 5000;
config.attributeArrayLengthLimit = 5000;
BugsnagPerformance.start(config);
BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
attributeCountLimit = 200
attributeStringValueLimit = 5000
attributeArrayLengthLimit = 5000
})
Or in the app manifest:
<application ...>
<meta-data android:name="com.bugsnag.performance.android.ATTRIBUTE_COUNT_LIMIT"
android:value="200"/>
<meta-data android:name="com.bugsnag.performance.android.ATTRIBUTE_STRING_VALUE_LIMIT"
android:value="5000"/>
<meta-data android:name="com.bugsnag.performance.android.ATTRIBUTE_ARRAY_LENGTH_LIMIT_KEY"
android:value="5000"/>
</application>
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.
Care should be taken to avoid adding excessive data as oversized span payloads are rejected by the BugSnag API. If the payload limits are being reached for your project, a warning will be displayed on your Performance dashboard.
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)
})
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)
})
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.
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>
When using the BugSnag Okhttp module, 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]")
}
}
})
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.
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.
PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setSamplingProbability(1.0);
BugsnagPerformance.start(config);
BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
samplingProbability = 1.0
})
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.
A readable identifier for your app to populate the service.name attribute in captured spans.
PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setServiceName("ZippyApp");
BugsnagPerformance.start(config);
BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
serviceName = "ZippyApp"
})
Or in the app manifest:
<application ...>
<meta-data android:name="com.bugsnag.performance.android.SERVICE_NAME"
android:value="ZippyApp"/>
</application>
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 the package name of the app.
Callback functions can be registered to tranform and filter spans before they are sent to BugSnag:
PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.addOnSpanEndCallback(new OnSpanEndCallback() {
@Override
public boolean onSpanEnd(Span span) {
span.setAttribute("device.locale", "en-US");
return true;
}
});
BugsnagPerformance.start(config);
BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
addOnSpanEndCallback { span ->
span.setAttribute("device.locale", "en-US")
true
}
})
These callbacks can be executed with a high frequency, so care should be taken not to perform complex operations that will have a detrimental effect on performance. To aid diagnostics, the amount of time taken for the callbacks to run is captured in the bugsnag.span.callbacks_duration attribute and shown on the span details panel on the Performance dashboard.
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.
Enabling this option sends OpenTelemetry compatible trace context headers on network requests made to your servers.
If you are using the BugSnag Okhttp module this is enabled by setting the tracePropagationUrls configuration option to control which URLs should include the header:
PerformanceConfiguration config = PerformanceConfiguration.load(this);
config.setTracePropagationUrls(Set.of(
Pattern.compile("^(http(s)?(://))?(www\\.)?example\\.com(/.*)?$")));
BugsnagPerformance.start(config);
BugsnagPerformance.start(PerformanceConfiguration.load(this).apply {
tracePropagationUrls = setOf(
"""^(http(s)?(://))?(www\.)?example\.com(/.*)?$""".toPattern())
})
Or in the app manifest:
<application ...>
<meta-data android:name="com.bugsnag.performance.android.TRACE_PROPAGATION_URLS"
android:value="^(http(s)?(://))?(www\\.)?example\\.com(/.*)?$"/>
</application>
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.