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.

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

All options set in the main process affect the behavior of the BugSnag library in renderer processes, however only a subset of options are available to be customized in renderer processes directly, with limitations indicated on each option below.

apiKey

mainavailable
rendererunavailable

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

mainavailable
rendereravailable

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.

On Electron, appType defaults to the OS the app is running on and will be either Linux, macOS or Windows.

Bugsnag.start({ appType: 'prefs_window' })

appVersion

mainavailable
rendererunavailable

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

By default, appVersion is set to the bundle version (CFBundleShortVersionString on macOS, ProductVersion on Windows) or app.getVersion().

autoDetectErrors

mainavailable
rendererunavailable

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

mainavailable
rendererunavailable

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 the app is launched or returns to the foreground after 60 or more seconds in the background.

codeBundleId

mainunavailable
rendereravailable

A user-defined unique identifier for a JavaScript code deployment. There can be multiple deployments for a given appVersion.

If you ship updates to your renderer JavaScript without releasing a new version of your app, use this configuration option to identify the bundle to BugSnag for matching source maps.

Bugsnag.start({ codeBundleId: "1.0-15" })

context

mainavailable
rendereravailable

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

mainavailable
rendererunavailable

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

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

Network requests

request breadcrumbs are left for network requests initiated via the Electron net module. Metadata includes HTTP method, request URL and status code (if available).

State changes

state breadcrumbs are left when:

  • the application becomes ready or will quit
  • the application enters or exits the foreground
  • the device’s network connection changes state
  • the device’s displays change size or are added or removed
  • power state changes, like switching to battery power
  • window resize and responsiveness events

User interaction

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

enabledErrorTypes

mainavailable
rendererunavailable

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: true,
    unhandledRejections: false,
    nativeCrashes: true,
  }
})

Setting autoDetectErrors to false will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes.

enabledReleaseStages

mainavailable
rendererunavailable

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

mainavailable
rendererunavailable

By default we will send error events to notify.bugsnag.com, sessions to sessions.bugsnag.com, and native crash dumps to notify.bugsnag.com/minidump.

If you are using BugSnag On-premise you’ll need to set these to your Event Server, Session Server, and Minidump Server, respectively. If the notify and sessions endpoints are set but the minidumps endpoint is not, native crash reporting will be disabled automatically to avoid leaking 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',
    minidumps: 'https://bugsnag-minidump.example.com',
  }
})

featureFlags

mainavailable
rendereravailable

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.

launchDurationMillis

mainavailable
rendererunavailable

The amount of time (in milliseconds) after starting BugSnag that should be considered part of the app’s launch.

By default this value is 5000 milliseconds.

Bugsnag.start({
  launchDurationMillis: 0
})

// Once your app has finished launching
Bugsnag.markLaunchCompleted()

Events that occur during app launch will have their app.isLaunching property set to true.

Setting this to 0 will cause BugSnag to consider the app to be launching until Bugsnag.markLaunchCompleted() has been called.

See identifying crashes at launch guide for more info.

logger

mainavailable
rendereravailable

By default, log messages from the BugSnag JavaScript library are prefixed with [bugsnag] and the process type and output to the console. 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

mainavailable
rendererunavailable

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

metadata

mainavailable
rendereravailable

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.

onBreadcrumb

mainavailable
rendereravailable

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

Callbacks configured in renderer processes only run for breadcrumbs added in that process.

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

onError

mainavailable
rendereravailable

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

Callbacks configured in renderer processes only run for errors captured in that process.

onSession

mainavailable
rendererunavailable

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

onSendError

mainavailable
rendererunavailable

Add callbacks to modify or discard error events immediately prior to delivering events to BugSnag. This callback may not be invoked during the same app launch cycle as when the error occurred, since delivery can be delayed by network connectivity conditions or whether the event was caused by a crash (which are always sent in a subsequent app launch).

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

onUncaughtException

mainavailable
rendererunavailable

By default, when an unhandled exception occurs, BugSnag will send an error report, then print the error to the console.

If you want to do something else – for example, displaying an error dialog – 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

mainavailable
rendererunavailable

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.

projectRoot

mainavailable
rendererunavailable

By default, this is the application path as derived by app.getAppPath(). Stack frame paths will be relative from this path.

const { join } = require('path')

Bugsnag.start({ projectRoot: join(__dirname, '..') })

plugins

mainavailable
rendereravailable

Provide plugins for the client to use, along with any necessary arguments.

For example:

var Vue = require('vue')
var Bugsnag = require('@bugsnag/electron')
var BugsnagPluginVue = require('@bugsnag/plugin-vue')
Bugsnag.start({
  plugins: [ new BugsnagPluginVue(Vue) ]
})

redactedKeys

mainavailable
rendererunavailable

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

mainavailable
rendererunavailable

Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).

Bugsnag.start({ releaseStage: 'staging' })

By default, if app.isPackaged() is true, then releaseStage is set to production, otherwise it is set to development.

sendCode

mainavailable
rendererunavailable

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

mainavailable
rendereravailable

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