In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to Bugsnag.
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.
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
})
}
})
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 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 `true` for anything with "vendor" in the path
for (var frame in report.stacktrace) {
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' ]
}