This documentation is for version 6 of the BugSnag JavaScript notifier. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.
The object passed to bugsnag({ … })
can be used to configure and customize the behaviour of the library. Additionally, some properties of the client object returned by the bugsnag(…)
function can be set.
Configuration options should be set in addition to the API key:
var bugsnagClient = bugsnag({
apiKey: 'YOUR_API_KEY',
otherOption: value
})
agent
Supply an agent to manage the connections for sending error reports to BugSnag. You can use this option to supply a proxy agent if you need to send via proxy. See the proxy guide for more information.
The default value is undefined
which means that the https.globalAgent
will be used. Supplying agent: false
will mean that a new agent is created for every request (i.e. connections will not be reused at all).
bugsnag({ agent: false })
bugsnag({ agent: new ProxyAgent('http://my-proxy-url:3128') })
apiKey
Set your BugSnag API key. You can find your API key in your project settings from your BugSnag dashboard:
bugsnag('API_KEY')
bugsnag({ apiKey: 'API_KEY' })
appVersion
You should provide your application’s version number/identifier (if it has one). 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({ appVersion: '4.10.0' })
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({ appType: 'web_server' })
bugsnag({ appType: 'worker' })
bugsnag({ appType: 'websocket_server' })
bugsnag({ appType: 'mailer' })
These examples are just for illustration. BugSnag doesn’t set appType
by default, so it’s up to you if and how you use it.
autoBreadcrumbs
By default, BugSnag will collect various kinds of breadcrumbs. To switch all of these off, set the autoBreadcrumbs
option to false
:
bugsnag({ autoBreadcrumbs: false })
autoCaptureSessions
By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.
bugsnag({ autoCaptureSessions: false })
BugSnag will automatically report a session each time:
If you switch off automatic session tracking with the autoCaptureSessions
option, you can still send sessions manually by calling bugsnagClient.startSession()
when appropriate for your application.
autoNotify
By default, we will automatically notify BugSnag of any uncaught exceptions and unhandled promise rejections. If you want to stop this from happening, you can set autoNotify
to false:
bugsnag({ autoNotify: false })
beforeSend
To modify error reports before they are sent, or to prevent them from being sent at all, beforeSend
provides access the report data structure and the means to mutate or ignore it:
bugsnag({
beforeSend: function (report) {
// Adjust report here
}
})
beforeSend
callbacksWe recommend using the synchronous interface as shown above, but it is possible to provide an asynchronous beforeSend
callback using a Node-style error-first callback or a Promise.
Anything that can take a long time or cause subsequent errors should be discouraged – if this is a particularly catastrophic error then you want to avoid doing any work that might prevent the report from sending.
bugsnag({
beforeSend: report =>
new Promise((resolve, reject) => {
// doing some asynchronous work, resolving when done
resolve()
// if an error happened, you can reject the promise but this error won't
// prevent the report from being sent (or other callbacks from being run)
reject(err)
// to stop the report from being sent resolve with false
resolve(false)
// or call report.ignore()
report.ignore()
resolve()
})
}
})
bugsnag({
beforeSend: (report, cb) =>
// do some async work, calling cb(err, ignore?) when done
cb(null)
// if an error happens call cb(err) – this won't prevent
// the report from being sent
cb(err)
// prevent report from sending
cb(null, false)
// or
report.ignore()
cb(null)
}
})
For examples on how to modify reports and what is available on the report object, see customizing error reports.
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({
endpoints: {
notify: 'https://bugsnag-notify.example.com',
sessions: 'https://bugsnag-sessions.example.com'
}
})
filters
Filter out properties from the payloads that are sent to BugSnag using strings (for exact matches) and regexes (for pattern matching).
Use this option to ensure you don’t send sensitive data such as passwords, and credit card numbers to our servers. Any property whose key matches a provided string or regex in this array will be filtered and replaced with [Filtered]
.
By default, this array contains 'password'
. Be aware that if you supply a new value, it will replace the default, so include 'password'
in your own array if you want to filter that.
The array can include both strings and regexes.
bugsnag({
filters: [
'access_token', // exact match: "access_token"
/^password$/i, // case-insensitive: "password", "PASSWORD", "PaSsWoRd"
/^cc_/ // prefix match: "cc_number" "cc_cvv" "cc_expiry"
]
})
hostname
By default we will detect the device’s hostname with Node’s os.hostname()
. Otherwise you can set it yourself with this option.
bugsnag({ hostname: 'web1.example.com' })
logger
By default, the notifier’s log messages 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({ logger: null })
// supply a custom logger
var myCustomLogger = {
debug: function () {},
info: function () {},
warn: function () {},
error: function () {}
}
bugsnag({ logger: myCustomLogger })
maxBreadcrumbs
By default, up to 20 breadcrumbs will be sent along with each error report. You can optionally configure this up to a hard limit of 40.
bugsnag({ maxBreadcrumbs: 40 })
notifyReleaseStages
By default, we will notify BugSnag of exceptions that happen in any releaseStage
. If you would like to change which release stages notify BugSnag of errors you can set notifyReleaseStages
.
bugsnag({ notifyReleaseStages: [ 'production', 'staging' ] })
onUncaughtException
By default, when an unhandled exception occurs in Node, BugSnag keeps the process alive just long enough to send the error report before logging the error and exiting with a non-zero status code. This behaviour mimics what Node.js does by default.
If you want to do something else – for example, keeping the process alive slightly longer to close out any in-flight requests or database calls – you can use this option to supply your own behaviour.
bugsnag({
onUncaughtException: function (err, report) {
// error = the original error
// report = the BugSnag report object that got sent
}
})
onUnhandledRejection
By default, when an unhandled rejection occurs, BugSnag will send an error report, then print the error to the console. The process remains alive, as per Node’s current default behaviour.
If you want to do something else, you can use this option to supply your own behaviour.
bugsnag({
onUnhandledRejection: function (err, report) {
// error = the original error
// report = the BugSnag report object that got sent
}
})
Note: Node prints a warning saying that in future, unhandled promise rejections will cause the process to terminate. For this reason, it’s advisable to shut down the process when you get an unhandled rejection before this becomes the default.
projectRoot
By default this is the current working directory of the running process. Stack frame paths will be relative from this path.
bugsnag({ projectRoot: '/app' })
proxy
Note: This option was removed in @bugsnag/js@6.0.0
.
You can supply an HTTP/HTTPS proxy URL. The notifier will then send all notify and session payloads via this proxy address.
bugsnag({ proxy: 'https://my.proxy.xyz' })
releaseStage
If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage
that is reported to BugSnag.
bugsnag({ releaseStage: 'staging' })
If process.env.NODE_ENV
is set, it will be used as the releaseStage
. Otherwise the default value is production
.
sendCode
By default, BugSnag will load the surrounding code for each stackframe, if the location can be found on disk. You can switch off this behaviour using this option.
bugsnag({ sendCode: false })
client.app.version
If the version of the application is available when BugSnag is configured, it’s preferrable to set this in the appVersion
configuration option, but you can also set this as a property on the client:
bugsnagClient.app.version = '1.2.3'
client.app.releaseStage
Like client.app.version
, if the release stage of the application is available when BugSnag is configured, it’s preferrable to set this in the releaseStage
configuration option, but you can also set this as a property on the client:
bugsnagClient.app.releaseStage = 'staging'
context
By default, in the browser, BugSnag sets the context for each report to window.location.pathname
. Context is given high visual prominence in the dashboard, so if the pathname is not useful to you in tracking down errors, you can set it to something else.
bugsnagClient.context = 'ctx-id-1234'
device
By default, the notifier will set some device properties: time
, locale
and userAgent
. If you want to collect additional information or override one of these values you can do so here.
bugsnagClient.device = { orientation: 'portrait', hasTouch: true }
metaData
Set any metaData
that you want to send with all reports by attaching it to the client object.
bugsnagClient.metaData = {
company: {
name: "Acme Co.",
country: "uk"
}
}
request
By default, in the browser, the notifier will capture { url: window.location.href }
when a report is sent. You can capture any other useful information about the request that loaded the page here. In Node.js because there isn’t likely to be one request which is global to the app, it is not recommended to use this top level property.
bugsnagClient.request = { body: 'item=1234,' }
user
If supplied, user id
, name
and email
are automatically available for filtering in your BugSnag dashboard. The id
property is also used to determine the number of users affected by a particular error.
bugsnagClient.user = {
id: '3',
name: 'Bugs Nag',
email: 'bugs.nag@bugsnag.com'
}
You can attach additional user information to metaData.user
to which will be displayed in the “User” tab of your events along with the id
, name
and email
properties:
bugsnagClient.metaData.user = {
roles: [ 'subscriber', 'premium member' ],
last_visit: '2019-04-09T13:48:47.260Z'
}
client.notify(err, opts, cb)
Report a handled error to BugSnag. This method is described in detail in the reporting handled errors section.
err
[required] should be an error, which will provide the best stacktrace information. If something other than an error is passed, notify()
will do its best to extract meaningful information from it.opts
[optional] is an object used to provide or modify information on the error report, and to provide a beforeSend
callbackcb
[optional] a function with the signature cb(err, report)
. If err=null
the report either sent successfully, or it was enqueued to send later. report
is the report object that was delivered (or enqueued).client.leaveBreadcrumb(message, metaData, type, timestamp)
Adds a breadcrumb.
message
[required] a meaningful summary of the eventmetaData
[optional] a one-level-deep key → value
mapping object of additional data associated with the eventtype
[optional] [default: manual
] a string indicating the breadcrumb type. This is not a free text field, and is typically reserved for automatic breadcrumbs.timestamp
[optional] an ISO 8601 string representing when the event happened. Unless this value is provided, it is set to the time that leaveBreadcrumb()
was called.client.startSession()
Reports a new session. Depending on the platform, this method behaves slightly differently.
In single user processes (such as the browser and React Native) you can call this method and discard its return value. References to the original client get updated with the new session. In these processes, the session is enqueued to send as soon as possible.
In processes that can potentially handle multiple users (i.e. a web server in Node), it is important to hold on to the return value of this method because it returns a new client which is bound to the session that was created. To illustrate, see the following example:
// this starts a session
var sessionClient = client.startSession()
// this error is reported with session information
sessionClient.notify(new Error('boom'))
// this error is not reported with session information
// because it uses the original client
client.notify(new Error('bam'))
In these processes, sessions are created immediately, but they are buffered and sent in batches periodically.
client.use(plugin, ...args)
Provide a plugin for the client to use, along with any necessary arguments.
plugin
[required] a plugin definition…args
[optional] extra arguments that may be required by the plugin@bugsnag/plugin-vue
This plugin requires the Vue
instance to be passed in:
var Vue = require('vue')
var bugsnagVue = require('@bugsnag/plugin-vue')
client.use(bugsnagVue, Vue)
client.getPlugin(name)
Access the return value of a plugin.
string
[required] the plugin’s name@bugsnag/plugin-react
The React plugin returns an ErrorBoundary
component
var ErrorBoundary = client.getPlugin('react')
ReactDOM.render(
<ErrorBoundary>
<App/>
</ErrorBoundary>
)