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

By default, BugSnag captures breadcrumbs for common actions and device changes, including:

  • Low memory warnings
  • Device rotation
  • Menu presentation
  • Screenshot capture (not the screenshot itself)
  • Undo and redo
  • Table view selection
  • Window visibility changes
  • Non-fatal errors
  • Log messages
  • User navigation (when enabled through our navigation plugins)
  • HTTP requests (from JavaScript layer)

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.leaveBreadcrumb("App loaded");
Bugsnag.leaveBreadcrumb("User clicked a button");
[Bugsnag leaveBreadcrumbWithMessage:@"App loaded"];
[Bugsnag leaveBreadcrumbWithMessage:@"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')
Map<String, Object> metadata = new HashMap<String, Object>() {{
  put("from", "moka");
  put("to", "french press");
Bugsnag.leaveBreadcrumb("Preference updated", metadata, BreadcrumbType.STATE);
[Bugsnag leaveBreadcrumbWithMessage:@"Preference updated"
                           metadata:@{@"from": @"moka", @"to": @"french press"}

For more information leaving manual breadcrumbs, including how to capturing NSNotification events on iOS and listening to the Fragment Lifecycle on Android, see our platform-specific guides:

Discarding and amending breadcrumbs

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

Native onBreadcrumb callbacks will be triggered for JavaScript and native layer breadcrumbs. JavaScript onBreadcrumb callbacks will only be triggered for JavaScript layer breadcrumbs.

  onBreadcrumb: function (breadcrumb) {
    if (breadcrumb.message === 'Noisy breadcrumb') {
        return false // ignore the breadcrumb
    } else {
        return true // capture the breadcrumb
Configuration config = Configuration.load(this);
config.addOnBreadcrumb(new OnBreadcrumbCallback() {
    public boolean onBreadcrumb(@NonNull Breadcrumb breadcrumb) {
        if (breadcrumb.getMessage().equals("Noisy breadcrumb")) {
            return false; // ignore the breadcrumb
        } else {
            return true; // capture the breadcrumb
Bugsnag.start(this, config);
BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addOnBreadcrumbBlock:^(BugsnagBreadcrumb *_Nonnull breadcrumb) {
    if ([breadcrumb.message isEqualToString:@"Noisy breadcrumb"]) {
        return NO; // ignore the breadcrumb
    } else {
        return YES; // capture the breadcrumb
[Bugsnag startWithConfiguration:config];

If log breadcrumbs are enabled, do not log within an onBreadcrumb callback to avoid an infinite loop.

For more information about breadcrumb callbacks, see our platform-specific guides:

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) { /* ... */ }
// ...
OnBreadcrumbCallback cb = new OnBreadcrumbCallback() { /* ... */ };
// ...
BugsnagOnBreadcrumbBlock cb = ^BOOL(BugsnagBreadcrumb *breadcrumb) { /* ... */ };
[Bugsnag addOnBreadcrumbBlock:cb];
// ...
[Bugsnag removeOnBreadcrumbBlock:cb];

For more information about adding and removing breadcrumb callbacks, see our platform-specific guides:

The Breadcrumb object

The breadcrumb callbacks available to the three libraries provide a “breadcrumb” parameter that represents a breadcrumb that is about to be captured. The object contains properties and methods for you to query and update the captured data.

For full details, see our platform-specific guides: