Breadcrumbs in PHP

Continuing on our JavaScript and Python breadcrumb announcements, we’re happy announce native support in our PHP error tracking SDK.

What are Breadcrumbs?

Breadcrumbs are a trail of events that occurred in your application leading up to the primary error. They can be as simple as generic logging messages, or they can contain rich metadata about the state of your application: network requests, database queries, UI events, navigation changes, or even earlier occurring errors.

Breadcrumbs can be incredibly helpful in reproducing the steps that led to the error you’re debugging. We’ve been dogfooding them here at Sentry for some time, and they add critical context to errors that a stack trace alone can’t provide. Once you use them, you won’t go back.

Getting Started

Start by ensuring you’re running a recent version of our PHP SDK (sentry/sentry on composer).

From there you can capture breadcrumbs by attaching them to the Sentry instance:

<?php

$sentry = new \Raven_Client(...);

$sentry->breadcrumbs->record(array(
    'data' => array(
        'endpoint' => $rpc->endpoint,
    ),
    'category' => 'rpc',
));

You can also use standard log-style annotations:

<?php

$sentry->breadcrumbs->record(array(
    'message' => 'request to ' . $rpc->endpoint,
    'category' => 'rpc',
));

Automated Instrumentation

Automated instrumentation in PHP is fairly limited today. We currently support integration with Monolog and the native error_reporting. The error reporting hook will get installed by default, but if you’re using Monolog you just need to register another handler:

<?php

$handler = new \Raven_Breadcrumbs_MonologHandler($sentry);

$monolog->pushHandler($handler);

Note: if you’re using multiple logger instances, you’ll need to bind to each one individually.

Looking Forward

Breadcrumbs for PHP are still in the early phase, but we think there’s a lot of opportunity to integrate them into your application. Prime targets would be areas where you make RPC or HTTP calls. If you have feedback let us know by opening an issue on our public GitHub repository.