Queue Size Health Check Laravel Package

Technical Evaluation

Architecture fit. The package is a single-purpose Spatie Health check: it counts pending jobs on one or more queue/connection pairs and returns a failing Result when a configured ceiling is exceeded. It is additive and read-only — no schema, no service provider side effects beyond registering the check class, no interception of the queue pipeline. That makes it architecturally inert in the best sense: it observes Laravel's Queue facade and nothing else. The real architectural decision is not this package but whether the organization adopts spatie/laravel-health as its health-check substrate. If Spatie Health is already present, this is a ~100-line plugin with near-zero blast radius. If it is not, this package is a stalking horse for a much larger dependency and a new /health surface that must be reconciled with Laravel 11+'s built-in up route, your APM, and existing alerting.

Integration feasibility. Trivially feasible. composer require, publish config/health.php, add a check entry, schedule health:check. There is no migration, no data backfill, no code changes in application classes. A single engineer can have it running in an afternoon. The friction is entirely in configuration hygiene: enumerating queues and connections per environment, and picking thresholds that mean something.

Technical risk. Low technical risk, elevated dependency risk.

• Bus factor 1. Single maintainer (SRWieZ), 7 stars, 0 dependents, community support only. No evidence of a security policy or coordinated disclosure process.
• Unvalidated in the field. Zero dependents means essentially no external production validation; you are an early adopter.
• Volatility is bounded by surface area. The public API is a check class with queue/max-size setters. Even a breaking rewrite is a one-day port, so the lock-in cost is genuinely small — which cuts both ways: the package has little defensible value over an in-house equivalent.
• Transitive risk dominates. Your exposure is really spatie/laravel-health's major-version cadence (check registration, Result construction, notifier config), not this package.
• Accuracy risk is driver-dependent. Queue::size() is O(1) on Redis (LLEN) but a COUNT on the jobs table for the database driver, and an eventually-consistent ApproximateNumberOfMessages for SQS. The check is only as truthful as the driver underneath it.
• Supply chain. Release metadata should be verified against the actual tag and Composer artifact before adoption; pin to an exact version and review the diff.

Key questions.

1. Is spatie/laravel-health already in the stack, or is this package being used to justify introducing it?
2. Which queue drivers are in production (Redis / SQS / database / Beanstalkd), and what is the cost and latency of a size query on each?
3. What are the baseline and p99 queue depths per queue, measured over at least two weeks?
4. Are alerts routed per team/queue, or does everything land in one channel?
5. Is there an existing on-call owner who will receive these pages, and what is the runbook?
6. Does a second health surface conflict with the platform's existing /health or APM synthetic checks?
7. Is backlog the actual failure mode we care about, or is it failed jobs / DLQ depth — which this package does not cover?

Integration Approach

Stack fit. Native Laravel. Assumes PHP 8.1+, a supported Laravel major, and spatie/laravel-health. Standard Composer install, config publish, and one entry in the checks array. No framework-level conflicts, no middleware, no service provider overrides. It composes cleanly with existing scheduler cadence (health:check every minute or every five).

Migration path. Effectively a no-op migration. There is no persistent state, no schema, no data to move. Deployment is additive configuration, and rollback is deleting the check entry — reversible in one commit with zero downtime. Treat it as configuration, not as an integration project.

Compatibility. Two constraints to confirm before commitment: the spatie/laravel-health version constraint against your Laravel major, and the queue driver matrix. Laravel's built-in health endpoint does not conflict technically but creates two competing health surfaces — decide early which one is the system of record and have the other proxy or defer to it. If SQS is in play, accept up to ~1 minute of staleness and design thresholds accordingly.

Sequencing.

1. Inventory — enumerate every queue and connection per environment; confirm driver per queue.
2. Baseline — pull 2–4 weeks of queue depth history from existing observability (Horizon, CloudWatch, Redis metrics). Do not set a threshold without this.
3. Threshold design — set failure thresholds at roughly 2–3× observed p95 sustained depth, differentiated per queue; a background-mail queue and a payments queue do not share a ceiling.
4. Shadow mode — deploy the check with notifications disabled; run health:list in CI or a cron and compare against reality for one to two weeks.
5. Alerting — enable notifiers, starting with a low-severity channel (Slack) rather than PagerDuty, and only escalate after the false-positive rate is known.
6. Runbook + ownership — document what "queue size exceeded" means, what the first three diagnostic steps are, and who acts.
7. Pair with a failure check — add failed-jobs/DLQ monitoring, because a queue drained into a failed-jobs table looks perfectly healthy to this check.

Operational Impact

Maintenance. The package itself is close to zero-maintenance — a thin wrapper over framework APIs with a low release cadence. The real burden is maintaining the thresholds: queue ceilings drift with traffic growth, seasonal peaks, and new job types, so this needs a quarterly review or it silently becomes either noise or a rubber stamp. Because the code is ~100 lines, the correct maintenance posture is to assume you may fork or reimplement it; budget a day of engineering for that contingency and note it in the ADR.

Support. Community-only. No vendor, no SLA, no documented security process, one maintainer. Support for the check will come from your own platform team, and support for the framework from Spatie. Set expectations accordingly: nobody upstream owes you a fix. Internally, name a single owner for the health-check configuration to avoid orphaned thresholds.

Scaling. Scaling cost is in the query, not the package. Each evaluation issues one size call per configured queue × connection. Redis LLEN is O(1) and effectively free; the database driver's COUNT(*) on a large jobs table every minute is a genuine cost that needs an index on (queue, reserved_at) and, at high volume, a cached or sampled read. SQS calls are billed per request and eventually consistent, so high-frequency polling is both wasteful and misleading — prefer CloudWatch for SQS and let this check cover Redis/database only. Also budget the scheduler: N queues × M environments is N×M invocations per tick, and the check should be capped to the queues that actually matter, not every queue that exists.

Failure modes.

• Burst false positives — legitimate traffic spikes trip the threshold and self-resolve before an engineer looks. Mitigate with sustained-duration logic or requiring two consecutive failed evaluations.
• Silent success on a broken system — workers consuming jobs but failing them leave the queue empty. This check reports green while the DLQ fills. It is a backlog detector, not a health detector.
• Scheduler not running — if schedule:run is broken, the check never fires and you get silence, not an alert. Requires meta-monitoring on check liveness (heartbeat / "no result in N minutes" alert).
• Driver error reported as threshold breach — a connection failure surfaces as a check failure with a misleading message; confirm the package distinguishes exceptions from limit breaches in the notification text, and if not, wrap it.
• Eventually-consistent drivers — SQS under-reports under load, producing false negatives exactly when you most need a true positive.
• Alert fatigue — the dominant failure mode by probability; a noisy queue-size alert is trained away within two weeks and is then worse than nothing.

Ramp-up. Very shallow. A mid-level Laravel engineer is productive in under an hour: read the README, add the config entry, run health:list. No new mental model, no new infrastructure, no training program. The non-obvious work is threshold calibration and notification routing, which take one to two weeks of shadow-mode observation and are an observability task, not a package task. Total onboarding: roughly one engineer-day including baselining, plus ongoing review.

Recommendation. Adopt conditionally — high value per unit of effort, low lock-in, but gated on three things: (1) Spatie Health is already or consciously being adopted, (2) per-queue thresholds are derived from real baseline data rather than guessed, and (3) the check is paired with failed-jobs monitoring and liveness meta-monitoring so it cannot report green while the system is down. If any of those cannot be met, the honest alternative is a 50-line in-house check with no third-party dependency at all — this package's value is convenience, not capability, and a TPM should price it as such.