Laravel Flare Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-flare
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\Flare\FlareServiceProvider" --tag="config"
   

2. Configuration: Add your Flare API key to .env:

   FLARE_API_KEY=your_api_key_here
   

   Ensure APP_ENV is set to production (Flare only works in production).

3. First Use Case: Trigger an error in production (e.g., 1/0 in a route or controller). Flare will automatically capture and display the error in your Flare dashboard.

Key Configuration

• Logging: Add 'flare' to LOG_STACK in config/logging.php to send logs to Flare.
• Sampling: Configure minimal_log_level in config/flare.php (e.g., debug, info, warning).
• Samplers: Use RateSampler or DynamicSampler to control which requests/logs are sent (e.g., sample 10% of /admin/* routes).

First Debugging Session

1. Reproduce an error (e.g., abort(500) in a route).
2. Open Flare dashboard to see:
   • Error stack traces.
   • Request/response details (headers, payloads).
   • Database queries (if enabled).
   • Logs around the error.

Implementation Patterns

Core Workflows

1. Error Reporting

• Automatic: All uncaught exceptions in production are sent to Flare.
• Manual: Use Flare::report($exception) in custom exception handlers or middleware.

  use Spatie\Flare\Flare;
  
  try {
      // Risky code
  } catch (\Exception $e) {
      Flare::report($e);
      throw $e; // Re-throw to ensure Laravel's error handling runs
  }
  

2. Logging

• Configure Log Channel:

  // config/logging.php
  'channels' => [
      'flare' => [
          'driver' => 'flare',
          'minimal_log_level' => env('FLARE_LOG_LEVEL', 'debug'),
      ],
  ],
  

• Log Messages:

  \Log::debug('User logged in', ['user_id' => 123]);
  

  Flare will display logs with timestamps, levels, and context.

3. Performance Monitoring

• Sampling:

  // config/flare.php
  'sampler' => \Spatie\Flare\Samplers\DynamicSampler::class,
  'sampler_config' => [
      'rules' => [
          ['route_name' => 'admin.*', 'sample_rate' => 0.1], // Sample 10% of admin routes
          ['queue_name' => 'high-priority', 'sample_rate' => 1.0], // Sample all high-priority jobs
      ],
  ],
  

• Traces: Enable for HTTP requests, queues, and Livewire components (auto-detected).

4. Custom Data Collection

• Add Custom Attributes:

  // config/flare.php
  'collects' => [
      'custom' => function () {
          return [
              'app_version' => \Spatie\Flare\Flare::appVersion(),
              'feature_flags' => \App\Services\FeatureFlags::enabled(),
          ];
      },
  ],
  

• Request/Console Attributes:

  // config/flare.php
  'request_attribute_provider' => \App\Providers\FlareRequestAttributes::class,
  'console_attribute_provider' => \App\Providers\FlareConsoleAttributes::class,
  

Integration Tips

1. Middleware for Selective Reporting

public function handle($request, Closure $next)
{
    try {
        return $next($request);
    } catch (\Exception $e) {
        if ($request->is('api/v1/*')) {
            Flare::report($e);
        }
        throw $e;
    }
}

2. Queue Job Monitoring

• Flare automatically traces queue jobs. Use DynamicSampler to control sampling:

  'sampler_config' => [
      'rules' => [
          ['queue_name' => 'notifications', 'sample_rate' => 0.5],
      ],
  ],
  

3. Livewire Component Traces

• No extra setup required for Livewire v3/v4. Flare captures component lifecycle and method calls.

4. Database Query Logging

• Enable in config/flare.php:

  'database' => [
      'enabled' => true,
      'query_logging' => true,
  ],
  

• View slow queries in Flare’s "Database" tab.

5. Environment-Specific Config

• Use .env to toggle Flare:

  FLARE_ENABLED=false  # Disable in staging
  

Gotchas and Tips

Pitfalls

1. API Key Leaks:

   • Never commit .env to version control. Use environment-specific keys.
   • Fix: Add .env to .gitignore and use php artisan config:clear after key changes.

2. Performance Overhead:

   • Sampling reduces overhead, but high sample_rate (e.g., 1.0) can slow down production.
   • Fix: Start with 0.1 and adjust based on monitoring.

3. Sensitive Data Exposure:

   • Flare captures request/response bodies, cookies, and sessions by default.
   • Fix: Configure censoring in config/flare.php:

     'censor' => [
         'headers' => ['authorization', 'cookie'],
         'query' => ['password', 'token'],
         'body' => ['credit_card'],
     ],
     

4. Queue Job Sampling:

   • Jobs processed via queue:work --sync may not be sampled correctly.
   • Fix: Use DynamicSampler with queue_connection rules:

     'sampler_config' => [
         'rules' => [
             ['queue_connection' => 'database', 'sample_rate' => 0.5],
         ],
     ],
     

5. Livewire Debugging:

   • Stack traces for Livewire components may appear truncated.
   • Fix: Ensure APP_DEBUG=false in production (Flare handles debugging).

6. Log Level Filtering:

   • Logs below minimal_log_level are dropped before leaving the app.
   • Fix: Set minimal_log_level to debug for development, warning for production.

7. Flare Daemon:

   • The DaemonSender routes data through a local Flare daemon (useful for air-gapped environments).
   • Fix: Install the Flare daemon and configure:

     'sender' => \Spatie\Flare\Senders\DaemonSender::class,
     

Debugging Tips

1. Verify Installation:

   • Check if Flare is active:

     php artisan flare:status
     

   • Expected output: Flare is active.

2. Test Locally:

   • Use FLARE_API_KEY=test_key to simulate production behavior without real API calls.

3. Check Config:

   • Validate config/flare.php for typos or missing keys (e.g., sampler_config).
   • Run:

     php artisan config:clear
     

4. Inspect Payloads:

   • Enable FLARE_DEBUG=true to log raw payloads to storage/logs/flare.log.

5. Common Errors:

   • Class not found: Ensure spatie/flare-client-php is installed and compatible.
   • Missing API key: Verify .env and config/flare.php.
   • No data in Flare: Check APP_ENV=production and network connectivity.

Extension Points

1. Custom Collectors:

   • Extend Spatie\Flare\Collectors\Collector to add app-specific data:

     namespace App\FlareCollectors;
     
     use Spatie\Flare\Collectors\Collector;
     
     class UserCollector extends Collector
     {
         public function collect(): array
         {
             return [
                 'current_user' => auth()->user()?->id,
             ];
         }
     }
     

   • Register in config/flare.php:

     'collectors' => [
         \App\FlareCollectors\UserCollector::class,
     ],
     

2. Override Samplers:

   • Create a custom sampler:

     namespace App\Samplers;
     
     use Spatie\Fl