cboxdk/laravel-queue-monitor

This is my package laravel-queue-monitor

v1.0.0.beta.1 2026-01-20 15:45 UTC

Requires

• php: ^8.3 || ^8.4 || ^8.5
• cboxdk/laravel-queue-metrics: ^2.0
• illuminate/contracts: ^11.0||^12.0
• nunomaduro/termwind: ^2.3
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Sylvester Damgaard

• laravel
• cbox
• laravel-queue-monitor

README

Production-ready Laravel queue monitoring with individual job tracking, payload storage, and comprehensive analytics.

Track every queue job with detailed metrics, replay failed jobs from stored payloads, and gain deep insights into your queue performance. Built on top of laravel-queue-metrics for enhanced resource tracking.

Features

• ✅ Individual Job Tracking - Monitor every job from queue to completion
• ✅ Full Payload Storage - Store complete job payloads for replay capability
• ✅ Worker & Server Identification - Track which server/worker processed each job
• ✅ Horizon Support - Automatic detection of Horizon vs queue:work
• ✅ Job Replay - Re-dispatch failed jobs from stored payloads
• ✅ Resource Metrics - CPU, memory, file descriptor tracking via queue-metrics integration
• ✅ Retry Chain Tracking - Complete visibility into job retry attempts
• ✅ Comprehensive Analytics - Per-queue, per-server, per-job-class statistics
• ✅ REST API - Full-featured API for dashboard integration
• ✅ Tag Analytics - Track and analyze jobs by custom tags
• ✅ Artisan Commands - CLI tools for monitoring and maintenance
• ✅ PHPStan Level 9 - Maximum static analysis compliance
• ✅ Pest 4 Ready - Modern testing framework support

Requirements

• PHP 8.3+
• Laravel 10+
• cboxdk/laravel-queue-metrics ^1.0 (hard dependency)

Installation

Install via Composer:

composer require cboxdk/laravel-queue-monitor

Publish configuration and run migrations:

php artisan vendor:publish --tag="queue-monitor-config"
php artisan migrate

Dashboard Customization

To customize the UI (Web or Terminal), publish the views:

php artisan vendor:publish --tag="queue-monitor-views"

This will create resources/views/vendor/queue-monitor/, where you can modify:

• web/dashboard.blade.php - The Web Dashboard
• tui/dashboard.blade.php - The Terminal Dashboard

That's it! The package automatically starts monitoring all queue jobs.

Quick Start

Facade Usage

use Cbox\LaravelQueueMonitor\Facades\LaravelQueueMonitor as QueueMonitor;

// Get job details
$job = QueueMonitor::getJob($uuid);

// Replay a failed job
$replayData = QueueMonitor::replay($uuid);

// Get statistics
$stats = QueueMonitor::statistics();
echo "Success Rate: {$stats['success_rate']}%";

// Query jobs with filters
$filters = new JobFilterData(
    statuses: [JobStatus::FAILED],
    queuedAfter: Carbon::now()->subHours(24)
);
$failedJobs = QueueMonitor::getJobs($filters);

Artisan Commands

# Show statistics
php artisan queue-monitor:stats

# Replay a job
php artisan queue-monitor:replay {uuid}

# Prune old jobs
php artisan queue-monitor:prune --days=30 --statuses=completed

REST API

# List jobs
GET /api/queue-monitor/jobs?statuses[]=failed&limit=50

# Get job details
GET /api/queue-monitor/jobs/{uuid}

# Replay job
POST /api/queue-monitor/jobs/{uuid}/replay

# Get statistics
GET /api/queue-monitor/statistics

# Queue health
GET /api/queue-monitor/statistics/queue-health

Architecture

Action Pattern

All business logic is encapsulated in single-responsibility Action classes:

RecordJobQueuedAction
RecordJobStartedAction
RecordJobCompletedAction
RecordJobFailedAction
ReplayJobAction
CalculateJobStatisticsAction

DTO Pattern

All data transfer uses strictly-typed DTOs:

JobMonitorData
WorkerContextData
ExceptionData
JobFilterData
JobReplayData

Repository Pattern

Data access through contracts with Eloquent implementations:

JobMonitorRepositoryContract
TagRepositoryContract
StatisticsRepositoryContract

Event-Driven

Integrates seamlessly with Laravel Queue events and queue-metrics events.

Configuration

Key configuration options in config/queue-monitor.php:

return [
    // Enable/disable monitoring
    'enabled' => env('QUEUE_MONITOR_ENABLED', true),

    // Payload storage for replay
    'storage' => [
        'store_payload' => env('QUEUE_MONITOR_STORE_PAYLOAD', true),
        'payload_max_size' => 65535,
    ],

    // Data retention
    'retention' => [
        'days' => 30,
        'prune_statuses' => ['completed'],
    ],

    // REST API (see Security section for authentication)
    'api' => [
        'enabled' => env('QUEUE_MONITOR_API_ENABLED', true),
        'prefix' => 'api/queue-monitor',
        'middleware' => ['api', 'auth:sanctum'], // Add authentication!
    ],

    // Worker detection
    'worker_detection' => [
        'server_name_callable' => null,
        'horizon_detection' => true,
    ],
];

Security

API Authentication

The REST API exposes sensitive queue data including job payloads and exception traces. You should always add authentication middleware in production.

Recommended Setup (Laravel Sanctum)

// config/queue-monitor.php
'api' => [
    'enabled' => env('QUEUE_MONITOR_API_ENABLED', true),
    'prefix' => 'api/queue-monitor',
    'middleware' => ['api', 'auth:sanctum'],
],

Alternative Authentication Methods

// Using Laravel's built-in auth
'middleware' => ['api', 'auth'],

// Using custom middleware
'middleware' => ['api', 'auth.admin'],

// Using abilities/permissions
'middleware' => ['api', 'auth:sanctum', 'ability:queue-monitor'],

IP Whitelisting (Additional Layer)

For maximum security, combine authentication with IP restrictions:

// app/Http/Middleware/QueueMonitorAccess.php
class QueueMonitorAccess
{
    public function handle($request, Closure $next)
    {
        $allowedIps = ['10.0.0.0/8', '192.168.0.0/16'];

        if (!$this->ipIsAllowed($request->ip(), $allowedIps)) {
            abort(403);
        }

        return $next($request);
    }
}

Payload Storage

Job payloads may contain sensitive data. Consider:

1. Disable payload storage if replay isn't needed:

   'storage' => ['store_payload' => false],

2. Use a separate database for monitoring data:

   'database' => ['connection' => 'queue_monitor'],

3. Implement data retention policies to limit exposure:

   'retention' => ['days' => 7],

Environment-Based Configuration

Disable the API in production if only using the facade/commands:

QUEUE_MONITOR_API_ENABLED=false

Documentation

• Installation Guide
• Configuration
• API Reference
• Facade Usage
• Job Replay

Security & Redaction

Payload Redaction

To protect sensitive data, the API automatically masks keys defined in the api.sensitive_keys config option (e.g. password, token).

// config/queue-monitor.php
'sensitive_keys' => ['password', 'secret', 'key'],

Note: The database stores the raw payload to ensure job replay functionality works correctly. Only the API response is redacted.

API Authentication

The REST API exposes sensitive queue data including job payloads and exception traces. You should always add authentication middleware in production.

This package is built on top of laravel-queue-metrics and automatically:

• Captures CPU time, memory usage, and file descriptors
• Subscribes to MetricsRecorded events
• Enriches job records with performance metrics
• Leverages Horizon detection utilities

Testing

composer test
composer analyse  # PHPStan Level 9
composer format   # Laravel Pint

Credits

• Sylvester Damgaard
• Built with laravel-package-tools

License

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