Laravel Top Laravel Package

Getting Started

1. Install with Composer: composer require leventcz/laravel-top.
2. Ensure Redis is ready: Confirm redis is configured as a database connection in config/database.php (e.g., redis://127.0.0.1:6379) and Redis 5.0+ is running.
3. Run php artisan top — instantly see real-time HTTP metrics: requests/sec, memory, duration, DB queries, cache hits/misses, and top 20 busiest routes.
4. First use: During development, open a terminal and run php artisan top while triggering endpoints via curl or browser — watch metrics update live to catch performance regressions or route hotspots.

Implementation Patterns

• Live debugging in production: Keep an SSH session open with php artisan top running to inspect traffic surges, high-memory routes, or slow DB queries as they happen — no logs or APM setup needed.
• Octane multi-server view: In production (e.g., Laravel Octane + Horizon), top aggregates metrics from all workers/servers via shared Redis — giving a unified view of application load across infrastructure.
• Custom health checks: Use the Top facade inside a custom Artisan command (e.g., php artisan metrics:health) to programmatically fail builds/deployments if route duration exceeds thresholds (e.g., Top::routes()->firstWhere('uri', '/api/checkout')->averageDuration > 1.5).
• Embedded telemetry: Surface real-time metrics in internal admin dashboards (e.g., Filament or Inertia SPA) via Top::http(), Top::database(), etc., enabling product teams to monitor live service health without leaving the app.
• Test-assisted profiling: Wrap critical test runs with Top::startRecording(10) → run tests → Top::stopRecording() to capture and assert against metrics programmatically (e.g., ensure POST /api/upload stays under X ms).

Gotchas and Tips

• ⚠️ Only tracks HTTP requests: Queue jobs, Artisan commands, and event listeners are not monitored — use Laravel Telescope or custom Top::track() equivalents for non-HTTP workloads.
• ⚠️ Data TTL & freshness: Metrics reflect the last 5 seconds of activity; idle periods show 0.00 — restart top after traffic resumes, and expect brief spikes to vanish quickly due to short TTL.
• 🔧 recording_mode matters: In development, set TOP_RECORDING_MODE=always in .env if using Top facade outside HTTP lifecycle (e.g., in queued jobs or test bootstraps); default "runtime" only captures during live requests.
• 🛠️ Redis pitfalls: If metrics are inconsistent across servers, confirm all app instances share the same Redis connection (TOP_REDIS_CONNECTION). Verify no other tool is clearing laravel-top:* keys — the package handles cleanup automatically.
• 🐞 Error resilience gap: If Redis fails, the package does not gracefully degrade — requests may hang or error during aggregation. Always monitor Redis health in prod and consider circuit breakers.
• 🚀 Performance caveat: Under very high RPS (>10k), Redis write volume could become a bottleneck; enable TOP_RECORDING_MODE=runtime in prod to minimize overhead when not actively debugging.