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

Removing IP address

IP address is collected by default and used as both the user identifier and client IP address in error reports. Both can be overridden with either a static value (to redact them altogether) or set dynamically as needed:

To set dynamic values, set report.user and report.request values from a callback:

var bugsnagClient = bugsnag({
  beforeSend: function (report) {
    var userId = getMyUserIdentifier() // a custom user resolver
    report.user = { id: userId }
    report.request = { clientIp: '[REDACTED]' }
  }
})

To set constant values, set report.user and report.request when configuring Bugsnag.

Note that setting user.id to a constant value will make all errors appear to have only been seen by a single user, rendering prioritization of errors by the number of users affected more difficult.

var bugsnagClient = bugsnag()

// Prevent the request's client IP from being collected
bugsnagClient.request = {
  request: { clientIp: '[REDACTED]' }
}

// Set the user ID to an anonymous user identifier
// (to prevent the default client IP value from being used)
bugsnagClient.user = {
  id: '[REDACTED]'
}

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

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