The Bugsnag
client object has many configuration options that can be set to customize the content of events and sessions and how they are sent.
This documentation is for version 7+ of the BugSnag JavaScript notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.
Configuration options can be set by creating a configuration object and passing it into Bugsnag.start
:
Bugsnag.start({
apiKey: 'YOUR_API_KEY',
appVersion: '1.0.0-alpha'
})
apiKey
The API key used for events sent to BugSnag.
Bugsnag.start('API_KEY')
Bugsnag.start({ apiKey: 'API_KEY' })
You can find your API key in Project Settings from your BugSnag dashboard.
appType
If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.
This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appType
s.
Bugsnag.start({ appType: 'client' })
The default appType
in the browser is "browser"
.
appVersion
The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally BugSnag can re-open closed errors if a later version of the app has a regression.
Bugsnag.start({ appVersion: '4.10.0' })
autoDetectErrors
By default, we will automatically notify BugSnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.
Bugsnag.start({ autoDetectErrors: false })
Setting autoDetectErrors
to false
will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes
.
autoTrackSessions
By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.
Bugsnag.start({ autoTrackSessions: false })
BugSnag will automatically report a session each time:
history.pushState()
or history.replaceState()
collectUserIp
By default the IP address of the user whose browser reported an error will be collected and displayed in the request tab. If you want to prevent IPs from being stored, set this option to false
.
Bugsnag.start({ collectUserIp: false })
Note that if you prevent collecting the user IP, we strongly suggest that you provide a user ID. See the removing IP address section for more info.
context
The “context” is a string that indicates what the user was doing when an error occurs and is given high visual prominence in the dashboard. Set an initial context that you want to send with events – see Setting context for more information.
By default, BugSnag sets the context for each report to window.location.pathname
. If the pathname is not useful to you in tracking down errors, you can set it to something else.
Bugsnag.start({ context: 'ctx-id-1234' })
enabledBreadcrumbTypes
By default BugSnag will automatically add breadcrumbs for common application events whilst your application is running. Set this option to configure which of these are enabled and sent to BugSnag.
Bugsnag.start({
enabledBreadcrumbTypes: ['error', 'log', 'navigation', 'request', 'user']
})
Automatically captured breadcrumbs can be disabled by providing an empty array in enabledBreadcrumbTypes
.
Bugsnag.start({ enabledBreadcrumbTypes: [] })
The following automatic breadcrumb types can be enabled:
error
breadcrumbs are left when an error event is sent to the BugSnag API.
log
breadcrumbs are left when messages are written to the console.
Wrapping console methods to leave breadcrumbs has the side effect of messing with line numbers in log messages. Therefore when releaseStage='development'
console breadcrumbs are disabled.
navigation
breadcrumbs are left on page loads, DOMContentLoaded
events, pushState
/replaceState
calls, and popstate
/hashchange
events.
request
breadcrumbs are left for network requests initiated via the XMLHttpRequest
constructor and fetch()
calls. Metadata includes HTTP method, request URL and status code (if available).
user
breadcrumbs are left when the user clicks/touches the page.
enabledErrorTypes
BugSnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.
Bugsnag.start({
enabledErrorTypes: {
unhandledExceptions: false,
unhandledRejections: true
}
})
Setting autoDetectErrors
to false
will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes
.
enabledReleaseStages
By default, BugSnag will be notified of events that happen in any releaseStage
. Set this option if you would like to change which release stages notify BugSnag.
Bugsnag.start({ enabledReleaseStages: [ 'production', 'staging' ] })
endpoints
By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.
If you are using BugSnag On-premise you’ll need to set these to your Event Server
and Session Server endpoints. If the notify
endpoint is set but the sessions
endpoint is not, session tracking
will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.
Bugsnag.start({
endpoints: {
notify: 'https://bugsnag-notify.example.com',
sessions: 'https://bugsnag-sessions.example.com'
}
})
featureFlags
Declare feature flag and experiment usage.
Bugsnag.start({
featureFlags: [
{ name: 'Checkout button color', variant: 'Blue' },
{ name: 'Special offer', variant: 'Free Coffee' },
{ name: 'New checkout flow' },
]
})
See the Feature flags & experiments guide for more information.
generateAnonymousId
An anonymous ID is generated and persisted in local storage so that the user stability score can be calculated. Use this option to disable generation and storage of this ID and the user stability feature.
Bugsnag.start({ generateAnonymousId: false })
logger
By default, log messages from the BugSnag JavaScript library are prefixed with [bugsnag]
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
Bugsnag.start({ logger: null })
// supply a custom logger
var myCustomLogger = {
debug: function () {},
info: function () {},
warn: function () {},
error: function () {}
}
Bugsnag.start({ logger: myCustomLogger })
maxBreadcrumbs
Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.
By default, 25 breadcrumbs are stored; this can be amended up to a maximum of 100.
Bugsnag.start({ maxBreadcrumbs: 40 })
maxEvents
Configure the maximum number of events that can be sent per page. The count is reset each time the location changes via pushState
/replaceState
. The default value is 10
and the maximum allowed value is 100
.
Bugsnag.start({ maxEvents: 100 })
You can use Bugsnag.resetEventCount()
to reset the page event count and so allow further events to be sent. This might be useful if your application presents new views without triggering location change events.
metadata
Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.
Bugsnag.start({
metadata: {
company: {
name: 'Acme Co.',
country: 'uk'
}
}
})
The top-level keys of the supplied map are section names that are displayed as tabs in the BugSnag dashboard.
onBreadcrumb
Add callbacks to modify or discard breadcrumbs before they are recorded — see Customizing breadcrumbs for more information.
Bugsnag.start({
onBreadcrumb: function (breadcrumb) {
if (breadcrumb.type === 'request') {
if (breadcrumb.metadata.request === '/home') return false
breadcrumb.metadata.request = stripQueryString(breadcrumb.metadata.request)
}
}
})
If log
breadcrumbs are enabled, do not log within an onBreadcrumb
callback to avoid an infinite loop.
onError
Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.
Bugsnag.start({
onError: function (event) {
// Adjust event here
}
})
onSession
Add callbacks to modify or discard sessions before they are sent to BugSnag — see Capturing sessions for more information.
Bugsnag.start({
onSession: function (session) {
var userId = getMyUserIdentifier() // a custom user resolver
session.setUser(userId)
}
})
plugins
Provide plugins for the client to use, along with any necessary arguments.
For example:
var Vue = require('vue')
var Bugsnag = require('@bugsnag/js')
var BugsnagPluginVue = require('@bugsnag/plugin-vue')
Bugsnag.start({
plugins: [ new BugsnagPluginVue(Vue) ]
})
redactedKeys
Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.
Any property whose key matches a redacted key will be filtered and replaced with [REDACTED]
. By default, any key that contains “password” will be redacted. Be aware that if you set this configuration option, it will replace the default, so you may want to replace “password” in your own set if you want to filter that.
The array can include both strings and regexes.
Bugsnag.start({
redactedKeys: [
'access_token', // exact match: "access_token"
/^password$/i, // case-insensitive: "password", "PASSWORD", "PaSsWoRd"
/^cc_/ // prefix match: "cc_number" "cc_cvv" "cc_expiry"
]
})
releaseStage
Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).
Bugsnag.start({ releaseStage: 'staging' })
By default, if the URL contains localhost
this is set to development
. The default value in all other circumstances is production
.
If you want to use the NODE_ENV
environment variable from your build, use one of the following plugins appropriate for your bundler:
webpack.DefinePlugin
Envify
rollup-plugin-replace
And then set the option:
Bugsnag.start({ releaseStage: process.env.NODE_ENV })
trackInlineScripts
By default, BugSnag wraps every source of asynchronous execution in order to reliably track errors from inline scripts and include the surrounding code. To disable this behaviour, set this option to false
. Errors will still be reported from inline scripts, but they will not include any surrounding code.
Bugsnag.start({ trackInlineScripts: false })
user
Set global user data that you want to send with all captured events – see Adding user data for more information.
Bugsnag.start({
user: {
id: '3',
name: 'Bugs Nag',
email: 'bugs.nag@bugsnag.com'
}
})