Configuration options

BugSnag has many configuration options that can be set to customize the content of events and sessions and how they are sent.

Setting configuration options

Configuration options package 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 your BugSnag dashboard.

Bugsnag.start({ apiKey: 'API_KEY' })

You can find your API key in your project’s settings (shortcut: gs) in the 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: 'tv' })

appVersion

The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally closed errors are re-opened if a later version of the app has a regression.

Bugsnag.start({ appVersion: '4.10.0' })

autoDetectErrors

By default, we will automatically report any uncaught errors that we capture. Use this flag to disable all automatic detection.

Bugsnag.start({ autoDetectErrors: false })

autoTrackSessions

By default, session information from your application will be automatically captured. Use this flag to disable all automatic reporting.

Bugsnag.start({ autoTrackSessions: false })

BugSnag will automatically report a session each time:

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

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', 'request']
})

Automatically captured breadcrumbs can be disabled by providing an empty array in enabledBreadcrumbTypes.

Bugsnag.start({ enabledBreadcrumbTypes: [] })

The following automatic breadcrumb types can be enabled:

Captured errors

error breadcrumbs are left when an error event is sent.

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.

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

enabledErrorTypes

The BugSnag SDK 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
  }
})

enabledReleaseStages

By default, events that happen in any releaseStage will be sent. 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 the address of our hosted notify and sessions endpoints.

If you are using On-premise services 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.

logger

By default, log messages from the BugSnag SDK 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 })

maxPersistedEvents

Sets the maximum number of events which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest events will be deleted.

By default, 32 events are stored.

Bugsnag.start({ maxPersistedEvents: 50 })

maxPersistedSessions

Sets the maximum number of sessions which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest sessions will be deleted.

By default, 128 sessions are stored.

Bugsnag.start({ maxPersistedSession: 50 })

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

onError

Add callbacks to modify or discard error events before they are sent — 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 — see Capturing sessions for more information.

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

persistenceDirectory

Sets the directory where BugSnag data, such as event and session payloads, are cached on disk. User information is also persisted here if persistUser is true.

Bugsnag.start({ persistenceDirectory: '/data/mydir' })

The default directory for this property is /data/bugsnag in your Vega app’s assigned directory.

persistUser

Set whether or not BugSnag should persist user information between application launches.

By default persistUser is set to true. To disable this behavior:

Bugsnag.start({ persistUser: false })

If enabled then any user information set will be re-used until the user information is removed manually by calling Bugsnag.setUser with null arguments.

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 an event is sent. 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' })

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