Docs Platforms PHP Lumen
bugsnag.com

Lumen integration guide

Add Bugsnag error monitoring to your Lumen applications.

Installation

Add bugsnag/bugsnag-laravel to your composer.json:

$ composer require "bugsnag/bugsnag-laravel:^2.0"

Register our service provider in providers array in bootstrap/app.php before your AppServiceProvider::class:

$app->register(Bugsnag\BugsnagLaravel\BugsnagServiceProvider::class);

To use the configured Bugsnag client, import the facade each time:

use Bugsnag\BugsnagLaravel\Facades\Bugsnag;

Basic configuration

To associate your application with a project in your Bugsnag dashboard, you’ll need to set your Integration API Key in your .env file:

BUGSNAG_API_KEY=your-api-key-here

You can find this key immediately after creating a new project from your Bugsnag dashboard, or later on your project’s settings page.

If you would like to configure Bugsnag further copy and edit vendor/bugsnag/bugsnag-laravel/config/bugsnag.php to config/bugsnag.php.

For a list of available options, see the configuration options reference.

Reporting unhandled exceptions

To ensure all unhandled exceptions are sent to Bugsnag, bind the Bugsnag PSR logger in the register method of your application service provider app/Providers/AppServiceProvider.php:

$this->app->alias('bugsnag.logger', \Illuminate\Contracts\Logging\Log::class);
$this->app->alias('bugsnag.logger', \Psr\Log\LoggerInterface::class);

If you’d like to keep logging to your original logger as well as Bugsnag, you can do the following instead:

$this->app->extend(\Psr\Log\LoggerInterface::class, function ($logger, $app) {
    return new \Bugsnag\BugsnagLaravel\MultiLogger([$logger, $app['bugsnag.logger']]);
});

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Reporting handled exceptions

Reporting handled exceptions can be accomplished as follows:

try {
    // Some potentially crashy code
} catch (Exception $ex) {
    Bugsnag::notifyException($ex);
}

When reporting handled exceptions, it’s often helpful to send us custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture the following data for every exception:

  • A full stacktrace
  • Request information, including ip, headers, URL, HTTP method, and HTTP params
  • Session, cookie, and user data
  • Release stage (production, beta, staging, etc)
  • Hostname

Custom diagnostics

In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to Bugsnag. This can be accomplished by registering a function to be executed before an error report is sent:

Bugsnag::registerCallback(function ($report) {
    $report->setMetaData([
        'account' => [
            'name' => 'Acme Co.',
            'paying_customer' => true,
        ]
    ]);
});

For more information, see the customizing error reports reference.

Leaving breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. The last 25 breadcrumbs are attached to an error report to help diagnose what events lead to the error. Captured breadcrumbs are shown on your Bugsnag dashboard as a part of the error report.

Automatically captured breadcrumbs

Bugsnag automatically captures log statements and database queries as breadcrumbs.

See the configuration options to modify this behavior.

Attaching custom breadcrumbs

Leaving breadcrumbs can be accomplished by using leaveBreadcrumb as follows:

Bugsnag::leaveBreadcrumb('Something happened!');

You can optionally attach a type and metadata to a breadcrumb for additional context into the state of the application when the breadcrumb was captured. See the Breadcrumb class for the available types.

Bugsnag::leaveBreadcrumb(
    'Something happened!',
    \Bugsnag\Breadcrumbs\Breadcrumb::ERROR_TYPE
);

And with additional diagnostic metadata:

Bugsnag::leaveBreadcrumb(
    'Something happened!',
    \Bugsnag\Breadcrumbs\Breadcrumb::MANUAL_TYPE,
    ['foo' => 'bar']
);

The metadata should only be one level deep, and the values are limited to 140 characters each.

Attaching breadcrumbs from events

Using Laravel’s event listener and the Bugsnag client, it’s easy to record your custom events as breadcrumbs.

For example, to record writing to the cache as a breadcrumb:

Event::listen('Illuminate\Cache\Events\KeyWritten', function ($event) {
    Bugsnag::leaveBreadcrumb('Cache written', 'process', [
        'key' => $event->key,
        'value' => $event->value,
        'ttl' => "{$event->minutes}mins",
    ]);
});

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

If you are Lumen’s built-in authentication, we will automatically capture information about the currently authenticated user.

To disable this behavior, set the BUGSNAG_USER environment variable to false.

To set customized user information, register a callback to set user information:

Bugsnag::registerCallback(function ($report) {
    $report->setUser([
        'id' => '123456',
        'name' => 'Leeroy Jenkins',
        'email' => 'leeeeroy@jenkins.com',
    ]);
});

For more information, see configuration options.

Tracking deploys

By sending your source revision or application version to us when you deploy a new version of your app, you’ll be able to see in which deploy each error was introduced. To notify Bugsnag of your deployment directly from the artisan console, use the provided command as follows:

Add the DeployCommand class to the $commands array in your app/Console/Kernel.php file:

protected $commands = [
    // ...
    \Bugsnag\BugsnagLaravel\Commands\DeployCommand::class
];

Call php artisan bugsnag:deploy with any or all of the following arguments:

  • --repository: The URL of the source repository being deployed
  • --branch: The name of the source control branch being deployed
  • --revision: The source control revision being deployed

For example:

php artisan bugsnag:deploy \
  --repository "https://github.com/bugsnag/example" \
  --branch "master" \
  --revision "ef7bebf8bdb1919d947afe46ab4b2fb4278039b3"

For more information on the deploy tracking API, see the Deploy tracking guide.

Next steps