Configuration options

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.

Setting configuration options

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

Available options

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.start({ agent: false })
Bugsnag.start({ agent: new ProxyAgent('http://my-proxy-url:3128') })

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

Bugsnag.start({ appType: 'web_server' })
Bugsnag.start({ appType: 'worker' })
Bugsnag.start({ appType: 'websocket_server' })
Bugsnag.start({ appType: 'mailer' })

The default appType in Node.js is "node".

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:

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

If you switch off automatic session tracking with the autoTrackSessions option, you can still send sessions manually by calling Bugsnag.startSession() when appropriate for your application.

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.

Bugsnag.start({ context: 'ctx-id-1234' })

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.

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.start({ hostname: 'web1.example.com' })

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

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.

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

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

Bugsnag.start({
  onUncaughtException: function (err, event) {
    // err = the original error
    // event = the BugSnag event 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 behavior.

If you want to do something else, you can use this option to supply your own behavior.

Bugsnag.start({
  onUnhandledRejection: function (err, event) {
    // err = the original error
    // event = the BugSnag event object that got sent
  }
})

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.

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

projectRoot

By default this is the current working directory of the running process. Stack frame paths will be relative from this path.

Bugsnag.start({ projectRoot: '/app' })

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

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.start({ sendCode: 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'
  }
})