PHPackages                             cboxdk/laravel-queue-metrics - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. cboxdk/laravel-queue-metrics

ActiveLibrary[Logging & Monitoring](/categories/logging)

cboxdk/laravel-queue-metrics
============================

Production-ready Laravel queue monitoring with metrics, analytics, and insights

v2.0.0(3mo ago)3215[1 PRs](https://github.com/cboxdk/laravel-queue-metrics/pulls)2MITPHPPHP ^8.3|^8.4|^8.5CI passing

Since Jan 20Pushed 1mo agoCompare

[ Source](https://github.com/cboxdk/laravel-queue-metrics)[ Packagist](https://packagist.org/packages/cboxdk/laravel-queue-metrics)[ Docs](https://github.com/cboxdk/laravel-queue-metrics)[ GitHub Sponsors](https://github.com/cboxdk)[ RSS](/packages/cboxdk-laravel-queue-metrics/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (14)Versions (4)Used By (2)

Laravel Queue Metrics
=====================

[](#laravel-queue-metrics)

[![Latest Version on Packagist](https://camo.githubusercontent.com/a62572035b26c22b0a32c45863e9f1198267078f79ef7d36d00027673ac9d20a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63626f78646b2f6c61726176656c2d71756575652d6d6574726963732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cboxdk/laravel-queue-metrics)[![GitHub Tests Action Status](https://camo.githubusercontent.com/e3723de0138470bab8c844190b3c9a10d956eeed12c58c2faf3009ea0870a2ab/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f63626f78646b2f6c61726176656c2d71756575652d6d6574726963732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/cboxdk/laravel-queue-metrics/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/2fa5376458054ca6c227f9650125fa2c741e4019f4760fe8fe849670044207d5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f63626f78646b2f6c61726176656c2d71756575652d6d6574726963732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/cboxdk/laravel-queue-metrics/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/8779010d4aac3f07279cb6b3eb59028b22bade2b52ca597c454864089d1699a2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63626f78646b2f6c61726176656c2d71756575652d6d6574726963732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cboxdk/laravel-queue-metrics)

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

Laravel Queue Metrics 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 Laravel Queue Metrics?
--------------------------

[](#why-laravel-queue-metrics)

- 🚀 **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
-------------

[](#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
-------------

[](#documentation)

📚 **[Full Documentation →](docs/introduction.md)**

🚀 Need Deep Insight and Replay Capability?
------------------------------------------

[](#-need-deep-insight-and-replay-capability)

While this package provides a high-level overview of your queue's health and performance via aggregated metrics, **[Laravel Queue Monitor](https://github.com/cboxdk/laravel-queue-monitor)** 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

[](#getting-started)

- **[Installation](docs/installation.md)** - Get up and running
- **[Quick Start](docs/quickstart.md)** - 5-minute walkthrough
- **[Configuration](docs/configuration-reference.md)** - Customize behavior

### Integration

[](#integration)

- **[Facade API](docs/basic-usage/facade-api.md)** - Developer interface
- **[HTTP API](docs/basic-usage/api-endpoints.md)** - REST endpoints
- **[Prometheus](docs/advanced-usage/prometheus.md)** - Monitoring integration

### Extensibility

[](#extensibility)

- **[Events](docs/advanced-usage/events.md)** - React to metrics changes
- **[Architecture](docs/advanced-usage/architecture.md)** - How it works

### Real-World Examples

[](#real-world-examples)

- **[Artisan Commands](docs/basic-usage/artisan-commands.md)** - CLI tools
- **[Performance Tuning](docs/advanced-usage/performance.md)** - Optimizing for scale

Installation
------------

[](#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](docs/installation.md)**

Key Features
------------

[](#key-features)

### Job Metrics

[](#job-metrics)

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

### Queue Health

[](#queue-health)

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

### Worker Monitoring

[](#worker-monitoring)

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

### Trend Analysis

[](#trend-analysis)

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

### Baseline Comparison

[](#baseline-comparison)

Automatic baseline calculation to detect performance degradation and regressions.

### Flexible Storage

[](#flexible-storage)

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

### Prometheus Export

[](#prometheus-export)

Native Prometheus metrics endpoint for Grafana dashboards and alerting.

### RESTful API

[](#restful-api)

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

### Events

[](#events)

Extensible architecture with events for reactive monitoring and notifications.

Requirements
------------

[](#requirements)

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

**Note**: Laravel 12.19+ is recommended for most accurate queue metrics ([Laravel PR #56010](https://github.com/laravel/framework/pull/56010)). Earlier versions use driver-specific implementations.

Configuration
-------------

[](#configuration)

### Storage Backend

[](#storage-backend)

**Redis (Recommended for Production)**:

```
QUEUE_METRICS_STORAGE=redis
QUEUE_METRICS_CONNECTION=default
```

**Database (For Persistence)**:

```
QUEUE_METRICS_STORAGE=database
```

### API Authentication

[](#api-authentication)

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

### Scheduled Commands

[](#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](docs/configuration-reference.md)**

Usage Examples
--------------

[](#usage-examples)

### Monitor Job Performance

[](#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

[](#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

[](#react-to-events)

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

### Multi-Tenancy Integration

[](#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](docs/quickstart.md#real-world-examples)**

API Endpoints
-------------

[](#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](docs/basic-usage/api-endpoints.md)**

Prometheus Integration
----------------------

[](#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](docs/advanced-usage/prometheus.md)**

Architecture
------------

[](#architecture)

Laravel Queue Metrics 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](docs/advanced-usage/architecture.md)**

Performance
-----------

[](#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](docs/advanced-usage/performance.md)**

Testing
-------

[](#testing)

```
composer test
composer analyse
composer format
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Sylvester Damgaard](https://github.com/sylvesterdamgaard)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

---

**[📚 Read the full documentation →](docs/introduction.md)**

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance86

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

113d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b9761a79e61f2d5b9d650510dfb3555da18daf38f027aa84012c937e397e39a7?d=identicon)[cboxdk](/maintainers/cboxdk)

---

Top Contributors

[![sylvesterdamgaard](https://avatars.githubusercontent.com/u/2431914?v=4)](https://github.com/sylvesterdamgaard "sylvesterdamgaard (146 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

laravelmonitoringperformanceMetricsqueueanalyticscboxlaravel-queue-metrics

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/cboxdk-laravel-queue-metrics/health.svg)

```
[![Health](https://phpackages.com/badges/cboxdk-laravel-queue-metrics/health.svg)](https://phpackages.com/packages/cboxdk-laravel-queue-metrics)
```

###  Alternatives

[jackwh/laravel-new-relic

Monitor your Laravel application performance with New Relic

112827.2k](/packages/jackwh-laravel-new-relic)[muhammadsadeeq/laravel-activitylog-ui

A beautiful, modern UI for Spatie's Activity Log with advanced filtering, analytics, and real-time features.

17510.1k](/packages/muhammadsadeeq-laravel-activitylog-ui)[scoutapp/scout-apm-laravel

Scout Application Performance Monitoring Agent - https://scoutapm.com

23831.3k](/packages/scoutapp-scout-apm-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)