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

Breadcrumbs for MongoDB queries are captured by default. This can be controlled using the enabled_breadcrumb_types configuration option.

Adding manual breadcrumbs

Append manual breadcrumbs with a message via the Bugsnag client:

Bugsnag.leave_breadcrumb('Something happened!')

BugSnag will keep track of the time and order of the breadcrumbs and show them on your dashboard.

Breadcrumbs are scoped to the thread running the current job.

Attaching metadata

Additional data can be attached to breadcrumbs by providing the optional metadata argument. Metadata will be presented on the BugSnag dashboard alongside the breadcrumb name and type:

metadata = {
  user_id: 9000,
  auth_level: "admin"
}

Bugsnag.leave_breadcrumb('User logged in', metadata, Bugsnag::BreadcrumbType::USER)

Breadcrumb “types” can be used to differentiate different types of events, such as user activity and changes in application state. See the Bugsnag::BreadcrumbType module for a complete list of the breadcrumb types available. Your breadcrumbs will not be affected by the enabled_breadcrumb_types configuration option.

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.

Bugsnag.configure do |config|
  config.add_on_breadcrumb(proc do |breadcrumb|
    if breadcrumb.message == 'should ignore'
      # ignore the breadcrumb if the message is 'should ignore'
      false
    else
      # amend the breadcrumb metadata if not ignored
      breadcrumb.metadata[:captured] = true
    end
  end)
end

Adding and removing callbacks

We recommend adding callbacks through the add_on_breadcrumb 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:

callback = proc { }

Bugsnag.add_on_breadcrumb(callback)
# ...
Bugsnag.remove_on_breadcrumb(callback)

The breadcrumb object

message

A short description of the breadcrumbed event. This shows up prominently on the BugSnag dashboard.

breadcrumb.message += ': some extra context'

type

Identifies what kind of event occurred.

breadcrumb.metadata = {} if breadcrumb.type == Bugsnag::BreadcrumbType::PROCESS

There is a list of valid types within the Bugsnag::BreadcrumbType module, defaulting to Bugsnag::BreadcrumbType::MANUAL.

metadata

A hash of additional data about the event. This can help to determine if or how this event may have caused an error notification.

breadcrumb.metadata[:authorized] = user_authorized?(user_id)

auto

Describes if the breadcrumb was automatically generated or not.

puts breadcrumb.auto ? "Bugsnag generated" : "Manually created"

This cannot be modified.

timestamp

The time the breadcrumb was created.

puts "Breadcrumb created at #{breadcrumb.timestamp}"

This cannot be modified.