Breadcrumbs

Breadcrumbs are a useful debugging tool that give you the ability to record contextual data as an event called a breadcrumb. When your Project reports an Error (Notice), we send along the breadcrumbs recorded during the execution (request, job, task, etc...).

Context is another way to store extra data to help with debugging. Context is still a great way to attach global data to an error, however, there are scenarios where Breadcrumbs might be a better choice:

  • You want to record metadata that contains duplicate keys
  • You want to group related data
  • You care about when an event happened in relation to an error

Enabling Breadcrumbs

As of version 4.4.0, Breadcrumbs are available yet disabled by default. You must explicitly enable them if you want breadcrumbs to be reported. We plan on enabling breadcrumbs by default in version 5.0.0

To toggle the breadcrumbs.enabled configuration option update the honeybadger yaml config:

---
breadcrumbs:
  enabled: true

or in the Ruby config:

Honeybadger.configure do |config|
  config.breadcrumbs.enabled = true
end

Automatic Rails Breadcrumbs

Rails provides a robust Active Support Instrumentation implementation that allows us to automatically add insights into your errors.

The instrumentation breadcrumbs are very configurable. You can modify a copy of the default config if you want to change the default behavior. Here's how you might remove all ActiveRecord breadcrumb events:

notifications = Honeybadger::Breadcrumbs::ActiveSupport.default_notifications
notifications.delete("sql.active_record")

Honeybadger.configure do |config|
  config.breadcrumbs.active_support_notifications = notifications
end

Note: Active Record SQL logging is on by default. Seeing what SQL statements have been executed leading up to an error can often give helpful context during debugging. We attempt to strip out any bound params or columns before storing queries, however, if you are executing any raw SQL commands or not using prepared statements, there might be a chance that sensitive data could get into the breadcrumb metadata. If you want to keep the ActiveRecord breadcrumbs but remove the SQL metadtata, you could update the config like this:

notifications = Honeybadger::Breadcrumbs::ActiveSupport.default_notifications
notifications["sql.active_record"][:select_keys].delete_if {|k| k == :sql}

Honeybadger.configure do |config|
  config.breadcrumbs.active_support_notifications = notifications
end

You can set an empty hash to remove ActiveSupport notifications all together:

Honeybadger.configure do |config|
  config.breadcrumbs.active_support_notifications = {}
end

The key for each instrumentation hash is the hook id used for subscribing to the ActiveSupport notification. For example

{
  "process_action.action_controller" => {
    message: "Action Controller Action Process",
    select_keys: [:controller, :action, :format, :method, :path, :status, :view_runtime, :db_runtime],
    category: "request",
  }
}

will subscribe to the process_action.action_controller instrumentation notification and produce a breadcrumb with the specified message and category and restrict the keys passed into the metadata to the set supplied by select_keys.

Here are all the options you can pass into an instrumentation hash:

Option name Description
:message A String message that describes the event or you can dynamically build the message by passing a Proc that accepts the event metadata.
:category A String key used to group specific types of events
:select_keys An (optional) Array of keys that filters what data we select from the instrumentation data
:exclude_when A (optional) Proc that accepts the data payload. A truthy return value will exclude this event from the payload
:transform A (optional) Proc that accepts the data payload. The return value will replace the current data hash

Check out the config. to see what we instrument by default.

Note: Some of these configuration options have Procs so you will need to configure breadcrumbs.active_support_notifications in the Ruby configuration only.

Custom Breadcrumbs

You can also add your own custom breadcrumb events:

Honeybadger.add_breadcrumb("Email Sent", metadata: { user: user.id, message: message })

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 options allowed while adding breadcrumbs:

Option name Description
:metadata A (optional) Hash that contains any contextual data to help debugging. We only accept a single-level hash with simple primatives as values (Strings, Numbers, Booleans & Symbols)
: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

Logging Breadcrumbs

All log messages, by default, sent to the ::Logger class are converted into breadcrumbs.

Breadcrumbs from logging can be disabled within the config:

---
breadcrumbs:
  logging:
    enabled: false

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

Limits

Honeybadger uses the following limits to ensure the service operates smoothly for everyone:

  • We only store & transmit 40 breadcrumb events. The current implementation only keeps the 40 latest breadcrumb events.
  • Metadata can only hold scalar values (no nested hashes or arrays)
  • String values have a max size of 64Kb