README

Production-ready queue monitoring and metrics collection for Laravel applications.

Queue Metrics for Laravel provides deep observability into your Laravel queue system with minimal overhead. Track job execution, monitor worker performance, analyze trends, and export to Prometheus—all with zero configuration required.

Why Queue Metrics for Laravel?

🚀 Zero Configuration - Works out-of-the-box
⚡ Minimal Overhead - ~1-2ms per job
📊 Rich Insights - Duration, memory, CPU, throughput, trends
🎯 Production Ready - Battle-tested at scale
🔌 Extensible - Events for customization and reactive monitoring
📈 Prometheus Ready - Native metrics export
🏗️ DX First - Clean facade API and comprehensive docs

Quick Example

use Cbox\LaravelQueueMetrics\Facades\QueueMetrics;

// Get job performance metrics
$metrics = QueueMetrics::getJobMetrics(ProcessOrder::class);

echo "Processed: {$metrics->totalProcessed}\n";
echo "P95 Duration: {$metrics->duration->p95}ms\n";
echo "Failure Rate: {$metrics->failureRate}%\n";
echo "Health Score: {$metrics->health->score}/100\n";

// React to events
Event::listen(HealthScoreChanged::class, function ($event) {
    if ($event->toStatus === 'critical') {
        Slack::alert("Queue health critical!");
    }
});

Documentation

📚 Full Documentation →

🚀 Need Deep Insight and Replay Capability?

While this package provides a high-level overview of your queue's health and performance via aggregated metrics, Queue Monitor for Laravel allows you to dive into individual job executions.

We recommend installing it if you need:

🕵️‍♂️ Debugging: View exact arguments (payload) for failed jobs and read the full stack trace.
🔁 Job Replay: Restart failed jobs directly from the database with a single click or command.
👤 Customer Support: Look up jobs based on tags (e.g., find all jobs for a specific user).
📜 Audit Log: Complete history of every job execution, including which server/PID processed it.

The two packages are designed to work together: Metrics tells you that something is wrong, while Monitor tells you what is wrong and lets you fix it.

Getting Started

Installation - Get up and running
Quick Start - 5-minute walkthrough
Configuration - Customize behavior

Integration

Facade API - Developer interface
HTTP API - REST endpoints
Prometheus - Monitoring integration

Extensibility

Events - React to metrics changes
Architecture - How it works

Real-World Examples

Artisan Commands - CLI tools
Performance Tuning - Optimizing for scale

Installation

composer require cboxdk/laravel-queue-metrics

That's it! The package auto-registers and starts collecting metrics immediately.

For database storage, run migrations:

php artisan vendor:publish --tag="laravel-queue-metrics-migrations"
php artisan migrate

→ Full installation guide

Key Features

Job Metrics

Track execution time, memory usage, CPU time, throughput, and failure rates per job class with percentile statistics (P50, P95, P99).

Queue Health

Monitor queue depth, processing rates, failure rates, and health scores with automatic issue detection.

Worker Monitoring

Real-time worker status, resource consumption, efficiency metrics, and stale worker detection.

Trend Analysis

Historical analysis with linear regression, forecasting, and anomaly detection for proactive insights.

Baseline Comparison

Automatic baseline calculation to detect performance degradation and regressions.

Flexible Storage

Redis (fast, in-memory) or Database (persistent) backends with automatic TTL cleanup.

Prometheus Export

Native Prometheus metrics endpoint for Grafana dashboards and alerting.

RESTful API

Complete HTTP API for integration with custom dashboards and monitoring tools.

Events

Extensible architecture with events for reactive monitoring and notifications.

Requirements

PHP 8.3+
Laravel 11.0, 12.0, or 13.0+
Redis or Database for metrics storage

Note: Laravel 12.19+ is recommended for most accurate queue metrics (Laravel PR #56010). Earlier versions use driver-specific implementations.

Configuration

Storage Drivers

Redis (default, recommended)

Redis is the recommended driver for all workloads. It handles high-frequency metrics writes with minimal overhead.

QUEUE_METRICS_STORAGE=redis
QUEUE_METRICS_CONNECTION=default

Database

For applications without Redis infrastructure, a database driver is available. This stores metrics in 4 database tables using the same schema as your application database.

QUEUE_METRICS_STORAGE=database
QUEUE_METRICS_CONNECTION=mysql  # or your database connection

Run the migration to create the metrics tables:

php artisan vendor:publish --tag="laravel-queue-metrics-migrations"
php artisan migrate

Important: The database driver is designed for low-scale workloads (< 10 workers). At higher scale, metrics writes create contention on the same database your queue jobs use. Use Redis for production with moderate to high workloads.

Recommended setting for database driver: Set QUEUE_METRICS_MAX_SAMPLES=500 to keep table sizes manageable.

The database cleanup command runs automatically every minute when using the database driver, removing expired data and trimming sample tables.

API Authentication

// config/queue-metrics.php
'api' => [
    'enabled' => true,
    'middleware' => ['api', 'auth:sanctum'], // Secure the API
],

Scheduled Commands

The package automatically schedules necessary maintenance tasks. You can disable or configure this behavior in config/queue-metrics.php:

// config/queue-metrics.php
'scheduling' => [
    'enabled' => true,
    'tasks' => [
        'cleanup_stale_workers' => true,
        'calculate_baselines' => true,
        'calculate_queue_metrics' => true,
        'record_trends' => true,
    ],
],

If you prefer to manually schedule commands in your Console/Kernel.php (or routes/console.php), simply set 'enabled' => false.

→ Complete configuration reference

Usage Examples

Monitor Job Performance

$metrics = QueueMetrics::getJobMetrics(ProcessOrder::class);

if ($metrics->duration->p95 > 5000) {
    alert("ProcessOrder is slow: {$metrics->duration->p95}ms");
}

if ($metrics->failureRate > 5) {
    alert("ProcessOrder failing: {$metrics->failureRate}%");
}

Check Queue Health

$queue = QueueMetrics::getQueueMetrics('redis', 'default');

if ($queue->health->status === 'critical') {
    PagerDuty::alert("Queue critical: {$queue->health->score}/100");
}

if ($queue->depth->total > 10000) {
    Log::warning("Queue depth high: {$queue->depth->total}");
}

React to Events

Event::listen(WorkerEfficiencyChanged::class, function ($event) {
    if ($event->getScalingRecommendation() === 'scale_up') {
        AutoScaler::scaleUp($event->activeWorkers + 2);
    }
});

Multi-Tenancy Integration

use Cbox\LaravelQueueMetrics\Events\MetricsRecorded;

Event::listen(MetricsRecorded::class, function (MetricsRecorded $event) {
    // Log with tenant context
    Log::info('Job metrics recorded', [
        'tenant_id' => tenant('id'),
        'tenant_plan' => tenant('plan'),
        'job' => $event->metrics->jobClass,
        'duration' => $event->metrics->duration->avg,
    ]);
});

→ More examples

API Endpoints

# System overview
GET /queue-metrics/overview

# Job metrics
GET /queue-metrics/jobs/App\\Jobs\\ProcessOrder

# Queue health
GET /queue-metrics/queues/default?connection=redis

# Active workers
GET /queue-metrics/workers

# Prometheus export
GET /queue-metrics/prometheus

→ Complete API reference

Prometheus Integration

# prometheus.yml
scrape_configs:
  - job_name: 'laravel-queues'
    static_configs:
      - targets: ['your-app.test']
    metrics_path: '/queue-metrics/prometheus'
    scrape_interval: 30s

Query metrics:

# Queue depth
queue_depth{connection="redis",queue="default"}

# Job duration P95
job_duration_p95_ms{job_class="App\\Jobs\\ProcessOrder"}

# Failure rate
job_failure_rate > 5

→ Prometheus setup guide

Architecture

Queue Metrics for Laravel uses a clean, layered architecture:

Event Listeners → Capture Laravel queue events
Actions → Business logic for recording metrics
Repositories → Data access abstraction
Storage Drivers → Pluggable backends (Redis/Database)
Services → High-level business operations
DTOs → Type-safe, immutable data structures
Events → Reactive monitoring and notifications

→ Architecture deep dive

Performance

Per-job overhead: ~1-2ms (Redis), ~5-15ms (Database)
Memory overhead: ~5-10MB package classes, ~1-2KB per job record
Tested throughput: 10,000+ jobs/minute
Storage: Auto-cleanup via TTL (Redis) or manual cleanup (Database)

→ Performance tuning guide

Testing

composer test
composer analyse
composer format

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

📚 Read the full documentation →

cboxdk / laravel-queue-metrics

Maintainers

Package info

Fund package maintenance!

Statistics

Security