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

Preventing IP address collection

The client’s IP address is collected by default and used in both the user identifier and request data tab in error reports. This can be prevented by setting the collectUserIp: false option.

Note that by not collecting IPs, reports will all appear to come from the same user.id unless a user ID is specified. We strongly recommend that you supply a user ID so you can prioritize bugs by the number of users affected. Libraries such as Fingerprintjs can be used to create an anonymous, unique, but reproducible identifiers.

To prevent IP collection but set user IDs:

var bugsnagClient = bugsnag({
  collectUserIp: false,
  beforeSend: function (report) {
    var userId = getMyUserIdentifier() // a custom user resolver
    report.user = { id: userId }
  }
})

If the user ID value is known when configuring Bugsnag, you can set user right away:

var bugsnagClient = bugsnag({
  collectUserIp: false,
  user: { id: '1234' }
})

For more information on these top-level values, see the configuration options documentation for user and request.

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

// 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 is set when Bugsnag is initialized, you may choose to send certain error reports to a different Bugsnag project:

report.apiKey = 'YOUR-API-KEY'

Modify the breadcrumbs array:

// filter out breadcrumbs that match a certain name
report.breadcrumbs = report.breadcrumbs.filter(
  breadcrumb => 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

Override any or all stackframes in the stacktrace. Each stackframe is an item in the stacktrace array:

// Modify the second stackframe
report.stacktrace[1] = {
  file: 'http://example/app.js',
  line: 19,
  column: 27,
  method: ''
}

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