Cara Mengoptimalkan Laravel Queue Worker untuk Pemrosesan Background Berskala Besar
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
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.
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:
whatsapp berisi 18.000 job, dan provider WhatsApp membatasi 30 pesan per menit per perangkat,failed_jobs,Masalah di atas tidak selesai dengan "tambah worker". Sebagian malah memburuk.
Hasil akhir:
retryUntil dan maxExceptions,| 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 |
| 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 |
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.
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(...)
}
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.
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);
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),
);
}
Setiap proses worker membuka koneksi database sendiri dan mempertahankannya. 60 worker di 3 server = 180 koneksi, ditambah PHP-FPM.
max_connections MySQL.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.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.DB::enableQueryLog() di worker; log query tumbuh tanpa batas.lazyById()/chunkById() dan lepaskan referensi besar setelah dipakai.Horizon menerapkan memory per supervisor dan mendaur ulang proses secara otomatis.
Saat deploy, php artisan horizon:terminate (atau queue:restart) meminta worker berhenti setelah job yang sedang berjalan selesai. Agar job panjang tidak terpotong:
stopwaitsecs lebih panjang dari timeout job terlama.TimeoutStopSec yang sama.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.
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));
});
Ketika layanan luar mati, ribuan job bisa gagal sekaligus dan memenuhi failed_jobs.
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'),
];
}
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.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);
});
| 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 |
Keamanan
Performa
bulk dan job berantai.Maintainability
waits di Horizon.retryUntil) bila terkena rate limit.| 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 |
Sebelumnya
PHP-FPM Tuning untuk Laravel: Memahami Worker, Memory Limit, dan Kapasitas Request
Berikutnya
Laravel Octane vs PHP-FPM: Perbedaan, Kelebihan, Risiko, dan Skenario Penggunaan
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk