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, and you can supply a beforeSend callback to manual notify() calls.

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 supply a beforeSend callback for an individual bugsnagClient.notify() call:

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

If you’re using an asynchronous callback, to prevent a report from being sent you can either use report.ignore() or asynchronously “return false” with resolve(false)/cb(null, false) depending on the style of function used.

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

metaData set on the report will be combinded with metaData set on the client, with properties on the report taking precedence.

// original metaData
var bugsnagClient = bugsnag({
  apiKey: 'YOUR_API_KEY_HERE',
  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 = 'User settings screen'

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

Set the grouping hash of the error report to override the default grouping on the dashboard. All errors 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 lookup a source map or 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:

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