laravel-queue-top maintained by caminodeldev
Laravel Queue Top
A terminal dashboard for Laravel queues.
I started this package from a very practical problem: when queues begin to grow, fail, or behave strangely, it should not take several commands and a lot of guesswork to understand what is happening.
Laravel Queue Top gives you a quick operational view from Artisan: queue snapshots, failed job summaries, worker heartbeat, health checks, diagnostics, and safe failed-job actions.
The package is intentionally careful. Most commands are read-only. The commands that can change failed jobs require explicit filters and --confirm.
Installation
composer require caminodeldev/laravel-queue-top
Publish the configuration file:
php artisan vendor:publish --tag=queue-top-config
Then try a first snapshot:
php artisan queue:top --once
Requirements
Laravel Queue Top is prepared for Laravel 10, 11, 12, and 13 through the Illuminate component constraints in composer.json.
The package is designed to work without shelling out to external tools such as redis-cli, psql, watch, or top.
Quick start
A one-shot queue snapshot:
php artisan queue:top --once
A live terminal view:
php artisan queue:top
JSON output for scripts:
php artisan queue:top --once --json
Queue health:
php artisan queue:health
Failed jobs grouped by fingerprint:
php artisan queue:failed:summary
Inspect a job safely:
php artisan queue:inspect 123
Run configuration diagnostics:
php artisan queue:doctor
Main commands
| Command | What I use it for |
|---|---|
queue:top |
See queue backlog and workers from the terminal. |
queue:health |
Get a script-friendly health result with stable exit codes. |
queue:failed:summary |
Understand repeated failures without opening every failed job. |
queue:inspect |
Inspect an active or failed job without exposing raw payloads by default. |
queue:doctor |
Check whether the queue setup looks safe and predictable. |
queue:failed:retry-safe |
Retry selected failed jobs with dry-run by default. |
queue:failed:forget-safe |
Delete selected failed jobs with dry-run by default. |
Safety defaults
This package tries hard not to surprise you.
- It does not print raw payloads by default.
- It does not deserialize queued commands during inspection.
- It redacts sensitive-looking keys when payload preview is enabled.
- It does not retry or delete failed jobs unless
--confirmis used. - It requires an explicit selection before failed-job operations.
- It keeps JSON output available for automation and logs.
Safe operations
Preview selected failed jobs:
php artisan queue:failed:retry-safe --fingerprint=abc123
Actually retry them:
php artisan queue:failed:retry-safe --fingerprint=abc123 --confirm
Preview deletion:
php artisan queue:failed:forget-safe --id=failed-job-uuid
Actually delete:
php artisan queue:failed:forget-safe --id=failed-job-uuid --confirm
Documentation
| Topic | English | Spanish |
|---|---|---|
| Command reference | docs/COMMAND_REFERENCE.md |
docs/COMMAND_REFERENCE.es.md |
| Interactive mode | docs/INTERACTIVE_MODE.md |
docs/INTERACTIVE_MODE.es.md |
| Health checks | docs/HEALTH_CHECKS.md |
docs/HEALTH_CHECKS.es.md |
| Failed jobs summary | docs/FAILED_JOBS_SUMMARY.md |
docs/FAILED_JOBS_SUMMARY.es.md |
| Job inspection | docs/JOB_INSPECTION.md |
docs/JOB_INSPECTION.es.md |
| Worker heartbeat | docs/WORKER_HEARTBEAT.md |
docs/WORKER_HEARTBEAT.es.md |
| Redis driver | docs/REDIS_DRIVER.md |
docs/REDIS_DRIVER.es.md |
| Doctor mode | docs/DOCTOR_MODE.md |
docs/DOCTOR_MODE.es.md |
| Safe operations | docs/SAFE_OPERATIONS.md |
docs/SAFE_OPERATIONS.es.md |
| Driver matrix | docs/DRIVER_MATRIX.md |
docs/DRIVER_MATRIX.es.md |
Validation
For local validation:
composer validate --strict
composer install
composer dump-autoload -o
composer lint
composer test
composer check
Branch and release style
The repository uses master as the main branch.
The release tags follow semantic versioning:
v1.0.0
v1.0.1
Contributing
Small, focused pull requests are easier to review.
Before opening a PR, please run:
composer check
Read CONTRIBUTING.md for the workflow.
Security
Please do not open public issues with secrets, tokens, private queue payloads, or production data.
Read SECURITY.md before reporting a vulnerability.
License
MIT.