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

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	Proc
:exclude_when	A (optional) Proc that accepts the data payload. A truthy return value will exclude this event from the payload	Proc
: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 primitives 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

Disabling breadcrumbs

As of version 4.6.0, Breadcrumbs are enabled by default. You can disable breadcrumbs via the breadcrumbs.enabled configuration option (in YAML):

---
breadcrumbs:
  enabled: false

or in the Ruby config:

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

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