---
title: Capturing events with breadcrumbs
description: Learn how to use breadcrumbs to track events leading up to errors.
url: https://docs.honeybadger.io/lib/php/errors/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](https://docs.honeybadger.io/_astro/php_breadcrumbs.BVlDCoST_Z1XBDSU.webp)

Use [context](https://docs.honeybadger.io/lib/php/errors/customizing-error-reports/#custom-metadata-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](https://laravel.com/docs/logging)
* [View renders](https://laravel.com/docs/views)
* [Email dispatches](https://laravel.com/docs/mail)
* [Job dispatches](https://laravel.com/docs/queues)
* [Notification dispatches](https://laravel.com/docs/notifications)
* [Database queries](https://laravel.com/docs/queries)
* [Redis commands](https://laravel.com/docs/redis)
* 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' => '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](https://docs.honeybadger.io/_astro/php_custom_breadcrumbs.DbCe_AYo_Z1Y7a7S.webp)

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](https://docs.honeybadger.io/lib/php/errors/breadcrumbs/#categories) for more details.

For each event, the Honeybadger client will automatically add a timestamp, so you don’t need to include that yourself.

## Categories

A `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:

| 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' => '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

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)