# laravel-top is a terminal monitor for a running Laravel application

> laravel-top adds a top command to a Laravel application that shows request, database and cache metrics in the terminal, by listening to framework events and aggregating them into Redis. It works across all the servers behind a load balancer, and it deliberately ignores work that does not arrive as an HTTP request.

**leventcz/laravel-top** — 🚀 Real-time monitoring from the command line for Laravel applications.

- Repository: https://github.com/leventcz/laravel-top
- Stars: 583 · Forks: 22
- Language: PHP
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/leventcz-laravel-top

## One artisan command, aimed at production

laravel-top provides a lightweight solution for real-time monitoring directly from the command line for Laravel applications, and it is explicitly designed for production environments, so that you can track essential metrics and identify the busiest routes without adding a hosted agent. The entry point is a single artisan command.

```php
php artisan top
```

The visual language borrows from the familiar top utility, and the project ships an animated recording of it in the repository. What makes it more than a screen is the set of numbers behind it, which the facade section later exposes in full: requests per second, memory usage and duration for HTTP, queries per second and query duration for the database, and hit, miss and write rates for the cache, plus a list of the twenty busiest routes with their average request rate, memory usage and duration. For an operator on a call, that is the difference between knowing the site is slow and knowing which endpoint is slow. The package is installed the way every Laravel package is installed.

```bash
composer require leventcz/laravel-top
```

The stated compatibility is Laravel 10 and newer with Laravel Octane, and the requirements are PHP 8.2 or newer and Redis 5.0 or newer.

## Redis is the pipeline, and the short time to live is a design decision

The how it works section is three sentences and every one of them matters. Top listens to Laravel events and saves aggregated data to Redis behind the scenes in order to calculate metrics. The aggregated data is stored with a short TTL, which ensures that historical data is not retained and prevents Redis from becoming overloaded. And during display, metrics are calculated from the average of the last five seconds of data. The consequence of putting the aggregation in Redis rather than in the application process is the next sentence, that since the data is stored in Redis, the output of the top command reflects data from all application servers and not just the server where you ran the command. For a load balanced deployment that is the feature, since the busiest route is often busiest on the other two machines, and it is also the cost, because every application server now writes to the same key space and the key rotation has to keep up. The five second window is a good default for a live view, and it is also why this is not a historical tool.

## Only incoming requests are measured, and the readme says so

There is one limitation stated plainly in the readme, and it is the one that will decide whether the tool is useful to you. Top only listens to events from incoming requests, so metrics from operations performed via queues or commands are not reflected. For a Laravel application whose heavy lifting happens in queued jobs, that is a significant blind spot, because the job that is timing out will not appear in the busiest routes list, and the console command that is slow will not appear at all. It is also, arguably, the right boundary. Instrumenting every queue worker and every artisan command would multiply the event volume for a view that is designed around request traffic, and a lighter tool that is honest about its scope is easier to reason about than a heavier one that pretends to see everything. The second limitation follows from the first, since the recording mode configuration decides when Top listens to your application, and by default it only listens while the application is running.

## Two configuration keys, and a recording mode that matters

The package publishes its configuration with the standard artisan command and a tag.

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

The published file has two settings, and the comments in it are worth reading because they explain the trade-offs. The first is the Redis connection, taken from the database configuration file, that Top will use to save data, with a default that is suitable for most applications.

```php
    /*
    |--------------------------------------------------------------------------
    | Redis Connection
    |--------------------------------------------------------------------------
    |
    | Specify the Redis database connection from config/database.php
    | that Top will use to save data.
    | The default value is suitable for most applications.
    |
    */
    'connection' => env('TOP_REDIS_CONNECTION', 'default'),
```

The second is the recording mode, which determines when Top should record metrics, and the file is explicit that by default it only listens to your application while it is running, and that you can select the always mode if you want to access metrics through the facade.

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

The always mode is the one to think about carefully. If a queued worker or an artisan command reads metrics through the facade in runtime mode, it will read nothing, because recording stopped when the request finished. The always mode fixes that and costs you the write volume on every process.

## The facade gives your code the same numbers the terminal shows

The same metrics are available to application code through a facade, which is what turns the package from a display into an instrumentation source. The request summary exposes the average requests per second, the average memory usage and the average duration. The database summary exposes the average queries per second and the average query duration. The cache summary exposes the average hit rate, miss rate and write rate per second. And the routes call returns the top twenty busiest routes, each with its URI, its HTTP method, and its average request rate, memory usage and duration.

```php
use Leventcz\Top\Facades\Top;
use Leventcz\Top\Data\Route;

// Retrieve HTTP request metrics
$requestSummary = Top::http();
$requestSummary->averageRequestPerSecond;
$requestSummary->averageMemoryUsage;
$requestSummary->averageDuration;
```

There is also direct control over the recording itself, with a call to start recording for a given duration in seconds, a call to stop it, and a call to ask whether it is currently recording. Those three functions matter for a scheduled report or a health check that wants a consistent window rather than whatever the last five seconds happened to be. The namespace layout in the source directory follows from this design, with the facade, the data objects carrying the summaries, and a route value object that the routes call returns.

## A small package with a conventional Laravel layout

The repository is a standard Laravel package skeleton, with a config directory, a source directory, a tests directory and a composer manifest, plus the pieces that show how it is maintained. There is a PHPStan configuration in the distribution, so static analysis is part of the setup rather than an aspiration, and a PHPUnit configuration for the test suite, which the readme tells you to run with a single composer command.

```bash
composer test
```

There is a changelog file, an editor configuration, a license file and a documentation site configuration. The release history is unhurried and shows a package that ships when something changes rather than on a schedule, with 1.1.0 in May 2024, 1.2.0 in March 2025 and 1.3.0 in May 2026, and the default branch is named 1.x, which tells you the maintainer is maintaining a stable line rather than developing a next major. The last push was on 2026-05-01, the same day as the newest release, and the project is MIT licensed, which for a package that sits in the request path of a production application is a sensible choice.

## Conclusion

laravel-top earns its place for a team running a Laravel application on several servers who want a quick read on which routes are hot and how slow they are, without installing a full application performance monitoring agent, and who already have Redis in the stack because the framework usually does. It is the wrong tool if you need long term history, since the aggregated data is stored with a short time to live specifically so that history is not retained, and it is the wrong tool if you care about queue workers and console commands, which the README states are not measured. Verify three things before you install it: that you meet the stated requirements of Laravel 10 or newer with Octane, PHP 8.2 or newer and Redis 5.0 or newer, that the Redis connection you point it at can take the write load of every application server, since each one writes to it, and whether the default recording mode suits you, because by default it only records while the application is running and the always mode exists for the case where you want to read metrics through the facade from a console or worker process. The licence is MIT, the newest release is v1.3.0 from 2026-05-01, and the last push was on the same day.

## FAQ

### What does the top command in laravel-top show?

It shows request, database and cache metrics in the terminal, including requests per second, memory usage, duration, queries per second, cache hit, miss and write rates, and the twenty busiest routes with their average request rate, memory usage and duration.

### Does laravel-top measure queued jobs and console commands?

No. The readme states that Top only listens to events from incoming requests, so metrics from operations performed via queues or commands are not reflected. A recording mode of always exists if you need to read metrics through the facade from those processes.

### How does laravel-top store its data, and for how long?

It listens to Laravel events and saves aggregated data to Redis, storing it with a short time to live so that historical data is not retained and Redis does not become overloaded. Metrics shown are calculated from the average of the last five seconds, and because the data lives in Redis the view covers all application servers rather than only the one you run the command on.

### What does laravel-top require?

The stated compatibility is Laravel 10 and newer with Laravel Octane, and the requirements are PHP 8.2 or newer and Redis 5.0 or newer. The package is installed with composer require, and its configuration is published with the vendor publish command using the top tag.

## Sources

- [Issues](https://github.com/leventcz/laravel-top/issues)
- [leventcz/laravel-top on GitHub](https://github.com/leventcz/laravel-top)
- [License: MIT](https://github.com/leventcz/laravel-top/blob/1.x/LICENSE)
- [README](https://github.com/leventcz/laravel-top/blob/1.x/README.md)
- [Releases](https://github.com/leventcz/laravel-top/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/leventcz-laravel-top