Customizing error reports

In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to Bugsnag.

Adding a callback

Use the beforeSend callback to add diagnostic data to error reports, modify collected data, or cancel report delivery altogether. You can configure a beforeSend callback for all reports, or if you call notify() manually, you can supply a beforeSend callback for that report only.

To cancel the error report, return false from the function.

See the report object for available properties and methods within the callback.

Modifying report information

You can modify the payload by editing values directly and via convenience methods.

var bugsnagClient = bugsnag({
  beforeSend: function (report) {
    // Filter out sensitive information
    report.request.url = '[REDACTED]'

    // Add additional diagnostic information
    report.updateMetaData('account', {
      type: 'paid',
      betaAccess: true
    })
  }
})

Disabling error reporting

If you want to halt the error notification completely, call report.ignore() or return false from beforeSend. You can set a beforeSend callback globally:

var bugsnagClient = bugsnag({
  beforeSend: function (report) {
    // Example: Disable reporting of errors with a given error message
    if (report.errorMessage === 'Do not report this error') report.ignore()
    // or
    if (report.errorMessage === 'Do not report this error either') return false
  }
})

Or you can set a beforeSend callback from bugsnagClient.notify:

bugsnagClient.notify(new Error('Bad things'), {
  beforeSend: function (report) {
    // Example: Disable reporting of errors with a given error message
    if (report.errorMessage === 'Do not report this error') report.ignore()
    // or
    if (report.errorMessage === 'Do not report this error either') return false
  }
})

The report object

The following properties are available on the report object. Some of these properties may already be set, depending on the configuration of the notifier. The beforeSend callback may modify any of these properties as desired.

Note that, for methods that call a hash, keys are merged into the previous hash, if present. Setting the method equal to a hash, however, will override the previous hash:

// original metaData
var bugsnagClient = bugsnag({
  apiKey: '8e029ff85de670bcb682cee5d8db733d',
  metaData: { tabName: { item: '1.2.3' } }
})

bugsnagClient.notify(err, {
  beforeSend: function (report) {
    // this metaData will override the original metaData
    report.metaData = {
      overrideTab: { overrideItem: '9.8.7' }
    }
  }
})

app.releaseStage

Set or modify the release stage:

report.app.releaseStage = 'staging'

app.version

Set or modify the app version:

report.app.version = '4.1.1'

apiKey

Takes in the api key as a string. Even though the API Key is set when Bugsnag is initialized, you may choose to send certain error reports to a different Bugsnag project:

report.apiKey = 'YOUR-API-KEY'

breadcrumbs

Modify the breadcrumbs array:

// filter out breadcrumbs that match a certain name
report.breadcrumbs = report.breadcrumbs.filter(function (breadcrumb) {
  return breadcrumb.name != "UI click"
})

context

By default, Bugsnag sets the context for each report to window.location.pathname. Context is given high visual prominence in the dashboard, so if the pathname is not useful to you in tracking down errors, you can set it to something else:

report.context = '/path/to/my/page.js'

device

Add or modify information about the device the error report was sent from.

report.device = { orientation: 'portrait', hasTouch: true }

errorClass

Override the error class if you wish to report a more descriptive error:

report.errorClass = 'MyError'

errorMessage

report.errorMessage = 'I have made a huge mistake'

groupingHash

If the metaData hash has a key groupingHash it will be used to override the default grouping on the dashboard. Exceptions with the same grouping hash will be grouped together into one error. This is an advanced usage of the library and mis-using it will cause your errors not to group properly in your dashboard.

report.groupingHash = report.errorClass

By default, errors are grouped by the statement in your code that raised the error. We try to fetch the JavaScript and use the surrounding code to identify the statement, but if that’s not possible we fall back to using line number and filename as an approximation.

ignore()

Prevents the report being sent to Bugsnag:

var bugsnagClient = bugsnag({
  beforeSend: function (report) {
    // Example: Disable reporting from internal routes
    if (/internal\//.test(report.request.url)) report.ignore()
  }
})

metaData

report.metaData = {
  company: {
    name: 'Acme Co.',
    country: 'UK'
  }
}

removeMetaData()

Use this to remove a metaData field or entire metaData tab:

// Remove a metaData field
report.removeMetaData('section', 'property')
// Remove a metaData tab
report.removeMetaData('section')

request

Update or remove the request object. The defined fields are url and clientIp:

report.request.url = '[REDACTED]'
report.request.clientIp = '[REDACTED]'

severity

The seriousness of the error, selected from the options info, warning and error, listed in order of increasing severity:

report.severity = 'warning'

stacktrace

An array containing stackframe objects with the following properties:

property	type	description
file	String	The URL that the browser loaded this particular source file from. When the script doesn’t have a URL this can be a value such as 'global code'. If the script is inline, this will be the URL of the page it was loaded on.
lineNumber	Number	The line number within the source file this stackframe refers to.
columnNumber	Number	The column number within the source file this stackframe refers to. This can be undefined when the column number is not known.
method	String	The name of the method that was being executed, if available.
inProject	Boolean	This is always set to undefined by default. However, you can update this property to indicate when stackframes are known to be outside of your project in order to improve grouping and stacktrace readability. See the example below.
code	Object	When errors occur in inline scripts the notifier will extract the contents of the script and populate this property.

// Sets the `inProject` property to `false` for anything with "vendor" in the path
report.stacktrace.forEach(function (frame) {
  var inProject = !/\/vendor\//.test(frame.file)
  // If you set one stackframe.inProject you should set them all
  frame.inProject = inProject
})

Note that if your code is minified, source maps will not have been applied at this point, and so your stackframes will have locations and methods from minified code.

updateMetaData()

Set, replace, or augment metaData key value pairs, or entire metaData tabs:

// Set a metaData key value pair under a given section, merging with exising properties
report.updateMetaData('section', 'property', value)
report.updateMetaData('section', { a: a, b: b })
// Removes the `'property'` value from `metaData.section` if it exists
report.updateMetaData('section', 'property', null)
// Removes `metaData.section` if it exists
report.updateMetaData('section', null)

user

Modify the information in the user tab:

report.user = {
  id: '3',
  name: 'Bugs Nag',
  email: 'bugs.nag@bugsnag.com',
  roles: [ 'subscriber' ]
}