Reporting handled errors

In order to quickly understand and fix errors, it is often helpful to send additional diagnostic data which is specific to that error.

Sending errors

The notify(err, opts, cb) function reports a JavaScript Error and can optionally attach additional information. The basic form accepts the JavaScript error which occurred:

// Basic example
bugsnagClient.notify(new Error('Something broke!'))

This will create and send a report for a “handled” error, with the default severity “error”.

To customize the error report, supply opts to notify(err, opts). All properties are optional:

opts.metaData	A nested mapping of key/value pairs with additional diagnostic information
opts.severity	'info', 'warning' or 'error'
opts.user	Supply information about the user who experienced the error
opts.beforeSend	A callback to run before the report is sent which can either modify the event or prevent it from being sent
opts.context	Set the context of the error (in the browser this defaults to the current window location pathname)
opts.device	Supply additional information about the user’s device
opts.request	Supply additional information about the request that caused the page to load

// All together now!
bugsnagClient.notify(new Error('Bad, but not fatal'), {
  metaData: { hyperflopz: { count: 23 } },
  severity: 'info',
  user: { id: '1', name: 'B. Nag', email: 'bugs.nag@bugsnag.com' },
  beforeSend: function (report) {
    if (report.user.id === '1') report.ignore()
  },
  context: 'component-space-246',
  device: { orientation: 'portrait' },
  request: { id: 12345 }
})

To run a callback when the report has been delivered or enqueued for delivery later, provide this as the third argument:

bugsnagClient.notify(new Error('uh oh'), {}, function (err, report) {
  if (err) {
    console.log('Failed to send report because of:\n' + err.stack)
  } else {
    console.log('Successfully sent report "' + report.errorMessage + '"')
  }
})

Sending custom errors

The notify(err) function only expects errors. If you provide something that is not an error, notify() will attempt to create an error from it (for example, if you provide a string, the notifier will do new Error(str)).

If an invalid type is sent, for example, null or a Function, the error will be reported but the error message will indicate a notifier usage error.

Customizing diagnostic data

The metaData property of the opts argument to notify(err, opts) creates a named section of diagnostic data using the top level key as the name and the key/value pairs as elements in the section. Additionally, the beforeSend callback can make use of the report.updateMetaData() and report.removeMetaData() convenience methods.

The following examples would create a section named “special info”, with elements named “request_id” and “message_id”:

// Sending a metaData property in opts
bugsnagClient.notify(new Error('Something broke!'), {
  metaData: {
    'special info': {
      request_id: 12345,
      message_id: 854
    }
  }
})

// Adding metaData via report methods
bugsnagClient.notify(new Error('Something broke!'), {
  beforeSend: (report) => {
    report.updateMetaData('special info', {
      request_id: 12345,
      message_id: 854
    })
  }
})