Add BugSnag error monitoring to your Lumen applications.
New to BugSnag? Create an account
Looking for performance monitoring? See our performance guide
This library supports Lumen 5 running PHP 5.5+. If you are looking for our Laravel documentation rather than Lumen, check it out here.
Add bugsnag/bugsnag-laravel to your composer.json:
$ composer require "bugsnag/bugsnag-laravel:^2.0"
The latest available version of bugsnag-laravel is v2.28.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;
Configure your BugSnag API Key in your .env file:
BUGSNAG_API_KEY=your-api-key-here
You can find your API key in Project Settings from your BugSnag 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.
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.
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.
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 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.
BugSnag will automatically capture the following data for every exception:
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) {
...
});
}
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.
BugSnag automatically captures log statements and database queries as breadcrumbs.
See the configuration options to modify this behavior.
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.
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",
]);
});
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.
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.
This feature is not available for applications running Lumen 5.2 and above as it relies on session storage which has been removed from the framework.
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.
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 client. 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.
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.
bugsnag-laravel and bugsnag-php, the open-source libraries powering BugSnag for Lumen, on GitHub