Capturing Events with Breadcrumbs
When your application encounters an error, it's often helpful to know what events occurred leading up to that. Honeybadger lets you do that with breadcrumbs.
Breadcrumbs are records of events that happened within your application — external API calls, job dispatches, database queries, or anything that you think might be relevant. When we capture an error, we display these breadcrumbs in your dashboard to provide extra debugging information.
Use context to record request-global data like the current user ID; use breadcrumbs to record specific events within the request and their custom metadata.
If you’re using Laravel or Lumen, Honeybadger can automatically capture breadcrumbs from your app. By default, we’ll record:
- Log events
- View renders
- Email dispatches
- Job dispatches
- Notification dispatches
- Database queries
- Redis commands
- Incoming requests
You can customise this with the
breadcrumbs option in your
'breadcrumbs' => [ 'enabled' => true, 'automatic' => [ Breadcrumbs\DatabaseQueryExecuted::class, Breadcrumbs\DatabaseTransactionStarted::class, Breadcrumbs\DatabaseTransactionCommitted::class, Breadcrumbs\DatabaseTransactionRolledBack::class, Breadcrumbs\CacheHit::class, Breadcrumbs\CacheMiss::class, Breadcrumbs\JobQueued::class, Breadcrumbs\MailSending::class, Breadcrumbs\MailSent::class, Breadcrumbs\MessageLogged::class, Breadcrumbs\NotificationSending::class, Breadcrumbs\NotificationSent::class, Breadcrumbs\NotificationFailed::class, Breadcrumbs\RedisCommandExecuted::class, Breadcrumbs\RouteMatched::class, Breadcrumbs\ViewRendered::class, ], ],
breadcrumbs.automatic key contains the list of the events Honeybadger tracks by default. You can disable a specific event by removing or commenting out the appropriate line.
You can also record breadcrumb events manually. This can be helpful if you aren’t using a supported framework, or there are additional events in your application that Honeybadger doesn’t recognize.
To add a breadcrumb, use
$honeybadger->addBreadcrumb($message, $metadata, $category):
$honeybadger = Honeybadger\Honeybadger::new(['api_key' => 'abc123']); $honeybadger->addBreadcrumb("Notification sent", ['user_id' => $user->id, 'type' => 'welcome']); $honeybadger->addBreadcrumb("Payment webhook received", ['service' => 'Stripe'], 'webhooks'); // If you're using Laravel or Lumen, you can also use the Facade or service container app('honeybadger')->addBreadcrumb("Notification sent", ['user_id' => $user->id, 'type' => 'welcome']); Honeybadger::addBreadcrumb("Notification sent", ['user_id' => $user->id, 'type' => 'welcome'], 'notifications');
addBreadcrumb() method has one required parameter,
message. The message should be a terse summary of the event, which we’ll display prominently in the UI for each breadcrumb.
You can also provide:
metadata, a key-value array of contextual data about the event. The metadata should be a single-level array with simple primitives as values (strings, integers, floats, or booleans).
category, a string key used to classify and group events. See Categories for more details.
For each event, the Honeybadger client will automatically add a timestamp, so you don’t need to include that yourself.
category is a top level property of a breadcrumb. Categories are helpful so events can be presented differently on your project dashboard; for instance,
error breadcrumbs are styled with a red “error” icon.
Feel free to give a breadcrumb any category you wish. Any categories we don’t recognize will use the default ‘custom’ styling.
Here are the recognized categories and a description of how you might categorize certain activity:
|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|
To turn off collection of breadcrumbs, use the
breadcrumbs.enabled configuration option:
$honeybadger = \Honeybadger\Honeybadger::new([ 'api_key' => 'abc123', 'breadcrumbs' => [ 'enabled' => false, ], ]);
When you do this, the Honeybadger client will stop any automatic collection of breadcrumbs and the
addBreadcrumb() method will do nothing.
We use the following limits on breadcrumbs to ensure the service operates smoothly for everyone:
- We only store & transmit the last 40 breadcrumb events for any error.
- Metadata can only hold scalar values (no objects, arrays or PHP resources)
- String values have a maximum size of 64Kb