README

A powerful Laravel queue monitoring package with database driver support, advanced metrics, and operational controls.

Better than Horizon - Full database driver support, advanced controls, lightweight, and easy to install.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Usage
• API Documentation
• Comparison with Horizon
• Requirements
• Documentation
• Contributing
• License

Features

• 📊 Real-time Dashboard - Monitor queue jobs with live updates
• 🎛️ Operational Controls - Pause, resume, throttle, and retry queues
• 📈 Rich Metrics - Track job success rates, runtime, and failures
• 💾 Database Driver Support - Full support for database queue driver
• 🚀 Performance Optimized - Indexed queries and efficient data retention
• 🔒 Secure - Customizable middleware for dashboard protection

Installation

Quick Install

composer require willypelz/queue-monitor
php artisan queue-monitor:install

That's it! Visit http://your-app.test/queue-monitor to see your dashboard.

✅ Auto-Discovery: This package supports Laravel's auto-discovery feature. The service provider is automatically registered when you install the package.

🔒 HTTPS Ready: All external resources use HTTPS to prevent mixed-content blocking. Works seamlessly with secure applications.

Manual Installation

Install the package via Composer:

composer require willypelz/queue-monitor

Publish the configuration and migrations:

php artisan vendor:publish --provider="QueueMonitor\QueueMonitorServiceProvider"

Or publish individually:

# Publish config
php artisan vendor:publish --tag=queue-monitor-config

# Publish migrations
php artisan vendor:publish --tag=queue-monitor-migrations

# Publish views (optional, for customization)
php artisan vendor:publish --tag=queue-monitor-views

Run the migrations:

php artisan migrate

Configuration

The configuration file is published to config/queue-monitor.php:

return [
    // Dashboard route path
    'path' => 'queue-monitor',

    // Middleware for dashboard access
    'middleware' => ['web'],

    // Storage driver: 'database' or 'redis'
    'driver' => env('QUEUE_MONITOR_DRIVER', 'database'),

    // Redis configuration (when driver is 'redis')
    'redis' => [
        'connection' => env('QUEUE_MONITOR_REDIS_CONNECTION', 'default'),
    ],

    // Retention period in days
    'retention_days' => 14,

    // UI refresh interval
    'ui' => [
        'refresh_seconds' => 10,
    ],

    // Control settings
    'control' => [
        'pause_release_seconds' => 10,
        'throttle_default_rate_per_minute' => 60,
        'throttle_release_seconds' => 5,
    ],
];

Storage Drivers

Database Driver (Default)

QUEUE_MONITOR_DRIVER=database

• Persistent storage
• SQL queries supported
• Best for moderate volume

Redis Driver (High Performance)

QUEUE_MONITOR_DRIVER=redis
QUEUE_MONITOR_REDIS_CONNECTION=default

• 20x faster than database
• Perfect for high-volume queues
• Memory-based with TTL expiration
• See Redis Driver Guide for details

Securing the Dashboard

Add authentication middleware to protect the dashboard:

'middleware' => ['web', 'auth'],

Or create custom middleware for role-based access:

'middleware' => ['web', 'auth', 'can:view-queue-monitor'],

Usage

Accessing the Dashboard

Once installed, visit the dashboard at:

http://your-app.test/queue-monitor

Dashboard Features

• Stats Overview: View total, processed, failed, and processing jobs
• Average Runtime: Monitor job performance
• Recent Jobs: See the latest job executions
• Queue Controls: Pause, resume, throttle, or retry queues

Queue Controls

Pause Queue

Temporarily stop processing jobs on a specific queue:

# Via Dashboard UI or API
POST /queue-monitor/api/control/pause
{
    "connection": "database",
    "queue": "default"
}

Resume Queue

Resume a paused queue:

POST /queue-monitor/api/control/resume
{
    "connection": "database",
    "queue": "default"
}

Throttle Queue

Limit the number of jobs processed per minute:

POST /queue-monitor/api/control/throttle
{
    "connection": "database",
    "queue": "default",
    "rate": 60
}

Retry Failed Jobs

Retry all failed jobs on a queue:

POST /queue-monitor/api/control/retry
{
    "connection": "database",
    "queue": "default"
}

Programmatic Usage

You can also interact with the queue monitor programmatically:

use QueueMonitor\Services\QueueControlService;

$control = app(QueueControlService::class);

// Pause a queue
$control->pause('database', 'default');

// Resume a queue
$control->resume('database', 'default');

// Throttle a queue
$control->throttle('database', 'default', 30);

// Check if paused
$isPaused = $control->isPaused('database', 'default');

// Get throttle rate
$rate = $control->getThrottleRate('database', 'default');

Pruning Old Records

Keep your database clean by pruning old job records:

# Prune records older than 14 days (default)
php artisan queue-monitor:prune

# Prune records older than 7 days
php artisan queue-monitor:prune --days=7

Schedule automatic pruning in app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    $schedule->command('queue-monitor:prune')->daily();
}

Driver Comparison

Choose the right storage driver for your needs:

When to Use Redis

✅ Processing 1000+ jobs per minute ✅ Multiple servers sharing monitoring data ✅ Real-time dashboard updates required ✅ Want to reduce database load ✅ Already using Redis for cache/queues

When to Use Database

✅ Low to medium job volume ✅ Need permanent data storage ✅ SQL queries for reporting ✅ Single server deployment ✅ Compliance/audit requirements

To use database driver instead:

# .env
QUEUE_MONITOR_DRIVER=database

See Redis Driver Guide for detailed comparison and migration instructions.

API Endpoints

All API endpoints are prefixed with /queue-monitor/api:

Comparison with Horizon

Requirements

• PHP 8.1 or higher
• Laravel 10.x, 11.x, or 12.x
• Database (MySQL, PostgreSQL, SQLite, etc.) or Redis

Documentation

• Installation Guide - Detailed installation instructions
• Redis Driver Guide - NEW! High-performance Redis storage
• Queue Controls - Pause, resume, throttle, and retry
• API Documentation - RESTful API endpoints
• Middleware Setup - Job middleware configuration
• Security Considerations - HTTPS, mixed-content prevention, and access control
• API Endpoint Fix - Fix blocked:mixed-content for API calls
• Advanced Features - Performance optimization, alerting, and more

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Changelog

Please see CHANGELOG.md for recent changes.

Security

If you discover any security-related issues, please email willypelz@example.com instead of using the issue tracker.

Credits

• Author: Willy Pelz
• Inspired by: Laravel Horizon, romanzipp/laravel-queue-monitor
• Built with: Laravel, Vue.js 3, Tailwind CSS

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

License

This package is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community