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 the following events as breadcrumbs:

• Error reports

• HTTP requests

This can be controlled using the enabled_breadcrumb_types configuration option.

Adding manual breadcrumbs

You can use the leave_breadcrumb method to log potentially useful events in your own applications:

bugsnag.leave_breadcrumb("Something happened!")

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:

bugsnag.leave_breadcrumb(
    "Something happened!",
    {"from": "moka", "to": "french press"},
    bugsnag.BreadcrumbType.USER
)

A Breadcrumb’s type can be used to differentiate different kinds of events, such as user activity and changes in application state. See the BreadcrumbType enumeration for a complete list of the breadcrumb types available. Manual breadcrumbs will not be affected by the enabled_breadcrumb_types configuration value.

Discarding and amending breadcrumbs

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

def on_breadcrumb(breadcrumb):
    if breadcrumb.message == "Noisy Breadcrumb":
        return False # ignore the breadcrumb

    breadcrumb.metadata['example'] = 1234

bugsnag.add_on_breadcrumb(on_breadcrumb)

Adding and removing callbacks

The following methods are provided to allow callbacks to be added and removed whilst the application is running:

def on_breadcrumb(breadcrumb):
    pass

bugsnag.add_on_breadcrumb(on_breadcrumb)
# ...
bugsnag.remove_on_breadcrumb(on_breadcrumb)

Logging integration

To record breadcrumbs for log messages, you can add the leave_breadcrumbs log filter:

from bugsnag.handlers import BugsnagHandler

logger = logging.getLogger("test.logger")
handler = BugsnagHandler()

logger.addFilter(handler.leave_breadcrumbs)

This will capture a breadcrumb for each log message at or above the configured breadcrumb_log_level, which defaults to INFO.

The breadcrumb log filter can work in conjunction with, or separately to, BugSnag’s log handler. When the filter and handler are both used, BugSnag will capture either an error or a breadcrumb. An error will be captured for messages at or above the handler’s level and a breadcrumb will be captured for messages at or above the breadcrumb_log_level and below the handler’s level.

The Breadcrumb class

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