Getting Started

Install the package with Composer and publish its config if the package exposes one (php artisan vendor:publish). Point the package at a Redis connection used for queue metrics.
Confirm that Redis connection is writable. Discovery pruning happens during reads, so a read-only replica is not a valid metrics store connection.
Run php artisan queue-metrics:calculate once manually and inspect listQueues() / listJobs() through the package API or your own tinker session. This is the quickest way to confirm discovery is working.
First real use case: schedule queue-metrics:calculate in app/Console/Kernel.php or the Laravel 11+ scheduler, then build a dashboard or alert around discovered queues and job classes. Start with one queue and one worker before broadening discovery.

Implementation Patterns

Schedule queue-metrics:calculate on a fixed cadence rather than calling it ad hoc. The command is the normal aggregation entry point, and v3.5.1 makes it cheaper on Redis by reading the discovered job list once per run instead of once per queue.
Treat discovery as a side effect of job execution: a queue is marked as seen when a job starts, not when it is pushed. If you need a queue to appear in listQueues(), dispatch and process at least one real job on it.
Use the store API (listQueues(), listJobs()) for dashboards, health checks, and “which queues exist?” admin screens. Do not assume the lists are append-only; reads can now prune persistent legacy keys by applying the aggregated TTL.
During rolling deploys, keep scheduler hosts and workers on compatible versions. A scheduler host still on v3.4 will not see entries first discovered by v3.5 workers until it is upgraded.
If you maintain custom tooling around RedisMetricsStore, use expireIfPersistent() when you need “set a TTL only if the key exists and has none.” It is useful for repairing old keys without overwriting existing TTLs.
For integrations, prefer reading metrics after queue-metrics:calculate completes, not concurrently with it. That keeps dashboards aligned with the latest aggregation run.

Legacy v1.x discovery keys ({prefix}:discovery:queues and {prefix}:discovery:jobs) may still exist without a TTL. v3.5.1 repairs them lazily: the first read applies the aggregated TTL. A legacy key that already has a TTL is left alone.
Because reading discovery can write a TTL, the Redis connection must be writable. A read-only replica will break or silently fail this repair path.
Do not expect queues to appear just because jobs were pushed. Only a job starting marks a queue as seen. Idle or push-only queues can remain invisible.
Mixed-version deploys are the main operational trap: v3.4 scheduler hosts do not see discovery entries first written by v3.5 workers. Upgrade schedulers alongside workers, or accept a temporary gap in visibility.
If you are upgrading from v1.x, expect stale queue and job entries to disappear only as they are read after upgrading. If you need immediate cleanup, inspect the legacy keys directly and set or remove TTLs deliberately.
queue-metrics:calculate is now more efficient on Redis, but it still reads discovery data each run. For very large installs, monitor command duration and Redis round trips after upgrading.
Use expireIfPersistent() carefully: it only acts on existing keys without a TTL, so it will not create missing keys or extend keys that already expire.