Installation

Get Queue Metrics for Laravel up and running in your application.

Requirements

• PHP: 8.3 or higher
• Laravel: 11.0, 12.0, or 13.0+
• Storage: Redis (recommended) or Database
• Optional: cboxdk/system-metrics for server monitoring

Laravel Version Notes

Laravel 12.19+ is recommended for most accurate queue metrics. This version includes native methods for separate pending, delayed, and reserved queue sizes (Laravel PR #56010).

Earlier versions use driver-specific implementations with reflection but work perfectly fine for most use cases.

Installation Steps

1. Install via Composer

composer require cboxdk/laravel-queue-metrics

The package will auto-register its service provider.

2. Choose Storage Backend

Option A: Redis (Recommended)

Redis is the recommended storage backend for production use:

Pros:

• Fast, in-memory performance (~1-2ms per operation)
• Automatic TTL cleanup
• Low latency for real-time metrics
• Handles high throughput (10,000+ jobs/minute)

Cons:

• Not persistent (data lost on Redis restart)
• Requires Redis server

Setup:

Ensure your .env has Redis configured:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

No migrations needed! Metrics are stored in Redis automatically.

Option B: Database

Use database storage for long-term persistence:

Pros:

• Persistent storage
• Queryable with SQL
• No additional infrastructure

Cons:

• Slower than Redis (~10-20ms per operation)
• Requires manual cleanup of old data
• Not ideal for very high throughput

Setup:

Publish and run migrations:

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

Configure in .env:

QUEUE_METRICS_STORAGE=database

3. Publish Configuration (Optional)

Publish the configuration file to customize behavior:

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

This creates config/queue-metrics.php where you can customize:

• Storage driver and TTLs
• API endpoints and middleware
• Performance settings
• Worker heartbeat intervals

See Configuration Reference for all options.

Verification

Test the Installation

1. Dispatch a Test Job

php artisan tinker

dispatch(new \App\Jobs\TestJob());

2. Check Metrics via API

curl http://your-app.test/queue-metrics/overview

You should see JSON with queue statistics.

3. Verify Metrics Storage

For Redis:

redis-cli
> KEYS queue_metrics:*

For Database:

php artisan tinker

DB::table('queue_job_metrics')->count();

Start Queue Worker

Ensure you have a queue worker running:

php artisan queue:work redis --queue=default

Or with Horizon:

php artisan horizon

Post-Installation Setup

1. Configure Scheduled Commands (Optional)

The package automatically schedules necessary maintenance tasks (like calculating baselines and recording trends) if scheduling.enabled is set to true in the config (default).

If you prefer to define schedules manually (e.g., to change frequencies), disable automatic scheduling in config/queue-metrics.php:

'scheduling' => [
    'enabled' => false,
],

Then add the commands to your routes/console.php (Laravel 11+) or app/Console/Kernel.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('queue-metrics:trends:record')->everyFiveMinutes();
Schedule::command('queue-metrics:workers:detect-stale')->everyMinute();
Schedule::command('queue-metrics:baseline:calculate')->daily();

// Only needed for database storage
Schedule::command('queue-metrics:cleanup --days=7')
    ->dailyAt('02:00')
    ->when(fn() => config('queue-metrics.storage.driver') === 'database');

2. Configure API Middleware (Recommended)

By default, the API is protected by a Gate that only allows access in the local environment. To allow access in production, you must define the authorization logic in your AppServiceProvider or AuthServiceProvider:

use Cbox\LaravelQueueMetrics\LaravelQueueMetrics;

public function boot(): void
{
    LaravelQueueMetrics::auth(function ($request) {
        return app()->environment('local') ||
               in_array($request->user()?->email, ['admin@example.com']);
    });
}

For more advanced configuration, see Security.

3. Register Event Listeners (Optional)

To react to metrics events, register listeners in EventServiceProvider:

use Cbox\LaravelQueueMetrics\Events\{
    MetricsRecorded,
    WorkerEfficiencyChanged,
    HealthScoreChanged,
    BaselineRecalculated,
    QueueDepthThresholdExceeded,
};

protected $listen = [
    MetricsRecorded::class => [
        SendMetricsToDatadog::class,
    ],

    WorkerEfficiencyChanged::class => [
        TriggerAutoScaling::class,
    ],

    HealthScoreChanged::class => [
        SendHealthAlert::class,
    ],
];

See Events for detailed usage.

4. Register Hooks (Optional)

For data enrichment, register hooks in AppServiceProvider:

use Cbox\LaravelQueueMetrics\Facades\QueueMetrics;

public function boot(): void
{
    QueueMetrics::hook('before_record', function (array $data) {
        // Add custom metadata
        $data['environment'] = app()->environment();
        $data['tenant_id'] = tenant('id');

        return $data;
    });
}

See Hooks documentation for detailed usage.

Common Issues

Issue: No Metrics Appearing

Symptoms: API returns empty data, no metrics in storage

Solutions:

1. Verify queue worker is running:

   php artisan queue:work
   

2. Check if jobs are actually processing:

   php artisan queue:work --once
   

3. Verify package is enabled:

   php artisan tinker
   

   config('queue-metrics.enabled'); // Should be true
   

4. Check event listeners are registered:

   php artisan event:list | grep Queue
   

Issue: High Memory Usage

Symptoms: Redis or database growing too large

Solutions:

1. Reduce TTL values in config/queue-metrics.php:

   'ttl' => [
       'raw' => 1800,        // 30 minutes instead of 1 hour
       'aggregated' => 86400, // 1 day instead of 7 days
   ],
   

2. For database storage, run cleanup:

   php artisan queue-metrics:cleanup --days=3
   

3. Reduce sample sizes:

   'performance' => [
       'percentile_samples' => 500,  // Reduce from 1000
       'baseline_samples' => 50,     // Reduce from 100
   ],
   

Issue: API Returns 404

Symptoms: /queue-metrics/* endpoints not found

Solutions:

1. Clear route cache:

   php artisan route:clear
   

2. Verify API is enabled:

   config('queue-metrics.api.enabled'); // Should be true
   

3. Check route registration:

   php artisan route:list | grep queue-metrics
   

Issue: Slow Performance

Symptoms: Job processing slowed after installing package

Solutions:

1. Use Redis storage instead of database

2. Increase batch sizes in config:

   'performance' => [
       'batch_size' => 200, // Increase from 100
   ],
   

3. Disable metrics temporarily:

   QUEUE_METRICS_ENABLED=false
   

4. Use queued event listeners for integrations

Upgrading

From Pre-1.0 Versions

If upgrading from a pre-1.0 version:

1. Clear old config:

   rm config/queue-metrics.php
   

2. Republish config:

   php artisan vendor:publish --tag="laravel-queue-metrics-config" --force
   

3. Run new migrations:

   php artisan migrate
   

4. Update event listener namespaces if you registered any

Composer Update

Regular updates:

composer update cboxdk/laravel-queue-metrics

Always check CHANGELOG.md for breaking changes.

Uninstallation

To remove the package:

1. Remove Package

composer remove cboxdk/laravel-queue-metrics

2. Clean Up Data

For Redis:

redis-cli
> KEYS queue_metrics:*
> DEL queue_metrics:* # Be careful!

For Database:

php artisan migrate:rollback --path=database/migrations/*_create_queue_metrics_tables.php

3. Remove Config

rm config/queue-metrics.php

4. Clear Cache

php artisan config:clear
php artisan route:clear

Next Steps

• Quick Start Guide - Start using the package
• Configuration Reference - Customize behavior
• Facade API - Learn the developer interface
• Events - React to metrics events