README

A Laravel package to monitor queue failures and send notifications based on thresholds and time windows.

Features

Digest Mode (Time-Bucket): Instead of immediate alerts, it collects all failures within a time window and sends a summary report.
Threshold Monitoring: Alert only when X jobs fail within Y minutes.
Queue Filtering: Precisely control which queues to monitor (supports wildcards and exclusions).
Aggregation Strategies:
- all: Count all failures.
- unique_jobs: Count failures per job class.
- unique_exceptions: Count failures per exception type.
Cooldown: Prevent notification spam with a configurable cooldown period after a report is sent.
Multi-channel Notifications: Support for Mail, Slack, and any other Laravel notification channel.

Installation

composer require kreatif/laravel-queue-watchdog

Note: If you plan to use the Slack notification channel, you must also install the official Laravel Slack notification package:

composer require laravel/slack-notification-channel

Configuration

Publish the config file:

php artisan vendor:publish --tag="laravel-queue-watchdog-config"

php artisan vendor:publish --tag="queue-watchdog-config"

The configuration allows you to define thresholds, aggregation strategies, and notification channels.

How it works: Digest Mode

The watchdog uses a Time-Bucket model to ensure no failure information is lost:

The first failure on a monitored queue starts a "Collection Window" (defined by window_minutes).
All subsequent failures during this window are collected in a cache-based bucket.
At the end of the window, an analysis job runs.
If the total count of failures is >= failure_limit, a summary notification is sent via your configured channels.
A cooldown_minutes period then starts, during which no new collection windows will begin.

Configuration Tips:

Real-time Alerts: Set window_minutes to 0 or false and failure_limit to 1 to receive a notification immediately for every failure.
Strict Digest: Set window_minutes to 10 and failure_limit to 1 to get a summary of all failures every 10 minutes.
Threshold Digest: Set window_minutes to 5 and failure_limit to 10 to only be notified if at least 10 jobs fail within a 5-minute burst.

Queue Filtering

You can precisely control which queues are monitored using the queues array in the config file. It supports wildcards and exclusions:

*: Monitor all queues.
default: Monitor only the "default" queue.
!ignored: Exclude the "ignored" queue.
sync*: Monitor any queue starting with "sync" (e.g., sync-users, sync-orders).

Example:

'queues' => ['*', '!update', 'report', 'sync*'],

Usage

The package automatically listens for the Illuminate\Queue\Events\JobFailed event and tracks failures in your cache. No additional setup is required beyond configuration.

Stale Queues (worker not running)

When a worker dies (e.g. the database was unreachable for a few minutes and Supervisor gave up restarting it), no job fails – jobs just pile up and nobody notices. The package therefore also schedules queue-watchdog:check-stale every five minutes:

A queue counts as stale when its oldest waiting job (not reserved, already due) has been waiting longer than stale_jobs.max_wait_minutes (default 15, env QUEUE_WATCHDOG_STALE_MINUTES). Delayed jobs and retries with backoff only count once they are due.
The alert goes out synchronously through the configured notification channels – it does not depend on the queue it reports on.
While the queues stay stuck it reports again every repeat_minutes (default 60), immediately when another queue gets stuck, and once more when everything moves again.
Only in the production environment by default (stale_jobs.environments; an empty list means everywhere), so local machines without a worker stay quiet.
With the database driver every queue in the jobs table is checked; with other drivers the connection's default queue, or list them in stale_jobs.queues. The queues filter ('!name') applies as well.

Requirements: the Laravel scheduler must run (schedule:run via cron). Projects that published the config before this version get the stale_jobs defaults automatically; publish again only to change them. Disable with QUEUE_WATCHDOG_STALE_ENABLED=false. Apps that report failed jobs themselves can turn off only the failed-job alerts with QUEUE_WATCHDOG_FAILED_JOBS_ENABLED=false; the stale check keeps running.

php artisan queue-watchdog:check-stale   # run the check by hand

License

The MIT License (MIT). Please see License File for more information.

kreatif / laravel-queue-watchdog

Package info

Security

Statistics