BugSnag is now Insight Hub – we're making some changes to how the product looks, but this won't impact the way you use BugSnag or any of your integrations.

Lumen integration guide

Add BugSnag error monitoring to your Lumen applications.

This library supports Lumen 5 running PHP 5.5+. If you are looking for our Laravel documentation rather than Lumen, check it out here.

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

Configure your BugSnag API Key in your .env file:

BUGSNAG_API_KEY=your-api-key-here

You can find your API key in your project’s settings (shortcut: gs) in the dashboard.

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

Lumen 5.6+

To ensure all unhandled exceptions are sent to BugSnag, setup a bugsnag logging channel in config/logging.php, and add it to your logging stack:

    'channels' => [
        'stack' => [
            'driver' => 'stack',
            // Add bugsnag to the stack:
            'channels' => ['single', 'bugsnag'],
        ],

        // ...

        // Create a bugsnag logging channel:
        'bugsnag' => [
            'driver' => 'bugsnag',
        ],
    ],

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

Lumen 5.0-5.5

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 out of memory exceptions

BugSnag can increase the PHP memory limit when your app runs out of memory to ensure events can be delivered. To do this, a “bootstrapper” class must be registered in your bootstrap/app.php file:

(new Bugsnag\BugsnagLaravel\OomBootstrapper)->bootstrap();

The OomBootstrapper must be called before your Lumen Application is created, otherwise Lumen will crash before BugSnag can report the error.

The amount of extra memory BugSnag allocates can be controlled with the memory limit increase option.

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.

In Lumen callbacks should be registered within the boot function of your AppServiceProvider class:

public function boot()
{
    Bugsnag::registerCallback(function($report) {
        ...
    });
}

Logging 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. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

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.

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.

Session tracking

BugSnag can track the number of “sessions” that happen in your application. This enables BugSnag to provide and compare stability scores between releases to help you understand the quality of your releases. This functionality is disabled by default, but can be enabled through the configuration:

Bugsnag::setAutoCaptureSessions(true);

Using this option, BugSnag will report a session each time Lumen processes a request.

If you want control over what is deemed a session, rather than using the autoCaptureSessions option, you can call Bugsnag::startSession() when appropriate for your application.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag SDK. You can use the Features dashboard to identify whether these features have introduced errors into your app.

Bugsnag::addFeatureFlag('Checkout button color', 'Blue')
Bugsnag::addFeatureFlag('New checkout flow')

For more information, see Feature flags & experiments.

Tracking releases

By sending your source revision or application version to us when you release a new version of your app, you’ll be able to see in which release each error was introduced.

Ensure you’ve set your app version within the application:

Bugsnag::setAppVersion('1.2.3');

You can then notify BugSnag of your build to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

This can be done using our Laravel Artisan command or you can call our Build API directly.

Next steps

• Catch and report errors in your client-side JavaScript with the Browser error monitoring guide
• View bugsnag-laravel and bugsnag-php, the open-source libraries powering BugSnag for Lumen, on GitHub
• Get support for your questions and feature requests