Bugsnag Psr Logger Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bugsnag/bugsnag-psr-logger:^2.0
   

   Ensure bugsnag/bugsnag is also installed (required dependency).

2. Basic Configuration Add to your config/logging.php under channels (PSR-3 v3 compliant):

   'bugsnag' => [
       'driver' => 'custom',
       'via' => \Bugsnag\PsrLogger\BugsnagLogger::class,
       'config' => [
           'apiKey' => env('BUGSNAG_API_KEY'),
           'releaseStage' => env('APP_ENV') === 'production' ? 'production' : 'development',
       ],
   ],
   

3. First Use Case Replace a standard PSR-3 logger (e.g., Monolog) with the BugSnag logger in your application:

   $logger = app('log')->channel('bugsnag');
   $logger->error('Failed to process payment', ['user_id' => 123]);
   

Implementation Patterns

Logger Integration

1. Replace Existing Loggers Use the BugSnag logger as a fallback or primary channel for error tracking (PSR-3 v3 compliant):

   // In AppServiceProvider@boot()
   $logger = new \Bugsnag\PsrLogger\BugsnagLogger(
       new \Bugsnag\Client(env('BUGSNAG_API_KEY')),
       env('APP_ENV') === 'production' ? 'production' : 'development'
   );
   app()->bind(\Psr\Log\LoggerInterface::class, fn() => $logger);
   

2. Conditional Logging Route critical errors to BugSnag while keeping debug logs in Monolog:

   if (config('app.env') === 'production') {
       app('log')->channel('bugsnag')->error('Critical failure', $context);
   } else {
       app('log')->debug('Debug info', $context);
   }
   

3. Middleware for Error Tracking Log exceptions in middleware:

   public function handle($request, Closure $next)
   {
       try {
           return $next($request);
       } catch (\Throwable $e) {
           app('log')->channel('bugsnag')->error('Middleware error', [
               'exception' => $e,
               'request' => $request->all(),
           ]);
           throw $e;
       }
   }
   

Contextual Logging

Leverage structured logging for richer error context:

app('log')->channel('bugsnag')->critical('Database migration failed', [
    'migration' => 'CreateUsersTable',
    'batch_size' => 1000,
    'user_count' => DB::table('users')->count(),
]);

Release Stages

Use releaseStage to differentiate environments:

$logger = new \Bugsnag\PsrLogger\BugsnagLogger(
    $bugsnagClient,
    env('APP_ENV') === 'staging' ? 'staging' : 'production'
);

Gotchas and Tips

Pitfalls

1. PSR-1 vs PSR-3 Compatibility PSR-1 is no longer supported in v2.0. Use bugsnag/bugsnag-psr-logger:^1.0 if you need PSR-1 compatibility.

2. Double Reporting Avoid logging the same error to both BugSnag and another service (e.g., Sentry). Use a single channel for critical errors.

3. Performance Overhead BugSnag’s HTTP requests add latency. Avoid logging in high-frequency loops (e.g., API rate-limiting checks).

4. Context Size Limits BugSnag truncates large payloads. Keep context data under 200KB to avoid silent failures.

5. Sensitive Data Never log passwords, tokens, or PII. Use bugsnag()->leaveBreadcrumb() for metadata instead:

   bugsnag()->leaveBreadcrumb('User action', ['user_id' => 123]);
   

Debugging

1. Verify API Key Test with a dummy key first to ensure the logger initializes:

   $logger = new \Bugsnag\PsrLogger\BugsnagLogger(
       new \Bugsnag\Client('dummy-key'),
       'development'
   );
   $logger->error('Test error'); // Check BugSnag dashboard for this event.
   

2. Check HTTP Errors Enable BugSnag’s debug mode in config:

   'config' => [
       'apiKey' => env('BUGSNAG_API_KEY'),
       'debug' => true, // Logs HTTP issues to stderr
   ],
   

3. Log Levels BugSnag ignores debug and info levels by default. Use warning, error, or critical for visibility.

Extension Points

1. Custom Error Handling Extend the logger to add metadata (note: AbstractLogger is now Psr\Log\AbstractLogger):

   class CustomBugSnagLogger extends \Bugsnag\PsrLogger\BugsnagLogger
   {
       public function log($level, \Stringable|string $message, array $context = []): void
       {
           $context['custom_tag'] = 'my_app';
           parent::log($level, $message, $context);
       }
   }
   

2. Breadcrumbs Manually add breadcrumbs for traceability:

   bugsnag()->leaveBreadcrumb('User clicked submit', [
       'form' => 'checkout',
       'timestamp' => now()->toIso8601String(),
   ]);
   

3. Release Tracking Set release versions dynamically (e.g., from Git):

   $bugsnagClient->setReleaseStage('production');
   $bugsnagClient->setReleaseStage('v1.2.3');
   

4. MultiLogger Usage Combine BugSnag with other loggers (e.g., Monolog) for hybrid logging:

   use Bugsnag\PsrLogger\MultiLogger;
   
   $multiLogger = new MultiLogger([
       new \Bugsnag\PsrLogger\BugsnagLogger($bugsnagClient, 'production'),
       app('log')->driver(),
   ]);