Weave Code
Laravel Queue Metrics Laravel Package
cboxdk/laravel-queue-metrics
cboxdk/laravel-queue-metrics gives Laravel apps clear visibility into queue performance: job throughput, wait times, failures, and worker activity across Redis, database, and SQS queues. Use its metrics API and dashboard to spot bottlenecks, tune workers, and keep background jobs reliable.
Production-ready Laravel queue monitoring with metrics, analytics, and insights
Frequently asked questions about Laravel Queue Metrics
- How do I install cboxdk/laravel-queue-metrics in a Laravel app?
- Install it with composer require cboxdk/laravel-queue-metrics, then publish the package configuration if you need to change defaults. It is an additive observability layer that hooks the queue lifecycle rather than replacing your queue driver. Before deploying, confirm that the Redis connection used by the metrics store is writable, since discovery reads can now set TTLs.
- Does cboxdk/laravel-queue-metrics work with database and SQS queues, or only Redis?
- It reports on job throughput, wait times, failures, and worker activity across Redis, database, and SQS queues. The metrics themselves are persisted in Redis through the RedisMetricsStore abstraction, so you still need a Redis connection even when the observed queues use another driver. Confirm your topology before spending review time, because a non-Redis environment may not be worth the extra infrastructure.
- How do I upgrade from 3.5.0 to 3.5.1, and do I need to change configuration?
- It is a patch release, so the upgrade is a Composer version bump with no new configuration surface, no schema change, and no API removal. The behavioral delta is a TTL backfill fix for persistent discovery keys plus the removal of a redundant read. Run your test suite after bumping, then watch for write-on-read behavior anywhere the metrics store sits on a read-only replica.
- Why does the metrics store need a writable Redis connection?
- listQueues() and listJobs() now apply an expiry to existing discovery keys that have none, so reads against the metrics store can mutate it. A connection pointed at a read-only replica contradicts that documented behavior and is the one item that can be genuinely blocking. The release notes do not say whether such a read throws, logs, or silently no-ops, so test it explicitly instead of assuming silent safety.
- What does the queue-metrics:calculate command do and how often should I schedule it?
- The Artisan command queue-metrics:calculate aggregates recorded queue events into the metric keys that the metrics API and dashboard read. Schedule it the same way you schedule other Laravel maintenance commands, and keep the scheduler host on the same package version as your workers. Aggregation frequency determines the freshness of historical metrics, so align it with how quickly you need to spot bottlenecks or failure spikes.
- Can I run cboxdk/laravel-queue-metrics alongside Laravel Horizon?
- Yes, it composes with Horizon rather than competing with it, because it sits beside the queue driver instead of inside it. Horizon provides live introspection of Redis queues, while this package adds historical and aggregated metrics plus job and queue discovery. If Horizon already covers your operational view, evaluate the overlap and treat the marginal value as analytics over time rather than live debugging.
- How much extra Redis load do the discovery reads add?
- The package's own technical evaluation puts saving at roughly four Redis round trips per queue and questions whether that scales linearly with queue count. Because listQueues() and listJobs() now write as well as read, frequent calls from a dashboard or health check add write amplification on a hot read path. Measure against your real queue count in staging before enabling it broadly, and audit how often your own code calls those methods.
- What happens to metrics during a rolling deploy with mixed package versions?
- The release notes state that a scheduler host still on v3.4 will not see discovery entries first recorded by v3.5 workers. That is a transient but real correctness gap in mixed-version fleets, which is exactly the state every production deploy passes through. Complete the upgrade promptly rather than leaving a long-lived mixed fleet running.
- How do legacy discovery keys without a TTL get cleaned up?
- The backfill is lazy and one-way: a key receives an expiry only when something reads it, so retired queues or job classes that are never read keep no TTL indefinitely. If you carry a long-lived v1.x install, trigger reads on those keys or delete stale entries from the discovery sets manually. After backfill, keys persist for whatever your aggregated TTL is configured to be.
- Which Laravel and PHP versions does cboxdk/laravel-queue-metrics support?
- The 3.5.1 release notes do not publish a supported Laravel or PHP version matrix, so check the package's composer.json constraints before upgrading. Validate it against your own Laravel version on a staging branch rather than assuming compatibility from the changelog. Treat the constraint check as a gating step in your review.
Weaver
How can I help you explore Laravel packages today?