Queue Monitoring

LaraBug automatically tracks your Laravel queue jobs, providing real-time visibility into job execution, failures, and performance metrics. Monitor what's running, what failed, and why—all from your LaraBug dashboard.

Overview

Queue monitoring helps you:

• Track job lifecycle - See when jobs are dispatched, start processing, complete, or fail
• Identify failures quickly - Get instant notifications when jobs fail with full exception details
• Monitor performance - View execution time, memory usage, and attempt counts
• Debug stuck jobs - Identify jobs that are taking too long or getting stuck
• Analyze trends - Visualize queue metrics with charts and analytics

Automatic Setup

Queue monitoring is enabled by default when you install LaraBug v3.5.0 or higher. No additional configuration is required—LaraBug automatically tracks all queue jobs across all queues.

composer require larabug/larabug:^3.5

That's it! Jobs will start appearing in your dashboard immediately.

How It Works

LaraBug listens to Laravel's queue events and automatically captures:

• Job dispatch - When a job is added to the queue
• Job processing - When a worker starts processing a job
• Job completion - When a job finishes successfully
• Job failure - When a job throws an exception

Dynamic Batching (v3.5.1+)

LaraBug uses intelligent load-based batching to minimize API overhead:

• Low traffic (< 10 jobs/min): Events sent immediately, zero delay
• High traffic (> 10 jobs/min): Automatic batching activates, reducing API calls by 50-100x
• Adaptive: Smoothly transitions between modes based on your workload

This ensures minimal performance impact while maintaining real-time visibility.

Configuration

While queue monitoring works out of the box, you can customize behavior in config/larabug.php:

Basic Configuration

'jobs' => [
    // Enable or disable queue job tracking
    'track_jobs' => env('LB_TRACK_JOBS', true),
    
    // Track job lifecycle events
    'track_processing' => env('LB_TRACK_PROCESSING', false),
    'track_completed' => env('LB_TRACK_COMPLETED', true),
    'track_failed' => env('LB_TRACK_FAILED', true),
],

Dynamic Batching Configuration (v3.6.0+)

'jobs' => [
    // Jobs per minute threshold to enable batching
    'auto_batch_threshold' => env('LB_AUTO_BATCH_THRESHOLD', 10),
    
    // Jobs per minute threshold to disable batching
    'auto_batch_disable_threshold' => env('LB_AUTO_BATCH_DISABLE', 5),
    
    // Minutes to wait before disabling batching after rate drops
    'auto_batch_cooldown' => env('LB_AUTO_BATCH_COOLDOWN', 5),
    
    // Events per batch when batching is active
    'batch_size' => env('LB_BATCH_SIZE', 50),
    
    // Auto-flush interval in seconds
    'flush_interval' => env('LB_FLUSH_INTERVAL', 30),
    
    // Maximum retry attempts for failed API calls
    'max_retries' => env('LB_MAX_RETRIES', 3),
],

Filtering Options

Track specific queues only:

'jobs' => [
    'only_queues' => ['high-priority', 'emails'],
],

Or via environment variable:

LB_ONLY_QUEUES=high-priority,emails

Ignore specific queues:

'jobs' => [
    'ignore_queues' => ['low-priority', 'notifications'],
],

Or via environment variable:

LB_IGNORE_QUEUES=low-priority,notifications

Ignore specific job classes:

'jobs' => [
    'ignore_jobs' => [
        \App\Jobs\UnimportantJob::class,
        \App\Jobs\NoiseGeneratingJob::class,
    ],
],

Sampling for High-Volume Queues

For applications processing thousands of jobs, you may want to sample successful completions while tracking all failures:

'jobs' => [
    'track_completed' => true,
    'track_failed' => true,
    'sample_rate' => 0.1, // Track 10% of successful completions
],

Sampling rates:

• 1.0 - Track 100% of successful jobs (default)
• 0.5 - Track 50% of successful jobs
• 0.1 - Track 10% of successful jobs
• 0.0 - Don't track successful jobs

Note: Failures are always tracked at 100% regardless of sample rate.

Environment Variables

Add these to your .env file for easy configuration:

# Enable/disable tracking
LB_TRACK_JOBS=true

# Lifecycle events
LB_TRACK_PROCESSING=false
LB_TRACK_COMPLETED=true
LB_TRACK_FAILED=true

# Dynamic batching thresholds
LB_AUTO_BATCH_THRESHOLD=10
LB_AUTO_BATCH_DISABLE=5
LB_AUTO_BATCH_COOLDOWN=5

# Batching behavior
LB_BATCH_SIZE=50
LB_FLUSH_INTERVAL=30
LB_MAX_RETRIES=3

# Sampling
LB_SAMPLE_RATE=1.0

# Queue filters
LB_ONLY_QUEUES=
LB_IGNORE_QUEUES=

# Payload limits
LB_JOBS_MAX_PAYLOAD_SIZE=10000

# Debug options
LB_REPORT_SDK_ERRORS=false
LB_REPORT_BUFFER_ERRORS=false

Configuration Examples

Default (Recommended)

Works perfectly for most applications with zero configuration:

'jobs' => [
    'track_jobs' => true,
    'track_processing' => false,
    'track_completed' => true,
    'track_failed' => true,
    'sample_rate' => 1.0,
],

High-Volume Applications

For apps processing 1000+ jobs per hour:

'jobs' => [
    'track_jobs' => true,
    'track_processing' => false,
    'track_completed' => true,
    'track_failed' => true,
    'sample_rate' => 0.1, // 10% of successful jobs
    'batch_size' => 100,  // Larger batches
],

Errors Only

Only track failures, ignore successful completions:

'jobs' => [
    'track_jobs' => true,
    'track_processing' => false,
    'track_completed' => false,
    'track_failed' => true,
],

Debugging Stuck Jobs

Enable processing events to debug jobs that start but never complete:

'jobs' => [
    'track_jobs' => true,
    'track_processing' => true, // Track when jobs start
    'track_completed' => true,
    'track_failed' => true,
],

Note: This doubles the number of events tracked.

Dashboard Features

Your LaraBug dashboard provides comprehensive queue monitoring:

Job Overview

• Real-time status - See jobs as they're processed
• Status counts - Completed, failed, and processing jobs
• Queue breakdown - Metrics per queue

Job Details

Each tracked job shows:

• Job class name - The fully qualified class name
• Queue name - Which queue processed the job
• Status - Pending, processing, completed, or failed
• Duration - Execution time in milliseconds
• Memory usage - Memory consumed during execution
• Attempts - Number of retry attempts
• Timestamps - When dispatched, started, and completed
• Payload - Serialized job data (truncated if too large)

Failure Details

For failed jobs, you also get:

• Exception class - Type of exception thrown
• Error message - Exception message
• Stack trace - Full stack trace with file/line numbers
• Code context - Lines of code around the error
• Server context - Environment variables and headers

Performance Analytics

• Execution time charts - Visualize job duration trends
• Success/failure rates - Track reliability over time
• Queue performance - Compare different queues
• Peak times - Identify when queues are busiest

Testing Queue Monitoring

To verify queue monitoring is working, dispatch a test job:

use Illuminate\Support\Facades\Queue;

// Dispatch a successful job
Queue::push(function () {
    logger('Test job executed successfully');
});

// Dispatch a failing job
Queue::push(function () {
    throw new \Exception('Test queue failure');
});

Or create a test job class:

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;

class TestJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle(): void
    {
        // Simulate work
        sleep(2);
        
        // Throw exception to test failure tracking
        if (rand(1, 3) === 1) {
            throw new \Exception('Random test failure');
        }
        
        logger('Test job completed');
    }
}

Dispatch it:

use App\Jobs\TestJob;

TestJob::dispatch();

Process the queue:

php artisan queue:work

Check your LaraBug dashboard to see the tracked jobs.

Performance Impact

Queue monitoring is designed to have minimal performance impact on your application.

Overhead

• Low traffic: < 1ms per job (immediate API calls)
• High traffic: < 0.1ms per job (batched)
• Memory: ~240 bytes per job in last 60 seconds

Batching Benefits

When processing 1000 jobs:

• Without batching: 1000+ API calls
• With batching: ~20 API calls (50x reduction)
• Network impact: 98% reduction in requests

Best Practices

1. Use default settings - Dynamic batching optimizes automatically
2. Enable sampling - For high-volume queues (1000+ jobs/hour)
3. Disable processing events - Unless debugging stuck jobs
4. Filter noisy queues - Ignore low-priority or high-volume queues

Troubleshooting

Jobs Not Appearing

1. Check configuration - Ensure track_jobs is true
2. Verify API keys - Check LB_KEY and LB_PROJECT_KEY are set
3. Check queue filters - Ensure queue isn't in ignore_queues
4. Process the queue - Jobs only appear after being processed by a worker
5. Check environment - Verify your environment is in the environments config

High API Usage

If you're seeing excessive API calls:

1. Upgrade to v3.6.0+ - Dynamic batching reduces calls by 50-100x
2. Disable processing events - Set track_processing to false
3. Enable sampling - Set sample_rate to 0.1 for high-volume queues
4. Increase batch size - Set batch_size to 100 or higher

Missing Failure Details

If failed jobs show incomplete information:

1. Check payload size - Increase max_payload_size if needed
2. Review blacklist - Ensure important data isn't filtered
3. Update package - Ensure you're on the latest version

Advanced Usage

Manual Flushing

For long-running queue workers or custom queue implementations:

use LaraBug\LaraBug;

// Get the queue monitor instance
$monitor = app(\LaraBug\Queue\JobMonitor::class);

// Manually flush buffered events
$monitor->flush();

This is useful when:

• Running long-lived queue workers
• Processing jobs in custom queue implementations
• Ensuring events are sent before script termination

Custom Context

Add custom data to job events using job properties:

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

class ProcessOrder implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public int $orderId,
        public string $customerEmail,
    ) {}

    public function handle(): void
    {
        // Job logic
    }
}

The $orderId and $customerEmail properties will be included in the tracked payload.

Migration from v3.5.0

If you're upgrading from v3.5.0 to v3.6.0:

composer update larabug/larabug
php artisan config:clear

No configuration changes required—dynamic batching is enabled by default and fully backward compatible!

Version Compatibility

• v3.6.0+ - Dynamic load-based batching
• v3.5.0 - Queue monitoring with basic batching
• < v3.5.0 - No queue monitoring support

Need Help?

• Check the GitHub repository for updates
• Report issues on GitHub Issues
• Contact support through your dashboard
• Check Service Status for API availability