PHPackages therealedatta/laravel-queue-health-check - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. therealedatta/laravel-queue-health-check ActiveLibrary[Logging & Monitoring](/categories/logging) therealedatta/laravel-queue-health-check ======================================== Monitor Laravel queue health with heartbeat checks and email alerts v1.1.2(3mo ago)211MITPHPPHP ^8.1CI passing Since Jan 30Pushed 3mo ago1 watchersCompare [ Source](https://github.com/therealedatta/laravel-queue-health-check)[ Packagist](https://packagist.org/packages/therealedatta/laravel-queue-health-check)[ RSS](/packages/therealedatta-laravel-queue-health-check/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (5)Dependencies (6)Versions (7)Used By (0) Laravel Queue Health Check ========================== [](#laravel-queue-health-check) A reusable Laravel package that monitors queue health via heartbeat checks. It periodically dispatches a job through the queue; if the job executes, it writes a timestamp to a file. A scheduled command checks whether that timestamp is recent and sends a **synchronous** email alert if the queue is unresponsive — and a recovery email when it comes back. How It Works ------------ [](#how-it-works) 1. The command `queue-health:check` runs on a cron schedule (configurable). 2. Each run, it checks the last heartbeat timestamp written by the job. 3. If the timestamp is older than `check_interval_minutes * 2` (minus 1 second), the queue is considered down. 4. On first detection of downtime, a synchronous alert email is sent (not queued, since the queue is down). 5. A `QueueHealthException` is reported via `report()`, which notifies any configured error tracking service (Bugsnag, Sentry, etc.) without interrupting the command flow. 6. A flag file tracks alert state — by default only one alert per incident, but repeated alerts with backoff are supported. 7. When the queue recovers (heartbeat is recent again and the flag exists), a recovery email is sent and the flag is cleared. 8. After the check, a new `QueueHealthCheckJob` is dispatched to write the next heartbeat. ### State Files [](#state-files) FilePurpose`storage/logs/queue-health.log`ISO 8601 timestamp of the last successful job execution`storage/logs/queue-health-alert.flag`JSON file tracking alert state (timestamp and count). Exists only while the queue is down.Installation ------------ [](#installation) ``` composer require therealedatta/laravel-queue-health-check php artisan vendor:publish --tag=queue-health-config ``` Configuration ------------- [](#configuration) Add to your `.env`: ``` QUEUE_HEALTH_ALERT_EMAIL=admin@example.com,devops@example.com QUEUE_HEALTH_CHECK_INTERVAL=5 ``` VariableDescriptionDefault`QUEUE_HEALTH_ALERT_EMAIL`Comma-separated list of email recipients`null` (disabled)`QUEUE_HEALTH_CHECK_INTERVAL`Minutes between checks`5``QUEUE_HEALTH_ALERT_REPEAT_INTERVAL`Alert repeat interval in minutes (see below)`null` (one alert per incident)If `QUEUE_HEALTH_ALERT_EMAIL` is missing or empty, the package does nothing. ### Alert Repeat Interval [](#alert-repeat-interval) Controls how often alerts are re-sent while the queue remains down: - **Not set / `null`**: only one alert per incident (default) - **Single value** (e.g. `60`): re-send every 60 minutes - **Comma-separated backoff** (e.g. `5,15,30,60`): the first alert is immediate, then re-alert after 5 min, then 15, then 30, then every 60 minutes indefinitely A 30-second tolerance is applied to repeat intervals to account for cron scheduling jitter, ensuring alerts fire on time rather than being delayed by one cycle. ``` # Re-alert every hour QUEUE_HEALTH_ALERT_REPEAT_INTERVAL=60 # Backoff: immediate → 5min → 15min → 30min → every 60min QUEUE_HEALTH_ALERT_REPEAT_INTERVAL=5,15,30,60 ``` Manual Queue Test ----------------- [](#manual-queue-test) You can manually verify the queue is working by dispatching a test email: ``` php artisan queue-health:test user@example.com ``` If no email is provided, it falls back to the configured `QUEUE_HEALTH_ALERT_EMAIL`: ``` php artisan queue-health:test ``` The command dispatches a job through the queue. When the worker processes it, it sends an email with timing information (dispatch time, processing time, and delay). If the delay exceeds 60 seconds, the email subject and body will flag it as a warning. If no email is configured at all, the command reports a `QueueHealthException` to your error tracking service so the misconfiguration doesn't go unnoticed. ### Error Tracking Integration [](#error-tracking-integration) Each time an alert is sent, the package calls `report(new QueueHealthException(...))`. This means any error tracking service configured in your Laravel app (Bugsnag, Sentry, Flare, etc.) will automatically receive the exception — providing a secondary alert channel that doesn't depend on email delivery. Requirements ------------ [](#requirements) - PHP >= 8.1 - Laravel 10, 11, or 12 Make sure `php artisan schedule:run` is in your crontab: ``` * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1 ``` Architecture ------------ [](#architecture) ``` src/ ├── QueueHealthCheckServiceProvider.php # Registers config, commands, and schedule ├── Commands/ │ ├── QueueHealthCheckCommand.php # Checks heartbeat, sends alert/recovery emails │ └── QueueHealthTestCommand.php # Manual test: dispatches a test email via the queue ├── Exceptions/ │ └── QueueHealthException.php # Reported to error tracking services └── Jobs/ ├── QueueHealthCheckJob.php # Writes heartbeat timestamp to file └── QueueHealthTestJob.php # Sends test email with timing diagnostics ``` ### ServiceProvider [](#serviceprovider) - Merges and publishes the config file - Registers the artisan commands - Schedules `queue-health:check` via `$schedule->command()->cron()` based on the configured interval ### QueueHealthCheckJob [](#queuehealthcheckjob) - Implements `ShouldQueue` with 3 retries and a flat 5s backoff - Writes `now()->toIso8601String()` to `storage/logs/queue-health.log` ### QueueHealthCheckCommand [](#queuehealthcheckcommand) - Exits silently if config is missing - On first run (no heartbeat file), dispatches the job without alerting - Threshold formula: `(check_interval_minutes * 2 * 60) - 1` seconds - Alert email subject: `[AppName] ALERT: Queue worker unresponsive` - Recovery email subject: `[AppName] RECOVERED: Queue worker is back` - Both emails are sent synchronously via `Mail::raw()` - Reports `QueueHealthException` via `report()` on each alert Testing ------- [](#testing) ``` composer install vendor/bin/phpunit ``` Tests use Orchestra Testbench and cover: 1. No config → does nothing, no mail, no job dispatched 2. No heartbeat file → no alert (first run) 3. Recent heartbeat → no alert 4. Old heartbeat, no flag → sends alert + creates flag + reports exception 5. Old heartbeat, flag exists, no repeat interval → no mail (already alerted) 6. Old heartbeat, flag exists, repeat interval elapsed → re-sends alert 7. Old heartbeat, flag exists, repeat interval not elapsed → no mail 8. Backoff schedule follows configured steps 9. Backoff schedule repeats last step indefinitely 10. Recent heartbeat, flag exists → sends recovery email, removes flag 11. Multiple recipients 12. Job writes heartbeat file correctly 13. Test command dispatches job with provided email 14. Test command falls back to config email 15. Test command reports exception when no email configured 16. Test job sends email with timing info 17. Test job warns when queue processing is delayed License ------- [](#license) MIT ### Health Score 38 — LowBetter than 85% of packages Maintenance82 Actively maintained with recent releases Popularity8 Limited adoption so far Community7 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 6 Last Release 96d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/512e4db1d263a5d63a20dec238db25ac78abcc2f0b9c050c02df62be9ea96a4c?d=identicon)[therealedatta](/maintainers/therealedatta) --- Top Contributors [![davidjr82](https://avatars.githubusercontent.com/u/4275886?v=4)](https://github.com/davidjr82 "davidjr82 (8 commits)") --- Tags laravelmonitoringqueuehealth check ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/therealedatta-laravel-queue-health-check/health.svg) ``` [![Health](https://phpackages.com/badges/therealedatta-laravel-queue-health-check/health.svg)](https://phpackages.com/packages/therealedatta-laravel-queue-health-check) ``` ### Alternatives [inspector-apm/inspector-laravel Code Execution Monitoring, built for developers. 2332.0M2](/packages/inspector-apm-inspector-laravel)[storviaio/vantage Vantage: Strategic queue monitoring and observability for Laravel applications. 2342.9k](/packages/storviaio-vantage) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)