Queue Size Health Check Laravel Package

Getting Started

Install the package alongside Spatie Health and confirm the check class/builder names in the package README before wiring it up:

composer require srwiez/queue-size-health-check
php artisan vendor:publish --tag=health-config # if you have not published Spatie Health config

Look first at:

1. vendor/srwiez/queue-size-health-check/README.md for the exact check class and fluent methods.
2. config/health.php and your AppServiceProvider for where Spatie Health checks are registered.
3. The package source if you need to confirm how thresholds are expressed, e.g. per queue, per connection, or as a single max.

The registration shape is typically:

use Spatie\Health\Facades\Health;
use SRWieZ\QueueSizeHealthCheck\Checks\QueueSizeCheck;

Health::checks([
    QueueSizeCheck::make()
        ->connection('redis')
        ->queue('default', 1000)
        ->queue('emails', 500),
]);

Treat the method names above as illustrative; use the package’s actual API. Then run:

php artisan health:check

First useful case: put a threshold on your busiest queue, schedule health:check every five or ten minutes, and route failures through your existing Spatie Health notification channel. Do not start by putting queue backlog on a load-balancer /health endpoint; use it for alerts and dashboards.

Implementation Patterns

• Set per-queue budgets, not one global number. Different queues have different normal depths. A default queue at 1,000 may be normal while emails at 200 is already a problem.
• Make thresholds environment-specific. Keep local/testing thresholds low or disabled, and production thresholds based on observed p95/p99 backlog. Example:

->queue('default', env('QUEUE_SIZE_DEFAULT_MAX', 1000))
->queue('emails', env('QUEUE_SIZE_EMAILS_MAX', 500))

• Use separate checks for separate connections. A Redis default queue and a database default queue are different failure domains. Separate checks produce clearer notifications and let you tune thresholds independently.
• Pair with worker/schedule health checks. Queue size catches growing backlog, but it cannot tell you the scheduler is dead or a worker is stuck on a poison job. Combine this check with Spatie Health’s schedule check, Horizon status if applicable, and worker heartbeat metrics.
• Validate with Laravel’s native monitor before choosing thresholds. Run php artisan queue:monitor redis:default,redis:emails --max=1000 against realistic traffic to see whether your proposed limits are sane.
• Use health history for tuning. Spatie Health stores check results; review whether failures are one-off spikes or sustained growth. Alert on sustained backlog, not a single sample.
• For critical queues, consider a second check at a lower “warning” threshold if the package/API allows multiple check instances with different names. Otherwise use the package check for the hard failure and rely on metrics for warning-level visibility.
• Test outside Queue::fake(). A faked queue may not produce real queue-size data. Use a real test connection (database queue is usually easiest), push jobs, run php artisan health:check, and assert the failure notification/result.
• Use a custom check when size is not enough. Queue depth can stay low while the oldest job is hours old. If that matters, extend the package check or write a small Spatie Health check that inspects created_at/available_at for the oldest pending job.

Gotchas and Tips

• Queue driver semantics differ. Queue::size() does not mean the same thing on Redis, database, SQS, and other drivers, especially for delayed, reserved, and in-flight jobs. Confirm what your production driver counts before trusting a threshold.
• sync and some local setups always look healthy. The sync queue has no real backlog, so the check can be green while production would fail. Keep local thresholds low or skip the check outside production-like environments.
• Failed jobs are not backlog. This check monitors pending queue size, not the failed_jobs table. Add a separate failed-job check if failed jobs matter to your team.
• The default connection can surprise you. If you do not specify a connection, the check likely follows queue.default. After changing QUEUE_CONNECTION, run php artisan config:clear or rebuild config:cache, then re-run the check.
• Large database queues can make counting expensive. Queue::size() may run a COUNT query. Avoid running the check every minute on very large queue tables without confirming indexes and query cost.
• Multiple queues with the same name need explicit connections. If both Redis and the database have a default queue, register separate checks or explicitly scope each check to its connection.
• Do not make queue backlog a liveness probe. A deep queue should page the team; it should not necessarily remove web instances from a load balancer.
• Tune notification behavior. Spatie Health can notify on state changes depending on configuration. Confirm whether you get one alert per failure, repeated alerts, or recovery notifications, and avoid alert storms during traffic spikes.
• Debug by running the underlying query directly. In php artisan tinker, compare Queue::connection('redis')->size('default') with the health check result. If they disagree, inspect the package’s connection/queue resolution.
• Pin a compatible version. v1.4.1 is a maintenance release with no functional changes from v1.4.0; ^1.4 is a reasonable constraint. Check the README when upgrading across minor versions in case builder methods or config keys changed.
• Extension points are your escape hatch. If the package only supports size thresholds, subclass its check or write a Spatie Health check that reuses the same registration/notification pipeline for oldest-job age, failed-job count, or per-queue warning thresholds.