Discover configuration options to customize your BugSnag integration.
Configuration options can be set by creating a configuration object and passing it into BugsnagPerformance.start:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
appVersion: '1.0.0-alpha'
})
The API key used for performance data sent to BugSnag.s
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
appVersion: '4.10.0'
})
You can find your API key in Project Settings from your BugSnag dashboard.
Setting your app’s version in configuration allows you to see performance data for a specific release:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
appVersion: '4.10.0'
})
The instrumentation added to your app to capture measurements can be disabled entirely using the following configuration options:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
autoInstrumentFullPageLoads: false,
autoInstrumentRouteChanges: false,
autoInstrumentNetworkRequests: false
})
A page is considered to have loaded when it has “settled”, by which we mean no recent DOM mutations or network requests have been made. If you wish to disregard particular URLs from this calculation, use the settleIgnoreUrls configuration option. The URLs can be either a string or RegExp:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
settleIgnoreUrls: ['https://my.excluded/path', /.*my\.excluded\.domain.*/]
})
The following configuration options can be used to increase the size of custom attribute data that can be stored in each span:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
attributeCountLimit: 200,
attributeStringValueLimit: 5000,
attributeArrayLengthLimit: 5000
})
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.
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.
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
endpoint: "https://otlp.example.com/v1/traces"
})
If you use the BugSnag error SDK for JavaScript, you can link performance and error data to see BugSnag errors in your distributed traces.
Making sure to call the start method of the error SDK first, pass in the bugsnag field with a reference to the BugSnag error client which is accessed via the Bugsnag global in most cases:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
bugsnag: Bugsnag
})
See Error linking for further information.
By default, log messages from the BugSnag SDK are prefixed with [bugsnag-performance] and output to the console (if the platform has a useful console object). You can supply your own logger instead, or switch off logging completely by setting logger: null.
If you supply a logger, it must have the following methods: debug, info, warn and error.
// switch off logging
BugsnagPerformance.start({ logger: null })
// supply a custom logger
var myCustomLogger = {
debug (message: string) { console.debug(message) },
info (message: string) { console.info(message) },
warn (message: string) { console.warn(message) },
error (message: string) { console.error(message) }
}
BugsnagPerformance.start({ logger: myCustomLogger })
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 null is returned:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
networkRequestCallback: (requestInfo) => {
// Don't send network request span
if (requestInfo.url.includes('no-track.com')) return null
// Remove user ID
if (requestInfo.type == 'fetch' && requestInfo.url.matches(/account\/[0-9]+/)) {
requestInfo.url = requestInfo.url.replace(/account\/[0-9]+/, 'account/[account-id]')
}
return requestInfo
}
})
The type field denotes the type of request, as defined by the PerformanceResourceTiming.initiatorType property.
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:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
releaseStage: 'testing'
})
You can also limit which builds send performance data by setting the enabledReleaseStages configuration option:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
enabledReleaseStages: ['production', 'development', 'testing']
})
By default, performance data will be sent for all stages.
For finer control of the route names used for Page Load and Route Change spans, a customized implementation of RoutingProvider can be set in configuration:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
routingProvider: new MyCustomRoutingProvider()
})
For more details see Instrumenting page loads & route changes.
By default, all spans will contain the URL, title and referrer of the page on which it was created. If you do not wish to capture one or more of these fields, they can be disabled using the sendPageAttributes configuration option:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
sendPageAttributes: {
url: false,
title: false,
referrer: false
}
})
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.
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
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.
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
serviceName: 'ZippyApp'
})
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 “unknown_service”.
Callback functions can be registered to tranform and filter spans before they are sent to BugSnag:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
onSpanEnd: [(span) => {
span.setAttribute('device.locale', 'en-US ')
return 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.
This is enabled by setting the propagateTraceContext field of the Network Request Callback object for the requests your want to propagate:
BugsnagPerformance.start({
apiKey: 'YOUR_API_KEY',
networkRequestCallback: (networkRequestInfo) => {
networkRequestInfo.propagateTraceContext =
networkRequestInfo.url?.startsWith(window.origin)
return networkRequestInfo
}
})
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.