Laravel Top Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require leventcz/laravel-top
   

2. Publish Configuration (optional, uses defaults otherwise):

   php artisan vendor:publish --tag="top"
   

3. Run the CLI tool:

   php artisan top
   

First Use Case

• Debugging Production Issues: Run php artisan top during a production incident to identify the busiest routes, memory spikes, or slow queries in real-time. The output shows:
  • Top 20 busiest routes (URI, HTTP method, request rate, memory usage, average duration).
  • Aggregated metrics for HTTP requests, database queries, and cache operations.

Where to Look First

• CLI Output: Focus on the Top Routes section to identify performance bottlenecks.
• Facade API: Use Top::routes() or Top::http() in custom scripts or tests to programmatically access metrics.
• Configuration: Check config/top.php for Redis connection settings and recording modes.

Implementation Patterns

Core Workflows

1. Real-Time Monitoring in Production:

   • Run php artisan top in a production environment to monitor live traffic across all servers (via shared Redis).
   • Use the recording_mode config to toggle between runtime (default, only during CLI execution) and always (continuous recording).

2. Programmatic Access:

   • Integrate metrics into custom scripts or dashboards using the facade:

     $topRoutes = Top::routes();
     $topRoutes->each(function ($route) {
         if ($route->averageDuration > 1000) { // >1s
             // Trigger alert or log
         }
     });
     

3. CI/CD Integration:

   • Add a post-deploy step to validate performance:

     php artisan top --format=json | jq '.http.averageDuration' > /tmp/deploy_metrics.json
     

   • Compare metrics against thresholds to fail builds if performance degrades.

4. Multi-Server Environments:

   • Ensure all Laravel servers share the same Redis connection. Metrics will aggregate across all instances.

Integration Tips

• Laravel Octane:

  • The package is compatible with Octane, but test in staging first to confirm event propagation works as expected.
  • Use recording_mode=always cautiously, as it may impact Octane’s event loop performance under high load.

• Redis Optimization:

  • Monitor Redis memory usage if running in high-traffic environments. The short TTL (default: 5s) mitigates historical bloat, but high request rates may still require tuning (e.g., Redis pipelining).

• Custom Metrics:

  • Extend the package by listening to additional Laravel events (e.g., jobs.processed) and pushing data to Redis using the same pattern as the core package.

• Alerting:

  • Pipe CLI output to monitoring tools (e.g., Slack, PagerDuty) for automated alerts:

    php artisan top --format=json | jq -r '.routes[] | select(.averageDuration > 1000) | "🚨 Slow route: \(.uri) - \(.averageDuration)ms"' | curl -X POST -d @- https://hooks.slack.com/services/...
    

• Testing:

  • Use the facade in unit tests to validate performance expectations:

    public function test_route_performance()
    {
        $routes = Top::routes();
        $this->assertLessThan(500, $routes->first()->averageDuration, 'Route is too slow');
    }
    

Gotchas and Tips

Pitfalls

1. Redis Dependency:

   • The package requires Redis 5.0+. If Redis is down, the CLI will fail or show stale data. Handle this gracefully in production:

     try {
         $metrics = Top::http();
     } catch (\RedisException $e) {
         // Fallback to logs or cached metrics
         Log::error('Top metrics failed: ' . $e->getMessage());
     }
     

2. Recording Mode Quirks:

   • recording_mode=always records metrics continuously, which may impact performance in high-traffic apps. Use sparingly and monitor Redis load.
   • In runtime mode (default), metrics are only recorded when php artisan top is running. This can lead to gaps in data if the CLI isn’t actively monitored.

3. Excluded Metrics:

   • The package ignores:
     • Queue jobs and Artisan commands (only HTTP requests are tracked).
     • Non-Redis cache stores (only the default cache is monitored).
   • Workaround: Use Laravel’s built-in logging or third-party tools for these use cases.

4. Preflight Requests:

   • OPTIONS/preflight requests may skew metrics. Filter them out in custom scripts:

     $routes = Top::routes()->reject(fn ($route) => $route->method === 'OPTIONS');
     

5. Multi-Server Data Accuracy:

   • Metrics aggregate across all servers using the same Redis connection. If servers use different Redis instances, data will be siloed.

6. Laravel 13.x/Octane Edge Cases:

   • Untested in Octane’s async event loop. If using Octane, verify that metrics update correctly during concurrent requests.
   • The package assumes traditional request lifecycle. Octane’s Swoole/ReactPHP workers may introduce subtle timing differences.

Debugging Tips

1. CLI Output Issues:

   • If php artisan top hangs or crashes, check Redis connectivity and Laravel logs (storage/logs/laravel.log).
   • Ensure the Redis connection in config/top.php matches your config/database.php settings.

2. Stale or Missing Data:

   • Data is aggregated over the last 5 seconds by default. If metrics appear stale, increase the TTL in the Redis config or adjust your monitoring frequency.
   • For recording_mode=always, ensure the process running Laravel isn’t terminated (e.g., in a long-running Octane server).

3. High Memory Usage:

   • Monitor Redis memory usage with redis-cli info memory. If spikes occur, reduce the aggregation window or optimize Redis settings (e.g., maxmemory-policy).

4. Facade API Race Conditions:

   • The facade is thread-safe for most use cases, but avoid concurrent writes to Redis (e.g., multiple Top::startRecording() calls). Use locks if needed:

     \Illuminate\Support\Facades\Lock::options(['timeout' => 10])->block('top-recording-lock', function () {
         Top::startRecording();
     });
     

Extension Points

1. Custom Metrics:

   • Extend the package by publishing your own Redis keys for additional metrics. Example:

     // In a service provider
     event(new \Leventcz\Top\Events\RequestHandled($request));
     // Then push custom data to Redis using the same key pattern as the package.
     

2. Override Templates:

   • Customize the CLI output by overriding the Twig templates in vendor/leventcz/laravel-top/resources/views. Publish the views first:

     php artisan vendor:publish --tag="top-views"
     

3. Add New Data Sources:

   • Listen to additional Laravel events (e.g., illuminate.query) and push data to Redis using the package’s Top::store() method (if exposed in future versions).

4. Modify Aggregation Logic:

   • Override the aggregation window (5s) by modifying the Redis TTL or extending the Leventcz\Top\Services\Aggregator class.

Configuration Quirks

1. Redis Connection:

   • The default connection (default) assumes Redis is configured in config/database.php. If using a custom connection, specify it explicitly:

     'connection' => 'cache',
     

2. Recording Mode:

   • recording_mode=always is not recommended for production unless you’re actively monitoring Redis performance. Prefer runtime mode for most use cases.

3. Environment-Specific Settings:

   • Use environment variables to toggle settings across environments:

     'recording_mode' => env('TOP_RECORDING_MODE', 'runtime'),
     

   • Example .env:

     TOP_RECORDING_MODE=always
     TOP_REDIS_CONNECTION=cache
     

Performance Considerations

1. High Traffic:

   • At >5k RPS, Redis may become a bottleneck. Test with redis-benchmark and tune Redis settings (e.g., appendfsync everysec, maxmemory-policy allkeys-lru).

2. Octane Compatibility:

   • Octane’s async workers may introduce slight delays in metric collection. Test in staging to validate accuracy.

3. Memory Leaks:

   • Monitor Laravel’s memory usage when recording_mode=always is active. The package should not leak memory, but high request rates may stress Redis.