Laravel Queue Insights Laravel Package

Getting Started

1. Install and publish the config. composer require sander-muller/laravel-queue-insights, then publish and open config/queue-insights.php. That file is the whole surface area — read it before anything else, especially redis_connection and the chain_lineage block.
2. Point it at a Redis connection. The package writes to the Laravel Redis connection named by queue-insights.redis_connection (env QUEUE_INSIGHTS_REDIS, default default). If your app already uses default for cache/sessions/queues, decide now whether telemetry belongs there or on a dedicated connection — switching later means re-pointing the env var and losing history on the old connection.
3. Make sure the config is loadable everywhere. The package writes from web requests (job dispatch listeners), queue workers, and the scheduler (schedule:run / schedule:work). All three processes need the same QUEUE_INSIGHTS_REDIS value and Redis reachability. Run php artisan config:clear after touching the env.
4. First use case: dispatch a job and run the scheduler once, then look at what the package recorded. That single pass exercises both the job listener and the schedule snapshotter — if either is misconfigured you'll see it in storage/logs/laravel.log, not as an exception in your request.

Implementation Patterns

Zero-instrumentation baseline. The listeners for jobs and scheduled tasks are registered by the package's service provider; you don't add trait or middleware calls to your jobs. Get the config right, keep workers and the scheduler running, and insights accumulate. Reach for per-job customisation only after the baseline is working.

Dedicated connection for telemetry. A common day-to-day setup is a second connection under database.redis (often a separate logical database or a separate instance) and QUEUE_INSIGHTS_REDIS=insights. This keeps insight writes off the connection your queues and cache depend on, so a slow telemetry write can't add latency to a cache miss.

Hand-written connection blocks. If you define the connection by hand rather than copying the default block, it must carry everything default carries — notably url (or username) alongside password. On a managed Redis using ACL auth, omitting username produces WRONGPASS at write time, now identifiable in the log via the redis_connection context field.

Split lineage from telemetry. chain_lineage.redis_connection overrides the global connection for chain-lineage tracking. Use it when chain data is written from a different process group or you want lineage retained longer than the per-job records. It goes through the same boot-time validation as the main key.

Multi-environment rollout. Because the connection name is validated at boot from 0.34.0 onward, treat QUEUE_INSIGHTS_REDIS as a deploy-blocking config value: set it explicitly in every environment (including CI and local), or leave it unset so the default fallback applies. Don't rely on it being "probably fine" in staging.

Gotchas and Tips

• A bad connection name now fails at boot. As of 0.34.0, a queue-insights.redis_connection (or chain_lineage.redis_connection) that matches no top-level key under database.redis throws immediately, naming the value and listing the connections that are defined. This is a deliberate trade: previously the mistake surfaced much later from inside a listener or the schedule sweeper, with a message that never mentioned the requested name. Expect a deploy to fail loudly if an env var is typo'd — that's the feature working.
• No Redis configured at all is not caught. If your database.redis block is missing entirely, the package stays out of the way and lets Laravel report it. So a boot that succeeds doesn't prove telemetry is wired up; verify by running one job.
• Failures are logged, not thrown. Job and scheduled-task listeners, both schedule reconcilers, and the schedule snapshotter swallow write exceptions into the log rather than breaking your dispatch path. Consequence: telemetry can be silently absent while everything "works." Check the log for these entries whenever dashboards look empty. From 0.34.0 each entry carries redis_connection, which is the fastest way to tell a WRONGPASS on a managed instance from a genuine outage.
• Docs correction worth knowing. Earlier versions of the published config described the setting as living under config/database.php → redis.connections. That key doesn't exist in Laravel — connections are top-level keys of redis. If you're on an older published config file, re-publish or hand-edit it; the stale comment has sent people looking in the wrong place.
• Config cache is the usual suspect. Changing QUEUE_INSIGHTS_REDIS without php artisan config:clear (or re-caching in deploy) leaves workers on the old connection while the web process uses the new one — you get partial data and no error at all.
• Extension points are the config file, not code: the global connection, the chain_lineage override, and whatever retention/sampling keys the published config exposes. Prefer overriding there over swapping package internals.