Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Performance, Caching & Scalability / Cara Mengoptimalkan Laravel Qu...
Performance, Caching & Scalability

Cara Mengoptimalkan Laravel Queue Worker untuk Pemrosesan Background Berskala Besar

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
12 min read
34 views

Dari "worker sudah jalan" menjadi "puluhan ribu job per jam tetap terkendali": mengukur throughput dan waktu tunggu, menghitung jumlah worker, auto-balancing Horizon, merancang job yang kecil dan ringan, fan-out bertahap, pembatasan laju ke API eksternal tanpa menghabiskan percobaan, mencegah antrean prioritas rendah kelaparan, serta autoscaling dan pemantauan antrean.

Overview

Artikel Queue dan Job membahas dasar-dasarnya: job, retry, batch, Supervisor. Artikel ini membahas apa yang terjadi saat volumenya naik.

Aplikasi RW sekarang dipakai 120 RW. Pada tanggal 10 pukul 09:00, scheduler mengirim pengingat iuran ke 18.000 keluarga. Yang terjadi:

  • antrean whatsapp berisi 18.000 job, dan provider WhatsApp membatasi 30 pesan per menit per perangkat,
  • job yang terkena batas laju di-release berulang kali sampai percobaannya habis dan masuk failed_jobs,
  • email reset password menunggu 40 menit karena worker sibuk,
  • worker laporan kehabisan memori setelah beberapa jam,
  • MySQL menolak koneksi karena 60 worker masing-masing membuka koneksi.

Masalah di atas tidak selesai dengan "tambah worker". Sebagian malah memburuk.

Hasil akhir:

  • metrik yang perlu dipantau dan cara menghitung kebutuhan worker,
  • konfigurasi Horizon dengan supervisor per kelas pekerjaan dan auto-balancing,
  • pola job untuk volume besar: kecil, idempoten, payload ringan, fan-out bertahap,
  • pembatasan laju yang benar dengan retryUntil dan maxExceptions,
  • perlindungan antrean penting dari kelaparan,
  • pemantauan waktu tunggu dan autoscaling berdasarkan panjang antrean.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
Redis 7.x (instance data dengan noeviction)
Laravel Horizon 5.x
MySQL 8.4
Supervisor / systemd / Kubernetes Untuk menjalankan Horizon

Step-by-step Tutorial

Langkah 1: Ukur Metrik yang Tepat

Metrik Arti Sumber
Waktu tunggu (wait time) Lama job antre sebelum diproses Horizon (wait time per antrean)
Runtime Lama job diproses Horizon (metrics per job)
Throughput Job selesai per menit Horizon
Panjang antrean Job yang menunggu Queue::size(), Horizon
Failure rate Persentase job gagal failed_jobs, Horizon
Memori worker Pemakaian per proses ps, Horizon

Metrik terpenting untuk pengguna adalah waktu tunggu, bukan jumlah job. 50.000 job laporan yang antre semalaman tidak masalah; 50 email reset password yang menunggu 10 menit adalah masalah.

Tetapkan target per antrean (SLA):

Antrean Target waktu tunggu
kritis (OTP, reset password, webhook pembayaran) < 10 detik
default (notifikasi, event umum) < 1 menit
whatsapp < 30 menit (dibatasi provider)
laporan < 15 menit

Langkah 2: Hitung Kebutuhan Worker

Sama seperti PHP-FPM, gunakan Little's Law:

Worker yang dibutuhkan ≈ laju job masuk (job/detik) × runtime rata-rata (detik)
Antrean Masuk Runtime Worker minimum
default 600 job/menit = 10/detik 0,3 detik 3
laporan 120 job pada tanggal 1 40 detik 120 × 40 / 900 detik target ≈ 6
whatsapp 18.000 job dibatasi 30/menit oleh provider Tidak bisa dipercepat dengan worker

Baris terakhir penting: bila bottleneck ada di layanan luar, menambah worker hanya menambah job yang ditolak. Yang bisa dilakukan adalah menambah kapasitas di sisi provider (lebih banyak perangkat/nomor, paket lebih tinggi) atau menyebar pengiriman lebih awal.

Tambahkan margin 30–50% untuk lonjakan.

Langkah 3: Horizon dengan Supervisor per Kelas Pekerjaan

Kelompokkan antrean berdasarkan karakteristiknya, bukan satu supervisor untuk semua:

// config/horizon.php
'defaults' => [
    'supervisor-kritis' => [
        'connection'   => 'redis',
        'queue'        => ['kritis'],
        'balance'      => false,
        'minProcesses' => 2,
        'maxProcesses' => 2,
        'tries'        => 3,
        'timeout'      => 30,
        'memory'       => 128,
    ],
    'supervisor-umum' => [
        'connection'   => 'redis',
        'queue'        => ['default', 'notifikasi'],
        'balance'      => 'auto',
        'autoScalingStrategy' => 'time',   // berdasarkan perkiraan waktu menghabiskan antrean
        'minProcesses' => 1,
        'maxProcesses' => 10,
        'balanceMaxShift' => 2,            // tambah/kurangi maksimal 2 proses per siklus
        'balanceCooldown' => 3,            // detik antar-penyesuaian
        'tries'        => 3,
        'timeout'      => 60,
        'memory'       => 128,
    ],
    'supervisor-whatsapp' => [
        'connection'   => 'redis',
        'queue'        => ['whatsapp'],
        'balance'      => false,
        'minProcesses' => 2,
        'maxProcesses' => 2,               // sengaja kecil: dibatasi provider
        'tries'        => 0,               // diatur di job lewat retryUntil
        'timeout'      => 30,
        'memory'       => 128,
    ],
    'supervisor-laporan' => [
        'connection'   => 'redis',
        'queue'        => ['laporan'],
        'balance'      => 'auto',
        'minProcesses' => 1,
        'maxProcesses' => 6,
        'tries'        => 3,
        'timeout'      => 300,
        'memory'       => 512,
        'nice'         => 10,              // prioritas CPU lebih rendah
    ],
],

'environments' => [
    'production' => [
        'supervisor-kritis'   => [],
        'supervisor-umum'     => ['maxProcesses' => 12],
        'supervisor-whatsapp' => [],
        'supervisor-laporan'  => [],
    ],
    'local' => [
        'supervisor-umum' => ['queue' => ['kritis', 'default', 'notifikasi', 'whatsapp', 'laporan'], 'maxProcesses' => 3],
    ],
],

// Peringatan bila waktu tunggu melebihi batas (detik)
'waits' => [
    'redis:kritis'     => 10,
    'redis:default'    => 60,
    'redis:notifikasi' => 120,
    'redis:whatsapp'   => 1800,
    'redis:laporan'    => 900,
],

Mengapa supervisor kritis punya proses tetap: antrean penting harus selalu punya worker yang siaga dan tidak pernah "dipinjam" untuk antrean lain. Dengan satu supervisor ['kritis', 'default', 'laporan'], worker memang memeriksa kritis lebih dulu, tetapi bila semua worker sedang mengerjakan laporan 5 menit, job kritis tetap menunggu.

Pemberitahuan waktu tunggu panjang:

// app/Providers/HorizonServiceProvider.php
public function boot(): void
{
    parent::boot();

    Horizon::routeMailNotificationsTo(config('app.admin_email'));
    // atau Horizon::routeSlackNotificationsTo(...)
}

Langkah 4: Job Kecil, Payload Ringan

Pecah pekerjaan besar menjadi unit kecil. Satu job "kirim pengingat ke 18.000 keluarga" yang gagal di keluarga ke-9.000 harus diulang dari awal (atau rumit melacak posisinya). 18.000 job kecil bisa diulang satu per satu.

Namun job yang terlalu kecil juga mahal: setiap job punya overhead (serialisasi, round-trip Redis, boot). Untuk pekerjaan yang sangat ringan (misalnya memperbarui 1 kolom), kelompokkan per 100–500 item.

Payload ringan. Model di constructor diserialisasi sebagai ID, tetapi relasi yang sudah dimuat ikut dicatat dan dimuat ulang saat job berjalan:

// ❌ Keluarga dengan relasi iuran (bisa ratusan) ikut dicatat, lalu di-load ulang di worker
$keluarga->load('iuran');
KirimPengingat::dispatch($keluarga);

// ✅ Tanpa relasi
KirimPengingat::dispatch($keluarga->withoutRelations());

// ✅ Atau atribut di kelas job
use Illuminate\Queue\Attributes\WithoutRelations;

class KirimPengingat implements ShouldQueue
{
    use Queueable;

    public function __construct(#[WithoutRelations] public Keluarga $keluarga) {}
}

Jangan memasukkan string besar (isi file, HTML laporan, array ribuan elemen) ke payload. Simpan di storage/database, kirim ID atau path-nya.

Langkah 5: Fan-out Bertahap

Men-dispatch 18.000 job dalam satu request atau command membuat memori melonjak dan Redis menerima ledakan tulis sekaligus. Gunakan job "pengirim" yang membuat job turunan per potongan:

// app/Jobs/JadwalkanPengingatIuran.php
class JadwalkanPengingatIuran implements ShouldQueue
{
    use Queueable;

    public function __construct(public string $periode, public int $mulaiDariId = 0)
    {
        $this->onQueue('default');
    }

    public function handle(): void
    {
        $keluargas = Keluarga::query()
            ->where('id', '>', $this->mulaiDariId)
            ->where('wa_opt_in', true)
            ->whereHas('iuran', fn ($q) => $q->where('periode', $this->periode)->where('status', 'belum_bayar'))
            ->orderBy('id')
            ->limit(500)
            ->pluck('id');

        if ($keluargas->isEmpty()) {
            return;
        }

        // Kirim 500 job dalam satu operasi bulk ke Redis
        Queue::connection('redis')->bulk(
            $keluargas->map(fn ($id) => new KirimPengingatWhatsApp($id, $this->periode))->all(),
            queue: 'whatsapp',
        );

        // Lanjut ke potongan berikutnya
        self::dispatch($this->periode, $keluargas->last());
    }
}

Untuk batch yang membutuhkan progres, tambahkan job ke batch secara bertahap dari dalam job yang termasuk batch tersebut:

// di dalam job yang memakai trait Batchable
$this->batch()->add($potonganJobBerikutnya);

Langkah 6: Pembatasan Laju yang Tidak Menghabiskan Percobaan

Middleware RateLimited dan Redis::throttle me-release job kembali ke antrean bila batas tercapai. Setiap release dihitung sebagai percobaan. Dengan $tries = 3, job yang tiga kali terkena batas laju akan gagal, padahal tidak ada error apa pun.

Solusinya: batasi berdasarkan waktu, bukan jumlah percobaan, dan batasi exception secara terpisah.

// app/Jobs/KirimPengingatWhatsApp.php
use Illuminate\Queue\Middleware\RateLimited;

class KirimPengingatWhatsApp implements ShouldQueue
{
    use Queueable;

    public int $tries = 0;              // tanpa batas jumlah percobaan...
    public int $maxExceptions = 3;      // ...tetapi gagal setelah 3 exception sungguhan
    public int $timeout = 30;

    public function __construct(public int $keluargaId, public string $periode)
    {
        $this->onQueue('whatsapp');
    }

    public function retryUntil(): \DateTime
    {
        return now()->addHours(6);      // batas waktu total
    }

    public function middleware(): array
    {
        return [new RateLimited('whatsapp-provider')];
    }

    public function backoff(): array
    {
        return [30, 120, 300];
    }

    public function handle(WhatsAppProvider $wa): void
    {
        // idempoten: lewati bila pengingat periode ini sudah terkirim
        // ... kirim
    }
}
// app/Providers/AppServiceProvider.php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('whatsapp-provider', fn () => Limit::perMinute(30));

Untuk batas per kunci (misalnya per perangkat pengirim), kembalikan Limit::perMinute(30)->by($job->perangkatId).

Redis::funnel membatasi jumlah job yang berjalan bersamaan (concurrency), cocok untuk API yang membatasi koneksi paralel:

public function handle(): void
{
    Redis::funnel('api-kelurahan')->limit(3)->block(0)->then(
        fn () => $this->sinkronkan(),
        fn () => $this->release(15),
    );
}

Langkah 7: Koneksi Database

Setiap proses worker membuka koneksi database sendiri dan mempertahankannya. 60 worker di 3 server = 180 koneksi, ditambah PHP-FPM.

  • Hitung total koneksi semua proses dibanding max_connections MySQL.
  • Worker yang menunggu job lama bisa terkena wait_timeout MySQL dan mendapat error MySQL server has gone away. Laravel menyambung ulang otomatis untuk error seperti ini pada query berikutnya, tetapi bila sering terjadi di tengah transaksi, sesuaikan wait_timeout atau --max-time worker.
  • Untuk worker yang tidak menyentuh database (misalnya hanya memanggil API), tidak ada koneksi yang dibuka sampai query pertama.

Langkah 8: Memori dan Siklus Hidup Worker

Worker adalah proses PHP yang berjalan lama. Hal-hal yang bocor perlahan (cache statis, listener yang terdaftar berulang, log query) bisa menumpuk.

php artisan queue:work redis --queue=laporan --memory=512 --max-jobs=500 --max-time=3600 --timeout=300
  • --memory: worker berhenti dengan rapi setelah job selesai bila memori melebihi batas.
  • --max-jobs/--max-time: daur ulang berkala.
  • Jangan mengaktifkan DB::enableQueryLog() di worker; log query tumbuh tanpa batas.
  • Untuk job yang memproses data besar, gunakan lazyById()/chunkById() dan lepaskan referensi besar setelah dipakai.

Horizon menerapkan memory per supervisor dan mendaur ulang proses secara otomatis.

Langkah 9: Shutdown yang Anggun Saat Deploy

Saat deploy, php artisan horizon:terminate (atau queue:restart) meminta worker berhenti setelah job yang sedang berjalan selesai. Agar job panjang tidak terpotong:

  • Supervisor: stopwaitsecs lebih panjang dari timeout job terlama.
  • systemd: TimeoutStopSec yang sama.
  • Kubernetes: terminationGracePeriodSeconds lebih panjang dari timeout job, dan proses menerima SIGTERM.
; /etc/supervisor/conf.d/horizon.conf
[program:horizon]
command=php /var/www/rw/current/artisan horizon
user=deploy
autostart=true
autorestart=true
stopwaitsecs=330
stopsignal=SIGTERM
redirect_stderr=true
stdout_logfile=/var/www/rw/shared/storage/logs/horizon.log

Job yang tetap terpotong (server mati mendadak) akan diambil ulang setelah retry_after. Itulah alasan semua job harus idempoten.

Langkah 10: Worker di Banyak Server dan Autoscaling

Horizon bisa dijalankan di beberapa server sekaligus terhadap Redis yang sama; masing-masing menjalankan supervisor sesuai konfigurasinya. Gunakan nama environment atau variabel untuk membedakan peran server:

'environments' => [
    'production'         => [ /* semua supervisor */ ],
    'production-laporan' => [ 'supervisor-laporan' => ['maxProcesses' => 12] ],
],
# .env server khusus laporan
HORIZON_ENV=production-laporan
// config/horizon.php
'env' => env('HORIZON_ENV'),

Di lingkungan container, autoscaling bisa dipicu dari panjang antrean Redis (misalnya KEDA dengan scaler redis yang membaca LLEN antrean). Perhatikan bahwa prefix Laravel ikut menjadi nama kunci: antrean whatsapp dengan prefix rw_ tersimpan sebagai rw_queues:whatsapp.

Untuk deteksi antrean menumpuk tanpa Horizon, Laravel menyediakan command queue:monitor yang memicu event QueueBusy:

// routes/console.php
Schedule::command('queue:monitor redis:kritis,redis:default --max=100')->everyMinute();
// AppServiceProvider
use Illuminate\Queue\Events\QueueBusy;

Event::listen(function (QueueBusy $event) {
    Notification::route('mail', config('app.admin_email'))
        ->notify(new AntreanMenumpuk($event->connection, $event->queue, $event->size));
});

Langkah 11: Kegagalan dalam Skala Besar

Ketika layanan luar mati, ribuan job bisa gagal sekaligus dan memenuhi failed_jobs.

  • Backoff dengan jitter agar percobaan ulang tidak serentak.
  • Circuit breaker: bila provider sedang mati, job segera di-release dengan jeda panjang alih-alih memanggil API yang pasti gagal (lihat artikel HTTP Client).
  • ThrottlesExceptions: setelah beberapa exception berturut-turut, job berikutnya ditunda otomatis.
use Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis;

public function middleware(): array
{
    return [
        new RateLimited('whatsapp-provider'),
        (new ThrottlesExceptionsWithRedis(10, 5 * 60))->backoff(1)->by('provider-whatsapp'),
    ];
}
  • Retry massal yang terkendali: php artisan queue:retry --queue=whatsapp mengembalikan semua sekaligus. Untuk ribuan job, lebih aman memakai job/command yang mengembalikan secara bertahap, atau memakai filter rentang ID.

Langkah 12: Uji Beban Antrean

Sebelum tanggal 10, uji kapasitas dengan data sintetis di staging:

// app/Console/Commands/UjiBebanAntrean.php
public function handle(): int
{
    $jumlah = (int) $this->option('jumlah') ?: 10_000;
    $mulai = now();

    collect(range(1, $jumlah))->chunk(500)->each(function ($potongan) {
        Queue::connection('redis')->bulk(
            $potongan->map(fn ($i) => new JobUji($i))->all(),
            queue: 'default',
        );
    });

    $this->info("{$jumlah} job dikirim dalam ".$mulai->diffInMilliseconds(now()).' ms. Pantau di Horizon.');

    return self::SUCCESS;
}

Amati di Horizon: throughput per menit, waktu tunggu, apakah auto-balancing menambah proses, dan apakah memori/koneksi database tetap aman.

// tests/Feature/Queue/PengingatSkalaTest.php
it('fan-out membagi pengiriman per 500 dan berantai', function () {
    Queue::fake();
    Keluarga::factory()->count(1200)->hasIuran(['periode' => '2026-10', 'status' => 'belum_bayar'])->create(['wa_opt_in' => true]);

    (new JadwalkanPengingatIuran('2026-10'))->handle();

    Queue::assertPushedOn('whatsapp', KirimPengingatWhatsApp::class);
    Queue::assertCount(501);                                // 500 pengingat + 1 lanjutan
    Queue::assertPushed(JadwalkanPengingatIuran::class, fn ($job) => $job->mulaiDariId > 0);
});

it('job WhatsApp dibatasi waktu, bukan jumlah percobaan', function () {
    $job = new KirimPengingatWhatsApp(1, '2026-10');

    expect($job->tries)->toBe(0)
        ->and($job->maxExceptions)->toBe(3)
        ->and($job->retryUntil())->toBeInstanceOf(DateTime::class);
});

Troubleshooting

Error / Gejala Penyebab Solusi
Job gagal MaxAttemptsExceeded tanpa error Release oleh rate limiter dihitung percobaan tries = 0 + retryUntil + maxExceptions
Job kritis menunggu lama Berbagi worker dengan job panjang Supervisor terpisah dengan proses tetap
Menambah worker tidak mempercepat Bottleneck di layanan luar atau database Ukur; tingkatkan kapasitas sumbernya
Too many connections Total worker × server melebihi max_connections Hitung ulang; batasi maxProcesses
Memori worker naik terus Kebocoran jangka panjang --memory, --max-jobs, --max-time
Payload job sangat besar, Redis membengkak Relasi/data besar ikut diserialisasi withoutRelations, kirim ID
Dispatch ribuan job membuat request timeout Fan-out sinkron Job pengirim bertahap + bulk
Job terpotong saat deploy stopwaitsecs terlalu pendek Lebih panjang dari timeout job
Auto-balancing berubah-ubah terlalu cepat Shift/cooldown terlalu agresif Atur balanceMaxShift, balanceCooldown
Ribuan job gagal saat provider mati Tanpa circuit breaker/throttle ThrottlesExceptions, circuit breaker

Best Practices

Keamanan

  • Payload job tidak membawa data sensitif; kirim ID.
  • Dasbor Horizon dilindungi gate.
  • Pembatasan laju ke provider menghindari pemblokiran akun/nomor.

Performa

  • Supervisor per kelas pekerjaan; antrean kritis dengan proses tetap.
  • Hitung worker dari laju masuk × runtime, tambah margin.
  • Fan-out bertahap dengan bulk dan job berantai.
  • Payload ringan dan job seukuran yang wajar.

Maintainability

  • Target waktu tunggu per antrean dan peringatan waits di Horizon.
  • Job idempoten, dibatasi waktu (retryUntil) bila terkena rate limit.
  • Shutdown anggun dan deploy yang memberi waktu job selesai.
  • Uji beban antrean sebelum periode puncak.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Laravel Horizon 5.x
Redis 7.x
MySQL 8.4
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya