Laravel Queue Metrics Laravel Package

Technical Evaluation

Architecture fit. The package is a Redis-backed queue observability layer for Laravel: it hooks the queue lifecycle, records discovered queues and job classes into Redis sets ({prefix}:discovery:queues, {prefix}:discovery:jobs), applies TTLs to aggregated metrics keys, and exposes an Artisan command (queue-metrics:calculate) plus a RedisMetricsStore abstraction. It sits alongside — not inside — the queue driver itself, so it composes with an existing Redis queue/Horizon topology rather than replacing it. That is a low-coupling shape, which is good: it is an additive dependency, not an architectural commitment.

The v3.5.1 release does not change that shape. It fixes a data-lifecycle defect and trims a redundant read. Both are consistent with the package's core design; neither suggests architectural drift.

Integration feasibility. This is a patch release on 3.5.0. No new configuration surface, no schema change, no API removal. Composer-level upgrade is trivially feasible; the real feasibility question is infrastructure, not code: because discovery reads now prune, the Redis connection used by the metrics store must be writable. Any team that pointed this package at a read-only replica — a reasonable choice for an observability tool — now has a topology that contradicts documented behavior. That is the one item a TPM should treat as potentially blocking.

Technical risk.

• Write-on-read paths. listQueues() / listJobs() now mutate the keys they read (expireIfPersistent() sets a TTL when the key exists and has none). Any caller that assumed those were pure reads — a dashboard, a health check, a controller — now triggers writes. Risk is low in correctness terms, moderate in blast radius if those calls are frequent or are placed on a replica.
• Lazy, one-way remediation. The legacy-key TTL backfill only happens when a key is read. Keys that are never read retain no expiry indefinitely. So the fix is a ratchet, not a sweep. Retired queues and job classes may persist on long-lived installs until something touches them — and after backfill they persist for whatever the aggregated TTL is.
• Version skew during rolling deploys. The notes explicitly state a scheduler host still on v3.4 will not see discovery entries first seen on v3.5 workers. That is a real, if transient, correctness gap in mixed-version fleets — precisely the state every production deploy passes through.
• Unknowns. The notes do not state the default aggregated TTL, whether a read against a read-only connection throws or silently no-ops, or the supported Laravel/PHP version matrix.

Key questions.

1. What is the default aggregated TTL, and is it configurable per environment?
2. On a read-only connection, does the reader raise an exception, log, or fail silently? Silent failure is the worst outcome — it looks like working software.
3. How frequently are listQueues()/listJobs() called in our own code and in any bundled dashboard? Write amplification on a hot read path matters.
4. Is there a config flag to disable write-on-read (preserving pure-read behavior for replica topologies)?
5. Does the ~4 Redis round trips per queue saving scale linearly with queue count? What queue counts was it measured against?
6. Are we on, or migrating from, a v1.x install — i.e. do we actually carry legacy no-TTL discovery keys?

Integration Approach

Stack fit. Appropriate for Laravel services on Redis-backed queues with a genuine need for queue/job inventory and throughput metrics. If the queue backend is not Redis, this package is likely out of scope — confirm before spending review time. If the team already runs Horizon, evaluate overlap: Horizon covers much of the operational view, and the marginal value here is historical/aggregated metrics, not live introspection.

Migration path. Treat this as two separate migrations:

1. Version upgrade (3.5.0 → 3.5.1) — a patch. Low ceremony: bump, run the test suite, deploy. The behavioral delta is a bug fix plus a performance tweak.
2. Legacy install remediation (v1.x → 3.5.x) — the substantive one. The TTL backfill is lazy and only fires on read, so this is not a migration that "completes." Plan for retired queues and job classes to remain visible for a full aggregated TTL after first touch, and decide whether that is acceptable or whether we should flush the discovery keys once at cutover for a clean slate.

Compatibility. Verify PHP and Laravel version constraints against our platform before committing. Confirm the Redis client (predis vs phpredis) and Redis server version support EXPIRE-style TTL semantics the store relies on — the package clearly depends on TTL introspection, so this is not a formality.

Sequencing.

1. Confirm the metrics store's Redis connection is the primary, not a replica. If it is a replica, this is a blocker to resolve first.
2. Inventory call sites of listQueues() / listJobs() and classify each as hot-path or cold-path.
3. Upgrade scheduler and workers together (or accept the documented visibility gap). The notes are explicit that a v3.4 scheduler will not see entries first seen on v3.5 workers — do not let a staggered rollout run for days.
4. Observe discovery key cardinality and TTLs for one full aggregation window post-deploy, then decide whether a one-time cleanup of stale members is warranted.
5. Roll out to one non-critical service before the fleet.

Operational Impact

Maintenance. Low. Patch-level upgrade, no config changes required, no data migration script. The package is now on a track where discovery keys self-expire, which reduces long-run operational entropy — a genuine improvement over the pre-2.0 behavior the notes describe, where every retired job class accumulated forever.

Support. The documentation additions are the most operationally useful part of this release: they convert three implicit assumptions into stated ones (writable connection, only job start marks a queue seen, version-skew visibility). Support burden should drop if teams read them. Realistically, the read-only-replica constraint will be discovered by someone at 2am unless we surface it in our own runbook.

Scaling. The queue-metrics:calculate change — reading the discovered job list once per run rather than once per queue — is a real if modest win, roughly four Redis round trips saved per queue after the first. On a fleet with dozens of queues this is meaningful during scheduled calculation; on three queues it is noise. The saving is in command runtime, not steady-state request latency, so expect it to matter for batch windows and Redis load, not for user-facing p99.

Failure modes.

• Read-only replica configured as the store → pruning and TTL backfill cannot occur; legacy keys persist and, depending on error handling, reads may throw. Highest-severity item in this release.
• Never-read keys → legacy no-TTL discovery sets survive indefinitely on installs that never query them. Silent, slow, and hard to notice.
• Rolling deploy skew → scheduler on 3.4 misses jobs first seen on 3.5 workers. Transient queue-visibility gaps; confusing if someone is debugging a missing queue mid-deploy.
• Write amplification → if listQueues() sits behind a frequently-polled dashboard, every poll now performs TTL writes on the primary.
• Slow decay by design → retired queues remain listed for up to the aggregated TTL after backfill. Not a bug, but it will be reported as one.

Ramp-up. Small. An engineer familiar with Laravel queues and Redis needs under an hour with the docs to operate this safely. The non-obvious knowledge is concentrated in two facts — reads mutate, and discovery is pruned by reading — and both are now documented. The risk is not skill, it is that the read-only-replica constraint lives in prose rather than in a startup check or a config validation, so it can be missed by anyone who does not read the discovery page.