Customizing breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatic breadcrumbs

Breadcrumbs for common actions and device changes are captured by default. This can be controlled using the enabledBreadcrumbTypes configuration option.

Adding manual breadcrumbs

Append manual breadcrumbs with a message via the Bugsnag client:

Bugsnag.leaveBreadcrumb('App loaded')
Bugsnag.leaveBreadcrumb('User clicked a button')

BugSnag will keep track of the time and order of the breadcrumbs and show them on your dashboard.

Attaching metadata

Additional data can be attached to breadcrumbs by providing the additional metadata argument. Metadata will be presented on the BugSnag dashboard alongside the breadcrumb name and type:

var metadata = {
  from: 'moka',
  to: 'french press'
}
Bugsnag.leaveBreadcrumb('Preference updated', metadata, 'state')

Breadcrumb “types” can be used to differentiate different types of events, such as user activity and changes in application state. See the breadcrumb types list for a complete list of the breadcrumb types available. Your breadcrumbs will not be affected by the enabledBreadcrumbTypes configuration option.

As of v8 of the BugSnag SDK, calling methods on the Bugsnag client inside middleware of a Node app is request-specific and so only affects the request being handled. See our Node.js guide for more details.

Discarding and amending breadcrumbs

You can register a callback that is executed each time a breadcrumb is captured using addOnBreadcrumb. This can be helpful if you wish to filter out certain automatic breadcrumbs from your application or amend the data contained within them.

Bugsnag.start({
  onBreadcrumb: function (breadcrumb) {
    if (breadcrumb.type === 'navigation') {
      if (breadcrumb.metadata.to === '/home') return false
      breadcrumb.metadata.to = stripQueryString(breadcrumb.metadata.to)
    }
  }
})

Adding and removing callbacks

We recommend adding callbacks through the onBreadcrumb configuration option to ensure that it is registered as soon as BugSnag starts. However, the following methods are provided to allow callbacks to be added and removed whilst the application is running:

var cb = function (breadcrumb) { /* ... */ }
Bugsnag.addOnBreadcrumb(cb)
// ...
Bugsnag.removeOnBreadcrumb(cb)

As of v8 of the BugSnag SDK, calling methods on the Bugsnag client inside middleware of a Node app is request-specific and so only affects the request being handled. See our Node.js guide for more details.

The Breadcrumb object

The following information is available on a Breadcrumb object, the representation of breadcrumb information available in an onBreadcrumb callback.