ccarver/queue-watcher-laravel

Laravel integration for the queue-watcher Go package — emits job telemetry over stdout as newline-delimited JSON.

v2.0.0 2026-08-11 12:51 UTC

Requires

• php: ^8.1
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/mail: ^10.0|^11.0|^12.0
• illuminate/queue: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• ccarver

Published on Packagist.org on 2026-08-11 12:51 UTC

README

A Laravel package that integrates with the queue-watcher Go process. It hooks into Laravel's queue job lifecycle and emits newline-delimited JSON to stdout so queue-watcher can monitor jobs in real time. It also tracks sent emails to a database for inbox-style monitoring.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12

Installation

composer require ccarver/queue-watcher-laravel

Laravel's auto-discovery will register the service provider automatically. No manual registration is needed.

Features

• Queue telemetry — emits job lifecycle events (reserved, completed, failed) as NDJSON to stdout for the queue-watcher Go process.
• Mail tracking — captures every sent email and stores it in the database so a monitoring service can display a full inbox view.

Configuration

Publish the config file if you need to override defaults:

php artisan vendor:publish --tag=queue-watcher-config

This creates config/queue-watcher.php. Available env vars:

# Queue telemetry (stdout / Go watcher)
QUEUE_WATCHER_ENABLED=true

# Mail tracking (database)
QUEUE_WATCHER_MAIL_ENABLED=true
QUEUE_WATCHER_MAIL_PRUNE_DAYS=7

Queue telemetry

While php artisan queue:work is running, the package listens to Laravel's queue events and writes a JSON line to stdout for each job transition:

{"telemetry":true,"status":"reserved","job_id":"1","job_name":"App\\Jobs\\MyJob","error":null,"time":"2026-01-01T00:00:00+00:00"}
{"telemetry":true,"status":"completed","job_id":"1","job_name":"App\\Jobs\\MyJob","error":null,"time":"2026-01-01T00:00:01+00:00"}
{"telemetry":true,"status":"failed","job_id":"2","job_name":"App\\Jobs\\MyJob","error":"Timeout","time":"2026-01-01T00:00:05+00:00"}

The queue-watcher Go process reads these lines from the worker's stdout pipe. Telemetry is only active during php artisan queue:work and is a no-op in web requests.

Mail tracking

Every email sent through Laravel's mailer is saved to the queue_watcher_mail database table. This works in all contexts — web requests and queue workers alike.

Setup

Publish and run the migration:

php artisan vendor:publish --tag=queue-watcher-migrations
php artisan migrate

What is stored

Each record captures everything needed to render the email in an inbox view:

Column	Description
message_id	SMTP Message-ID header
subject	Email subject
sent_at	Date from the message (RFC 2822)
from	Sender(s) as [{address, name}]
reply_to	Reply-to address(es)
to	Primary recipient(s)
cc	CC recipient(s)
bcc	BCC recipient(s)
body_html	HTML body
body_text	Plain-text body
created_at	When the record was inserted

Pruning old records

Stored emails are automatically pruned using Laravel's built-in model pruning. Records older than prune_after_days (default: 7) are deleted when you run:

php artisan model:prune

Schedule this in your application's routes/console.php (Laravel 11+) or App\Console\Kernel:

Schedule::command('model:prune')->daily();

Set QUEUE_WATCHER_MAIL_PRUNE_DAYS=0 to disable pruning (records kept indefinitely).

Querying stored mail

Records are accessible via the WatchedMail Eloquent model:

use Ccarver\QueueWatcher\Models\WatchedMail;

// All sent mail, newest first
WatchedMail::latest()->get();

// Mail sent to a specific address
WatchedMail::where('to', 'like', '[e-mail]%')->get();

Upgrading

v1.0.0 → v2.0.0

Version 2.0 adds mail tracking. No breaking changes to existing queue telemetry behaviour.

New dependency

illuminate/mail and illuminate/database are now required. These are included in a standard Laravel installation, so no extra steps are needed for most projects.

Run the new migration

php artisan vendor:publish --tag=queue-watcher-migrations
php artisan migrate

This creates the queue_watcher_mail table. Existing tables are untouched.

Publish the updated config (optional)

If you previously published config/queue-watcher.php, re-publish or manually add the new mail block:

'mail' => [
    'enabled'          => env('QUEUE_WATCHER_MAIL_ENABLED', true),
    'prune_after_days' => env('QUEUE_WATCHER_MAIL_PRUNE_DAYS', 7),
],

Schedule pruning (optional)

Add model:prune to your scheduler if you want old mail records cleaned up automatically — see Pruning old records.

License

MIT