HostAtlas / Tools / Queue Monitor
v0.4.1 Composer package · Laravel 10+ · Apache 2.0

hostatlas/queue-monitor - Laravel queues, finally observable.

A drop-in Composer package that ships wait time, throughput and failure rate from every queue your Laravel app uses — Redis, database, beanstalkd, SQS — to HostAtlas. No exporters to keep alive, no metrics endpoint to maintain, no payload data leaving the host.

$ composer require hostatlas/queue-monitor copy

Pair the app afterwards with php artisan hostatlas:enrol --key=YOUR_INSTALL_KEY. Generate keys in Settings → Install Keys.

p95
wait time per queue
0
payload bytes shipped
free
Apache 2.0 on Packagist
queues · last 5 min api-prod-eu · 4 workers
default
wait p95 1.2s
throughput 340/s
failures 0.3%
emails
wait p95 8.4s
throughput 12/s
failures 0.0%
image-resize
wait p95 2.1s
throughput 48/s
failures 4.2% ↑
webhooks
wait p95 220ms
throughput 82/s
failures 0.1%
backlog oldest image-resize · 12s
top failing ResizeJob · ImagickException × 47
— Why per-queue

Queues are silent until the customers tell you.

A single "queue size" gauge is the gas-station fuel-light of monitoring — it goes off when it's already a problem. Per-queue wait time + failure rate is the actual signal.

wait time is what users feel
"Jobs in queue" can be 50 or 5000 and look the same. p95 wait time tells you what the customer waiting on the email or PDF actually experiences.
failures are early warnings
A growing failure rate is usually the first sign of a downstream API, a database lock, or a deploy gone wrong. Cheap signal, expensive to miss.
per-queue SLOs
The email queue and the image queue have different SLOs. One global "queue is slow" rule fits neither. Per-queue thresholds catch the right things.
— What gets reported

Six metrics. Every queue. Every interval.

Nothing else needs configuring — every Laravel queue your app uses ends up in HostAtlas with these six values, named and tagged automatically.

wait p50 / p95
Per-queue wait time, the user-visible number. Charted, alertable, with separate thresholds per queue.
throughput
Jobs / sec. Trend line for capacity planning — see when a queue is genuinely under-provisioned.
failure rate
Failed jobs / total. Configurable thresholds; usually the earliest signal of downstream trouble.
workers
Active / idle / total. Detects when a supervisor silently stops a worker and the queue starts to back up.
top failing jobs
Job class name + count + last exception class. Names and metadata only — payloads stay on the host.
backlog age
Oldest currently-waiting job. The metric you wish you'd been tracking last time things piled up.
— Install

Two steps.

Same flow you'd use for any first-party Laravel package. No exporters, no extra services, no infrastructure changes.

1. Composer require

Pull the package into your Laravel app. Tested with Laravel 10, 11, 12; PHP 8.2+.

$composer require hostatlas/queue-monitor

2. Pair the app

Run the enrol command with an install key from your HostAtlas tenant. Queue tracking starts on the next scheduled run.

$php artisan hostatlas:enrol --key=YOUR_INSTALL_KEY
— Reference

Commands and config.

Three artisan commands and a published config file is the whole API surface.

php artisan hostatlas:enrol
One-shot pairing: links this app with a HostAtlas tenant using an install key from the dashboard.
$ php artisan hostatlas:enrol --key=YOUR_INSTALL_KEY
→ paired with tenant acme-co · queue tracking enabled
php artisan hostatlas:queue-check
Ad-hoc queue snapshot from the command line. Prints the same metrics that ship continuously to HostAtlas.
$ php artisan hostatlas:queue-check --queue=default
default · workers 4/4 · wait p95 1.2s · failures 0.3% · backlog 14
php artisan hostatlas:queue-flush
Force-ship the buffered metrics immediately. Useful after a deploy to confirm the package is talking to HostAtlas.
$ php artisan hostatlas:queue-flush
→ flushed 47 datapoints · ok
config/hostatlas-queue.php
Published by the package on install. Keep it in source control — overrides apply per environment via the usual Laravel config-cache flow.
queues · default auto
List of queue names to track. auto = every queue Laravel finds. Pass an explicit array to track only some.
thresholds · default { … }
Per-queue wait + failure thresholds. Overrides the global default; anything not listed uses the global one.
transport · default agent
How metrics reach HostAtlas. agent (recommended — ships via the local agent), direct (outbound HTTPS from the app), or none (collect-only, no shipping).
redact · default class-only
Job-class reporting mode. class-only (default — only class names), none (no class names at all), or full (include the failing job ID — never the payload).
sample · default 1.0
Failure-detail sampling rate. 1.0 = every failure, 0.1 = 10 % sample. Useful for very high-failure dev environments.
return [
'queues' => 'auto',
'thresholds' => [
'default' => ['wait_p95_ms' => 2000, 'failure_pct' => 1.0],
'emails' => ['wait_p95_ms' => 10000, 'failure_pct' => 0.5],
],
'transport' => 'agent',
'redact' => 'class-only',
];
— Honest answers

Questions that come up before the install.

Do job payloads leave the host?

No. Only metadata — queue name, job class, attempt count, exception class. Payload bodies stay on the host, always.

Does it conflict with Horizon?

No. Reads from the same sources Horizon does and runs alongside it; the package can power both views without duplicating the load on Redis.

Non-Laravel apps?

A language-agnostic statsd / OTel exporter is on the roadmap. Today: Laravel 10+ only.

Performance overhead?

Aggregation runs in a scheduled command (default: every 30 s), not in the worker hot path. Adding it shouldn't change measurable throughput.

What about queue backends?

Tested with Redis, database, beanstalkd, SQS. Anything Laravel's queue manager treats as a first-class driver should work.

Open source?

Yes — Apache 2.0 on Packagist. Hostatlas tenant required only for the platform-side dashboards + alerting; metrics can also be exported locally.

— Works with

Connected capabilities.

Stop guessing why the queue is slow.

Free on Packagist. Surfaces in your HostAtlas fleet automatically once you enrol the app.

Get early access View on GitHub