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

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.

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: 'client' })
Bugsnag.start({ appType: 'web_worker' })
Bugsnag.start({ appType: 'service_worker' })

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.

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

autoDetectErrors

By default, we will automatically notify Bugsnag of any uncaught exceptions and unhandled promise rejections. If you want to stop all automatic detection, you can set autoDetectErrors to false:

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.

To disable automatic session capturing:

Bugsnag.start({ autoTrackSessions: false })

Bugsnag will automatically report a session each time:

  • The page loads
  • The URL changes via 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.

enabledBreadcrumbTypes

By default Bugsnag will automatically add breadcrumbsfor common application events whilst your application is running. To configure which of these are enabled and sent to Bugsnag, set the enabledBreadcrumbTypes option:

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 breadcrumb types can be enabled:

Captured errors

error breadcrumbs are left when an error event is sent to the Bugsnag API.

Log messages

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.

Network requests

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 interaction

user breadcrumbs are left when the user clicks/touches the page.

enabledErrorTypes

Bugsnag will automatically detect different types of error in your application. If you wish to control exactly which types are enabled, set enabledErrorTypes:

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, 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 enabledReleaseStages.

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.

To set the endpoints:

Bugsnag.start({
  endpoints: {
    notify: 'https://bugsnag-notify.example.com',
    sessions: 'https://bugsnag-sessions.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.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 any metadata that you want to send with captured event by providing an object whose top-level keys are section names that are displayed as tabs in the Bugsnag dashboard.

Bugsnag.start({
  metadata: {
    company: {
      {
        name: "Acme Co.",
        country: "uk"
      }
    }
  }
})

The metadata configuration option is provided to set initial data when Bugsnag starts. For information about changing this data whilst your app is running, see Global metadata.

onBreadcrumb

To modify or discard breadcrumbs before they are recorded, onBreadcrumb provides access to the breadcrumb data structure:

Bugsnag.start({
  onBreadcrumb: function (breadcrumb) {
    if (breadcrumb.type == 'navigation') {
    if (breadcrumb.metadata.to == '/home') return false
    breadcrumb.metadata.to = stripQueryString(breadcrumb.metadata.to)
  }
})

If log breadcrumbs are enabled, do not log within an onBreadcrumb callback to avoid an infinite loop.

See Customizing Breadcrumbs for more information about breadcrumb callbacks.

onError

To modify error reports before they are sent, or to prevent them from being sent at all, onError provides access the report data structure and the means to mutate or ignore it:

Bugsnag.start({
  onError: function (event) {
    // Adjust event here
  }
})

For examples on how to modify events and what is available on the Event object, see Customizing Error Reports.

onSession

To modify sessions before they are sent, or to prevent them from being sent at all, onSession provides access to the session data structure and the means to mutate or ignore it:

Bugsnag.start({
  onSession: function (session) {
    var userId = getMyUserIdentifier() // a custom user resolver
    session.setUser(userId)
  }
})

See Capturing Sessions for more information about session callbacks.

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

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 [REDACTED].

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

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

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

You can supply user id, name and/or email data in events to make the data available for filtering in your Bugsnag dashboard. The id property is also used to determine the number of users affected by a particular error.

Bugsnag.start({ 
  user: {
    id: '3',
    name: 'Bugs Nag',
    email: 'bugs.nag@bugsnag.com'
  }
})

The user configuration option is provided to set user data when Bugsnag starts. For information about changing this data whilst your app is running, see Adding user data.