Web Snapshot Profiler Event Subscriber Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aeatech/web-snapshot-profiler-event-subscriber
   

2. Register the Subscriber Add the subscriber to your EventServiceProvider (app/Providers/EventServiceProvider.php):

   protected $listen = [
       // ... other listeners
       'kernel.request' => [
           \Aeatech\WebSnapshotProfilerEventSubscriber\WebSnapshotProfilerEventSubscriber::class,
       ],
   ];
   

3. Configure Profiler Publish the config file (if available) and adjust settings in config/web-snapshot-profiler.php:

   php artisan vendor:publish --provider="Aeatech\WebSnapshotProfilerEventSubscriber\WebSnapshotProfilerEventSubscriberServiceProvider"
   

   Enable profiling for specific routes or environments:

   'enabled' => env('APP_ENV') === 'production',
   'routes' => ['/admin/*', '/api/v1/*'],
   

4. First Use Case Trigger a snapshot for a specific request in a controller:

   use Aeatech\WebSnapshotProfilerEventSubscriber\Facades\WebSnapshotProfiler;
   
   public function index()
   {
       WebSnapshotProfiler::snapshot('homepage_load');
       return view('home');
   }
   

Implementation Patterns

Workflow: Production Profiling

1. Enable for Critical Paths Use middleware to enable profiling only for high-traffic or performance-critical routes:

   public function handle($request, Closure $next)
   {
       if ($request->is('/checkout*')) {
           WebSnapshotProfiler::enable();
       }
       return $next($request);
   }
   

2. Conditional Snapshots Capture snapshots dynamically based on user roles or request data:

   if (auth()->user()->isAdmin()) {
       WebSnapshotProfiler::snapshot('admin_dashboard');
   }
   

3. Batch Processing For CLI commands or queue jobs, use the WebSnapshotProfiler::start() and stop() methods:

   WebSnapshotProfiler::start('job_processing');
   // ... job logic
   WebSnapshotProfiler::stop();
   

Integration Tips

• Laravel Debugbar Compatibility If using barryvdh/laravel-debugbar, disable the profiler in config/debugbar.php to avoid conflicts:

  'enabled' => env('APP_ENV') !== 'production',
  

• Storage Backend Extend the default storage (e.g., database or S3) by implementing Aeatech\WebSnapshotProfilerEventSubscriber\Contracts\SnapshotStorage:

  class CustomStorage implements SnapshotStorage {
      public function store(Snapshot $snapshot) { ... }
  }
  

• API Endpoints Expose snapshots via an API route:

  Route::get('/api/snapshots', function () {
      return WebSnapshotProfiler::getSnapshots();
  });
  

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Issue: Profiling adds latency. Even in production, avoid enabling globally.
   • Fix: Use route-based or conditional enabling:

     'routes' => ['/performance-critical/*'],
     

2. Memory Leaks

   • Issue: Storing too many snapshots can bloat storage.
   • Fix: Implement a cleanup job:

     WebSnapshotProfiler::pruneOldSnapshots(Carbon::now()->subDays(7));
     

3. Event Ordering

   • Issue: Snapshots may not capture the full request lifecycle if not triggered at the right kernel.* event.
   • Fix: Use kernel.request for start and kernel.terminate for end:

     'kernel.request' => [\Aeatech\WebSnapshotProfilerEventSubscriber\WebSnapshotProfilerEventSubscriber::class . '@onRequest'],
     'kernel.terminate' => [\Aeatech\WebSnapshotProfilerEventSubscriber\WebSnapshotProfilerEventSubscriber::class . '@onTerminate'],
     

Debugging

• Missing Snapshots

  • Check if the subscriber is registered in EventServiceProvider.
  • Verify APP_DEBUG is false in production (some profilers ignore snapshots in debug mode).

• Storage Issues

  • Ensure the storage directory (storage/snapshots) is writable:

    chmod -R 775 storage/snapshots
    

Extension Points

1. Custom Metrics Add custom metrics to snapshots:

   WebSnapshotProfiler::addMetric('db_queries', DB::getQueryLog()->count());
   

2. Snapshot Filters Filter snapshots by tags or metadata:

   WebSnapshotProfiler::snapshot('user_login', ['user_id' => auth()->id()]);
   

3. Webhook Notifications Extend the subscriber to send alerts for slow snapshots:

   public function onTerminate(Request $request, $response)
   {
       $snapshot = WebSnapshotProfiler::getLastSnapshot();
       if ($snapshot->durationMs > 1000) {
           // Send Slack/Email alert
       }
   }
   

Config Quirks

• Environment Variables Override settings via .env:

  WEBSNAPSHOT_PROFILER_ENABLED=true
  WEBSNAPSHOT_PROFILER_ROUTES=/admin*,/api/*
  

• Default Storage Change the default storage path in config/web-snapshot-profiler.php:

  'storage' => storage_path('app/snapshots'),