Capturing events with breadcrumbs

Breadcrumbs are events that happen right before an error occurs. Honeybadger captures many types of breadcrumbs automatically, such as click events, console logs, and Ajax requests. You can enhance your ability to rapidly understand and fix your errors by capturing additional breadcrumbs throughout your application.

Capturing breadcrumbs

To capture a breadcrumb anywhere in your application:

Honeybadger.addBreadcrumb("Sent Email", {
  metadata: { user_id: user.id, body: body },
});

The first argument (message) is the only required data. In the UI, message is front and center in your breadcrumbs list, so we prefer a more terse description accompanied by rich metadata.

Here are the supported options when adding breadcrumbs:

Option name	Description
metadata	A (optional) Object that contains any contextual data to help debugging. Must be a single-level object with simple primitives (strings, numbers, booleans) as values.
category	An (optional) string key used to group specific types of events. We primarily use this key to display a corresponding icon, however, you can use it for your own categorization if you like.

Categories

A Breadcrumb category is a top level property. It’s main purpose is to allow for display differences (icons & styling) in the UI. You may give a breadcrumb any category you wish. Unknown categories will default to the “custom” styling.

Here are the current categories and a brief description of how you might categorize certain activity:

Category	Description
custom	Any other kind of breadcrumb
error	A thrown error
query	Access or Updates to any data or file store
job	Queueing or Working via a job system
request	Outbound / inbound requests
render	Any output or serialization via templates
log	Any messages logged
notice	A Honeybadger Notice

Automatic breadcrumbs

Honeybadger captures the following breadcrumbs automatically by instrumenting browser features:

• Clicks
• Console logs
• Errors
• History/location changes
• Network requests (XHR and fetch)

Enabling/disabling breadcrumbs

Breadcrumbs are enabled by default. To disable breadcrumbs in your project:

Honeybadger.configure({
  // ...
  breadcrumbsEnabled: false,
});

You can also enable/disable specific types of breadcrumbs:

Honeybadger.configure({
  breadcrumbsEnabled: {
    dom: true,
    network: true,
    navigation: true,
    console: true,
  },
});

Note: This configuration applies only on the first call to Honeybadger.configure.

Filtering breadcrumbs

To drop or change individual breadcrumbs, register a beforeBreadcrumb handler. It runs before each breadcrumb is recorded, including the ones Honeybadger captures automatically. Return false to drop the breadcrumb.

For example, to skip network breadcrumbs for requests to a telemetry endpoint (XHR and fetch breadcrumbs include the request url in their metadata):

Honeybadger.beforeBreadcrumb((breadcrumb) => {
  if (/\/telemetry\//.test(breadcrumb.metadata.url)) {
    return false;
  }
});

You can also mutate the breadcrumb in place to change what is recorded:

Honeybadger.beforeBreadcrumb((breadcrumb) => {
  if (breadcrumb.category === "log") {
    breadcrumb.message = breadcrumb.message.slice(0, 200);
  }
});

Handlers are synchronous and run in the order they were added. If a handler throws, Honeybadger logs the error and records the breadcrumb anyway.