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.

Breadcrumbs

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.

Automatic Breadcrumbs

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 config/honeybadger.php:

php

  

    '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,
        ],
    ],

The 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.

Custom Breadcrumbs

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):

php

  

$honeybadger = Honeybadger\Honeybadger::new(['api_key' => 'Your project API key']);
$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');

Custom breadcrumbs

The 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	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

To turn off collection of breadcrumbs, use the breadcrumbs.enabled configuration option:

php

  

$honeybadger = \Honeybadger\Honeybadger::new([
    'api_key' => 'Your project API key',
    'breadcrumbs' => [
        'enabled' => false,
    ],
]);

When you do this, the Honeybadger client will stop any automatic collection of breadcrumbs and the addBreadcrumb() method will do nothing.

Limits

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