Configuration options

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.

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 appTypes.

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.

If the notify endpoint is changed and the sessions endpoint is not, this option will be set to false and session tracking will be disabled.

To disable automatic session capturing:

bugsnag({ autoCaptureSessions: false })

Bugsnag will automatically report a session each time:

  • A request is handled (when using a server side framework plugin)

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
  }
})

For more information, 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.

To set the endpoints:

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 regexs (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 browser 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({
  onUnhandledException: 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({
  onUnhandledException: 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

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.

Client properties

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

The user property is used to populate the “User” tab of reported errors on your Bugsnag dashboard, and the id property is used to determine the number of users affected by a particular error. You can attach any additional user information here. In Node.js, a single process may handle many users in its lifetime, so use of this top-level property is discouraged (unless your application is, for example, a CLI which does only have one user).

bugsnagClient.user = {
  id: '3',
  name: 'Bugs Nag',
  email: 'bugs.nag@bugsnag.com',
  roles: [ 'subscriber' ]
}