Queue Size Health Check Laravel Package

Product Decisions This Supports

• Observability coverage gap decisions: Deciding whether queue backlog is a first-class monitored signal in your health-check stack, or something you leave to dashboards and ad-hoc alerting. This package makes "queue depth above threshold" an explicit, code-reviewable health check rather than a line on a Grafana board.
• Build vs. buy (vs. skip): If you already run Spatie Health Checks, this is a ~15-minute "buy" (free, MIT) versus writing a custom Check class that queries DB::table('jobs')->count() / the Redis queue size. The build cost is low, so the real decision is standardization: do you want one bespoke check per service, or a shared, tested package across all Laravel services?
• Incident-response and on-call design: Informs whether queue saturation should page a human, degrade a status page, or merely log. The configurable per-queue thresholds let you codify "normal backlog" vs. "stalled workers" — a policy decision, not just an engineering one.
• Release-gate and deploy-safety decisions: Queue backlog is a leading indicator of broken deploys (worker crashes, misconfigured queue names, lost connections). Wiring this into post-deploy health checks gives you an automatic rollback/alert trigger.
• Roadmap prioritization for platform teams: If multiple product squads run Laravel services, adopting a shared health-check convention is an enablement decision (platform owns it, squads consume it) rather than N teams each reinventing it.
• Use cases: async-heavy workloads (email dispatch, webhooks, media processing, report generation), autoscaling triggers keyed to backlog depth, SLA reporting on "time to drain," and pre-incident detection during traffic spikes.

When to Consider This Package

Consider adopting when:

• You use Laravel + Spatie Health Checks already — this is a drop-in Check with no new infrastructure or vendor SDK.
• Your service has queues where backlog growth is a real failure mode (worker crashes, poison jobs, upstream traffic spikes, insufficient worker concurrency).
• You want a cheap, framework-native floor under your observability — something that works even if your metrics pipeline is down or you haven't built queue dashboards yet.
• You operate multiple queues/connections and want per-queue thresholds rather than one global alarm.
• You're standardizing health checks across services and want a tested, MIT-licensed, dependency-light building block instead of copy-pasted custom checks.

Look elsewhere / deprioritize when:

• You don't use the Spatie Health package. Integrating a health framework and this check together is a bigger commitment than it looks; compare against Laravel Horizon's built-in metrics, queue:monitor, or your APM (Datadog, New Relic, Sentry) which likely already tracks queue depth.
• You have managed queue infrastructure (SQS, Redis via a managed provider, Laravel Cloud/Forge) exposing native backlog metrics — duplicating the signal may create alert noise and conflicting thresholds.
• You need latency/SLA signals, not just depth. Queue size is a coarse proxy; age-of-oldest-job and throughput are usually better predictors. This package won't tell you how long jobs have waited.
• Maturity risk tolerance is low. Single-maintainer project, low star count, near-zero dependents, and a 2026 maintenance-only release. Budget for the possibility that you fork or replace it; keep the dependency optional/isolated.
• Thresholds would be guesswork. Without baseline data on normal backlog per queue, you'll either drown in false positives or set limits so high they never fire. Establish baselines first, then codify them here.

How to Pitch It (Stakeholders)

For executives (30-second version): "We have a low-cost, low-risk way to catch stalled background processing before customers notice — missed emails, delayed webhooks, stuck reports. It's a small open-source component that plugs into our existing Laravel health checks and alerts us when queues back up past a threshold we set. No new vendor, no new infrastructure, no license cost. The trade-off is that it's a young, single-maintainer project, so we'd treat it as an easily-swappable convenience rather than a critical dependency."

For engineering:

• What it is: a Spatie Health Check that counts pending jobs per queue/connection and fails when a configurable limit is exceeded. MIT, framework-native, minimal footprint.
• Why now: it converts a manual dashboard glance into an automated, version-controlled check — code-reviewed thresholds, consistent across services, and usable as a deploy gate.
• Effort: hours, not sprints — conditional on already using Spatie Health. If not, that integration is the real scoping item.
• Risk management: isolate behind the health-check abstraction so we can swap in a custom check or APM-native metric later. Pin the version; single-maintainer project with a maintenance-only recent release.
• What it is not: a replacement for Horizon, APM queue metrics, or job-latency alerting. It's a floor, not a ceiling.
• Success measure: we detect at least one real backlog incident earlier than our prior process within the first quarter, and false-positive alert volume stays negligible.