Sending events to Insights

Honeybadger’s PHP (v2.19+) and Laravel (v4.1+) packages can be used to send events to Insights.

Automatic instrumentation

If you’re using Laravel or Lumen, Honeybadger provides automatic instrumentation to capture events from your apps. By default, we’ll record:

You can customise this with the events option in your config/honeybadger.php:

    'events' => [
        'enabled' => true,

        'automatic' => [
            Events\DatabaseQueryExecuted::class,
            Events\DatabaseTransactionStarted::class,
            Events\DatabaseTransactionCommitted::class,
            Events\DatabaseTransactionRolledBack::class,
            Events\CacheHit::class,
            Events\CacheMiss::class,
            Events\JobQueued::class,
            Events\MailSending::class,
            Events\MailSent::class,
            Events\MessageLogged::class,
            Events\NotificationSending::class,
            Events\NotificationSent::class,
            Events\NotificationFailed::class,
            Events\RedisCommandExecuted::class,
            Events\RouteMatched::class,
            Events\ViewRendered::class,
        ],
    ],

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

Manually sending events

You can also send events manually. Start by configuring Honeybadger and enabling events:

$honeybadger = Honeybadger\Honeybadger::new([
  'api_key' => 'my-api-key',
  'events' => [
    'enabled' => true
  ]
]);

Then you can send events using the $honeybadger->event method:

$honeybadger->event('user_activity', [
  'action' => 'registration',
  'user_id' => 123
])

The first argument is the type of the event (event_type) and the second argument is an object containing any additional data you want to include.

$honeybadger->event can also be called with a single argument as an object containing the data for the event:

$honeybadger->event([
  'event_type' => 'user_activity',
  'action' => 'registration',
  'user_id' => 123
])

A timestamp field (ts) will be automatically added to the event data if it is not provided, regardless of the method used to send the event.

These events may be found using the following BadgerQL query:

fields @ts, @preview
| filter event_type::str == "user_activity"
| filter action::str == "registration"
| sort @ts

Automatic log instrumentation

You can send your application logs to Insights either by sending them to Honeybadger from your infrastructure or if you are using Monolog, you can register Honeybadger’s LogEventHandler class as a handler:

$logger = new Monolog\Logger('my-logger');
$honeybadger = Honeybadger\Honeybadger::new([
    'api_key' => 'my-api-key'
]);
$logger->pushHandler(new Honeybadger\LogEventHandler($honeybadger));
$logger->info('An info message');
$logger->info('An info message with context data', ["some-key" => "some-value"]);
$logger->error('An error message');

You can send an optional second argument to the LogEventHandler constructor to specify the minimum log level to be sent to Honeybadger. The default is Monolog\Logger::INFO.

new Honeybadger\LogEventHandler($honeybadger, Monolog\Logger::DEBUG);

This will send all log messages to Insights, where they will be displayed in the Insights section of your dashboard.

Using Laravel or Lumen

If you are using Laravel or Lumen, register a custom channel in your config/logging.php, making use of the HoneybadgerLogEventDriver:

    'channels' => [
        // ...
        'honeybadger' => [
            'driver'  => 'custom',
            'via' => Honeybadger\HoneybadgerLaravel\HoneybadgerLogEventDriver::class,
            'name' => 'honeybadger',
            'level' => 'info',
        ],
    ],

Now you can write log messages as normal with Laravel’s log facade, and they’ll show up in Honeybadger Insights:

Log::channel('honeybadger')->info('An info message');
Log::channel('honeybadger')->error('An error message with context', ["some-key" => "some-value"]);

Add this custom channel to your default stack and voilà, all your log messages will appear in Honeybadger Insights:

    'channels' => [
        'stack' => [
            'driver' => 'stack',
            'channels' => ['single', 'honeybadger'],
            'ignore_exceptions' => false,
        ],
        // ...
    ],

Ignoring events

You can ignore events programmatically using the beforeEvent callback. This callback is called before an event is sent to Honeybadger. If the callback returns false, the event will not be sent.

For example, you can ignore events based on the event type:

$honeybadger->beforeEvent(function (&$event) {
    if ($event['event_type'] === 'user_activity' && $event['action'] === 'registration') {
        return false;
    }
});

Or, you may modify the event data before it is sent:

$honeybadger->beforeEvent(function (&$event) {
    $event['user_id'] = 456;
});

Note: You can register multiple beforeEvent callbacks. If any of them return false, the event will not be sent.

Sampling events

If you find that you’d like to report fewer events in order to minimize your quota consumption, you can update your configuration in config/honeybadger.php to conditionally send a certain percentage of events:

    'events' => [
        'enabled' => true,
        'sample_rate' => 10
    ]

This will send 10% of events not associated with a request, and all events for 10% of requests.