Laravel Queue Performance Tuning – Throughput, Retry Math & Worker Optimization

// config/queue.php – production Redis tuning
'redis' => [
    'driver'      => 'redis',
    'connection'  => 'queue',       // separate Redis connection for queues
    'queue'       => env('REDIS_QUEUE', 'default'),
    'retry_after' => 90,            // seconds before a reserved job is re-attempted
    'block_for'   => 5,             // seconds to block on BLPOP before re-checking
    'after_commit' => true,         // only dispatch after DB transaction commits
],

// config/database.php – dedicated queue Redis connection
'connections' => [
    'queue' => [
        'url'      => env('REDIS_URL'),
        'host'     => env('REDIS_HOST', '127.0.0.1'),
        'password' => env('REDIS_PASSWORD'),
        'port'     => env('REDIS_PORT', '6379'),
        'database' => 1,            // use DB 1, not DB 0 (separate keyspace)
        'options'  => [
            'parameters' => [
                'tcp_keepalive' => 60,
            ],
        ],
    ],
],

// App\Jobs\CallExternalApiJob.php
class CallExternalApiJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 6;
    public int $maxExceptions = 3; // stop after 3 different exception types

    /**
     * Exponential backoff with full jitter.
     * Attempt 1: 0–10s, Attempt 2: 0–20s, Attempt 3: 0–40s...
     * Cap at 10 minutes (600s) to prevent multi-hour delays.
     */
    public function backoff(): array
    {
        return $this->exponentialJitterBackoff(attempts: 6, base: 10, cap: 600);
    }

    private function exponentialJitterBackoff(int $attempts, int $base, int $cap): array
    {
        $delays = [];
        for ($i = 1; $i <= $attempts; $i++) {
            $ceiling = min($cap, $base * (2 ** $i));
            $delays[] = random_int(0, $ceiling);
        }
        return $delays;
    }

    public function handle(ExternalApiClient $client): void
    {
        $response = $client->post('/endpoint', $this->payload);

        // Treat 429 (rate limit) differently — respect the Retry-After header
        if ($response->status() === 429) {
            $retryAfter = (int) $response->header('Retry-After', 60);
            $this->release($retryAfter); // manually release with specific delay
            return;
        }

        if ($response->failed()) {
            throw new \RuntimeException("API call failed: {$response->status()}");
        }
    }
}

// Comparing backoff strategies for 100 simultaneous failures
// After attempt 3:

// Constant (30s): all 100 retry at exactly T+30 → spike
// Exponential (2^n * 10): all 100 retry at T+80 → spike, but larger window
// Exponential + full jitter: 100 jobs spread across [0, 80s] uniformly → no spike

// With jitter, the expected wait equals half the exponential ceiling:
// E[retry_after] = ceiling / 2 = 80 / 2 = 40s average wait
// vs deterministic 80s → jitter also reduces average wait time

// config/database.php – production connection settings for workers
'mysql' => [
    'driver'    => 'mysql',
    'host'      => env('DB_HOST'),
    'database'  => env('DB_DATABASE'),
    'username'  => env('DB_USERNAME'),
    'password'  => env('DB_PASSWORD'),
    'options'   => [
        PDO::ATTR_TIMEOUT           => 5,
        PDO::ATTR_PERSISTENT        => false, // workers should NOT use persistent connections
        PDO::MYSQL_ATTR_INIT_COMMAND => "SET time_zone='+00:00'",
    ],
    'pool' => [
        'min_connections' => 1,
        'max_connections' => 5,    // per worker process
        'connect_timeout' => 3.0,
        'wait_timeout'    => 3.0,
        'heartbeat'       => -1,
        'max_idle_time'   => 60.0,
    ],
],

// App\Jobs\Concerns\RefreshesConnections.php
trait RefreshesConnections
{
    public function handle(): void
    {
        // Force reconnect if connection has gone away
        try {
            DB::connection()->getPdo();
        } catch (\Exception) {
            DB::reconnect();
        }

        $this->process(); // implemented by the job
    }
}

// Alternatively — configure the Horizon supervisor to restart workers periodically:
// This is cleaner than manual reconnection logic
// horizon.php
'supervisors' => [
    'default' => [
        'maxProcesses'   => 10,
        'balanceMaxShift' => 1,
        'balanceCooldown' => 3,
        // restart workers after processing N jobs to clear any state/memory leaks
        // done via --max-jobs flag
    ],
],

# Supervisor config for workers with connection recycling
# /etc/supervisor/conf.d/laravel-worker.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/artisan queue:work redis \
    --sleep=3 \
    --tries=3 \
    --max-time=3600 \
    --max-jobs=1000 \
    --memory=256
autostart=true
autorestart=true
numprocs=8
redirect_stderr=true
stdout_logfile=/var/log/worker.log

# --max-time=3600   restart after 1 hour (clears memory leaks, refreshes connections)
# --max-jobs=1000   restart after 1000 jobs (prevents slow memory growth)

; /etc/php/8.3/cli/conf.d/20-opcache-worker.ini
; For queue workers specifically (PHP CLI)

[opcache]
opcache.enable=1
opcache.enable_cli=1                 ; critical — OPcache disabled for CLI by default!
opcache.memory_consumption=256       ; MB — tune based on your application size
opcache.interned_strings_buffer=32   ; MB for interned strings (class names, keys, etc.)
opcache.max_accelerated_files=20000  ; increase if you have many files (vendor/)
opcache.revalidate_freq=0            ; never revalidate — workers don't hot-reload
opcache.validate_timestamps=0        ; skip stat() calls entirely
opcache.save_comments=1              ; needed for doctrine annotations / phpdoc parsing
opcache.fast_shutdown=1              ; skip destructor calls on shutdown
opcache.jit_buffer_size=128M         ; PHP 8+ JIT — significant gain for CPU-bound jobs
opcache.jit=tracing                  ; tracing JIT — best for long-running CPU work

// Verifying OPcache is active in workers
// Add this to a diagnostic job or artisan command:

class DiagnoseWorkerCommand extends Command
{
    protected $signature = 'worker:diagnose';

    public function handle(): void
    {
        $status = opcache_get_status();

        $this->table(['Setting', 'Value'], [
            ['OPcache enabled',     $status['opcache_enabled'] ? 'Yes' : 'No'],
            ['Cached scripts',      $status['opcache_statistics']['num_cached_scripts']],
            ['Cache hits',          $status['opcache_statistics']['hits']],
            ['Cache misses',        $status['opcache_statistics']['misses']],
            ['Memory used (MB)',    round($status['memory_usage']['used_memory'] / 1024 / 1024, 2)],
            ['Memory free (MB)',    round($status['memory_usage']['free_memory'] / 1024 / 1024, 2)],
            ['JIT enabled',         $status['jit']['enabled'] ?? false ? 'Yes' : 'No'],
        ]);
    }
}

// Benchmarking baseline — dispatch N no-op jobs and time them
class BenchmarkQueueCommand extends Command
{
    protected $signature = 'queue:benchmark {count=1000} {--queue=benchmark}';

    public function handle(): void
    {
        $count = (int) $this->argument('count');
        $queue = $this->option('queue');

        // Dispatch N no-op jobs
        $this->info("Dispatching {$count} benchmark jobs...");
        $dispatchStart = microtime(true);

        for ($i = 0; $i < $count; $i++) {
            NoOpBenchmarkJob::dispatch()->onQueue($queue);
        }

        $dispatchTime = microtime(true) - $dispatchStart;
        $this->info(sprintf('Dispatched %d jobs in %.2fs (%.0f/s)',
            $count,
            $dispatchTime,
            $count / $dispatchTime
        ));

        // Now process them and measure throughput
        // Run: php artisan queue:work --queue=benchmark --max-jobs=1000 --once
        // and observe the time in Horizon or via Redis monitor
    }
}

// App\Jobs\NoOpBenchmarkJob.php
class NoOpBenchmarkJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle(): void
    {
        // Intentionally empty — measures queue infrastructure overhead only
    }
}

# Real-time throughput monitoring via Redis
# Count jobs processed in the last 60 seconds using Redis keyspace events

# In redis-cli:
MONITOR   # shows all commands in real time — useful for seeing job pop rate

# Better: use Redis XADD streams or Horizon's built-in metrics
# Horizon stores throughput per supervisor per minute in Redis
redis-cli HGETALL "horizon:supervisor:throughput"

# Measure queue depth changes over time
watch -n1 'redis-cli LLEN "queues:default"'

# Full queue stats via Horizon API
curl http://your-app.test/horizon/api/stats | jq .

// Instrumenting job processing time with Telescope or custom metrics
// App\Jobs\Concerns\TracksExecutionTime.php
trait TracksExecutionTime
{
    private float $startTime;

    public function middleware(): array
    {
        return [
            new class implements JobMiddleware {
                public function handle(mixed $job, callable $next): void
                {
                    $start = microtime(true);
                    $next($job);
                    $duration = microtime(true) - $start;

                    // Push to your metrics system (Prometheus, Datadog, etc.)
                    app('metrics')->histogram(
                        name: 'queue_job_duration_seconds',
                        value: $duration,
                        labels: ['job' => class_basename($job)]
                    );
                }
            }
        ];
    }
}

// BAD: passes the entire array of data unnecessarily
class ProcessOrderJob implements ShouldQueue
{
    public function __construct(
        private array $orderData,        // could be 50KB+ of serialized array
        private array $customerData,     // more unnecessary data
        private array $productList,      // potentially hundreds of products
    ) {}
}

// GOOD: pass only IDs — let the job fetch what it needs
class ProcessOrderJob implements ShouldQueue
{
    use SerializesModels;

    public function __construct(
        private readonly int $orderId,   // 8 bytes
    ) {}

    public function handle(OrderRepository $orders): void
    {
        $order = $orders->findWithRelations($this->orderId);
        // fetch exactly the relations you need, nothing more
    }
}

// For batches — use IDs, not models
Bus::batch(
    $orderIds->map(fn($id) => new ProcessOrderJob($id))->toArray()
)->dispatch();

// Measuring actual payload sizes before they hit the queue
class PayloadSizeAuditMiddleware implements JobMiddleware
{
    public function handle(mixed $job, callable $next): void
    {
        $payload = serialize($job);
        $size    = strlen($payload);

        if ($size > 10_240) { // 10 KB warning threshold
            logger()->warning('Large job payload detected', [
                'job'       => get_class($job),
                'size_kb'   => round($size / 1024, 2),
                'threshold' => '10 KB',
            ]);
        }

        $next($job);
    }
}

// SQS hard limit math:
// SQS max message size: 256 KB = 262,144 bytes
// After base64 encoding (SQS uses base64): effective limit ~192 KB raw
// After JSON envelope overhead: ~185 KB of actual payload
// If you need larger — use S3 Extended Client pattern:
//   1. Store payload in S3
//   2. Pass only the S3 key in the SQS message
//   3. Job downloads payload from S3 in handle()

// Instead of dispatching one job with 10,000 IDs:
// Dispatch 100 jobs with 100 IDs each
$userIds
    ->chunk(100)
    ->each(fn ($chunk) => ProcessUserBatchJob::dispatch($chunk->values()->toArray()));

// For very dynamic payloads — store in Redis/DB and pass a reference key
class LargePayloadJob implements ShouldQueue
{
    public function __construct(
        private readonly string $payloadKey  // Redis key
    ) {}

    public function handle(): void
    {
        $payload = Cache::get($this->payloadKey);

        if (! $payload) {
            // Payload expired — job cannot run, fail gracefully
            $this->fail(new \RuntimeException("Payload key {$this->payloadKey} expired"));
            return;
        }

        // Process...

        // Clean up
        Cache::forget($this->payloadKey);
    }
}