Site icon SUSANTOKUN

Laravel Horizon: Kelola Queue Redis Tanpa Drama

Kalau aplikasi Laravel kamu mulai punya pekerjaan latar seperti kirim email massal, generate PDF, atau resize gambar, queue jadi komponen yang gampang lupa dipantau. Laravel Horizon adalah jawabannya: dashboard plus konfigurasi queue berbasis kode yang khusus bekerja di atas Redis. Artikel ini membahas cara memasang, mengatur supervisor, mengamankan dashboard, sampai menyiapkan Horizon agar aman saat deploy.

Apa Itu Laravel Horizon

Horizon memperluas queue bawaan Laravel dengan tiga hal: dashboard, konfigurasi worker dalam satu file yang ikut versi di Git, serta metrik throughput dan waktu tunggu antrean. Semua pengaturan supervisor berada di config/horizon.php, tidak tersebar di banyak skrip.

Poin penting: Horizon bukan pengganti queue, tapi lapisan pengelola di atasnya. Job tetap class ShouldQueue biasa; yang berubah hanya cara worker dijalankan dan dipantau. Untuk proyek kecil dengan satu jenis job, php artisan queue:work sudah cukup — menambah Horizon cuma menambah Redis dan satu proses supervisor tanpa manfaat sebanding.

Syarat Wajib: Queue Harus Redis

Horizon hanya mau jalan kalau koneksi queue memakai Redis. Driver database atau sqs tidak didukung, dan dokumentasi resmi menyebut Horizon belum kompatibel dengan Redis Cluster. Sebelum composer require, pastikan config/queue.php memakai redis sebagai default connection.

Catatan yang sering bikin bingung: Horizon memakai nama koneksi Redis internal horizon. Nama itu dicadangkan, jadi jangan dipakai untuk koneksi lain di config/database.php maupun sebagai nilai opsi use.

Instalasi dan Publish Aset

Prosesnya dua perintah. Yang kedua menyalin file konfigurasi dan aset dashboard ke dalam proyek:

composer require laravel/horizon
php artisan horizon:install

Setelah itu muncul config/horizon.php dan provider app/Providers/HorizonServiceProvider.php. Buka file konfigurasinya: di situ seluruh perilaku worker ditentukan.

Soal versi, rilis terbaru di Packagist saat artikel ini ditulis adalah Horizon 5.51.0 (2 November 2026), masih menerima PHP ^8.0 dan komponen Laravel ^9.21 sampai ^13.0. Kode di branch 5.x GitHub sudah menaikkan syarat minimum ke PHP ^8.2 dengan komponen ^12.0|^13.0, jadi rilis besar berikutnya akan lebih ketat. Kalau kamu masih di Laravel 10 ke bawah, sematkan versi Horizon yang cocok di composer.json.

Mengatur Supervisor di config/horizon.php

Opsi utamanya environments: array per environment yang tiap entrinya boleh berisi beberapa supervisor — kelompok proses worker yang membagi beban antar antrean. Wildcard * bisa dipakai sebagai environment cadangan, dan nilai bersama diletakkan di opsi defaults supaya tidak perlu ditulis ulang.

Satu perilaku yang perlu diingat: saat aplikasi masuk maintenance mode, job tidak diproses kecuali supervisor diberi opsi force bernilai true.

Memilih Strategi Balancing: auto, simple, atau false

Berbeda dari queue bawaan, Horizon memberi tiga pilihan cara membagi worker:

Kalau jatah proses per antrean harus berbeda, pecah menjadi beberapa supervisor: misalnya 10 proses untuk default dan 2 proses khusus notifications, supaya job notifikasi tidak berebut jatah dengan job berat.

Menyetel tries, timeout, dan backoff

Tiga opsi ini paling sering menimbulkan bug halus di produksi:

Middleware WithoutOverlapping dan RateLimited memakan jatah percobaan, jadi naikkan tries kalau memakainya. Untuk worker berjalan lama, manfaatkan memory (default 128 MB), maxJobs, dan maxTime agar worker restart berkala dan tidak bocor memori.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'tries' => 3,
            'timeout' => 90,
            'backoff' => [10, 30, 60],
            'memory' => 256,
        ],
    ],
],

Mengamankan Dashboard Horizon di Produksi

Dashboard ada di route /horizon. Di lokal ia bebas diakses, tetapi di luar lokal akses dikontrol gate viewHorizon di HorizonServiceProvider — jangan biarkan gate itu berisi daftar email contoh dari dokumentasi. Batasi ke email admin tertentu atau tambahkan pembatasan IP.

Kalau kamu memakai autentikasi alternatif dan pengguna Horizon tidak login lewat guard Laravel, ubah signature closure gate menjadi function (User $user = null) agar Laravel tidak memaksa autentikasi.

Deploy: Supervisor dan horizon:terminate

Di server, Horizon dijalankan process monitor agar otomatis hidup lagi kalau mati. Di Ubuntu, Supervisor pilihan paling umum. Simpan konfigurasinya di /etc/supervisor/conf.d/horizon.conf:

[program:horizon]
process_name=%(program_name)s
command=php /var/www/app/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/var/www/app/storage/logs/horizon.log
stopwaitsecs=3600

Nilai stopwaitsecs harus lebih besar dari durasi job paling lama, kalau tidak Supervisor bisa membunuh job yang setengah jalan. Setelah file dibuat: supervisorctl reread, lalu supervisorctl update, terakhir supervisorctl start horizon.

Saat deploy kode baru, jalankan php artisan horizon:terminate di langkah deploy. Proses berhenti rapi setelah job selesai, lalu Supervisor menyalakannya kembali dengan kode terbaru. Kalau dilewati, perubahan class job tidak akan terasa di server karena worker menyimpan kode di memori.

Metrics: horizon:snapshot Tiap Lima Menit

Grafik metrics tidak terisi sendiri; Horizon butuh horizon:snapshot yang dijalankan berkala untuk merekam kondisi antrean. Jadwalkan di routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('horizon:snapshot')->everyFiveMinutes();

Jumlah snapshot diatur lewat metrics.trim_snapshots (default 24 untuk job dan 24 untuk queue). Yang dibatasi adalah jumlah snapshot, bukan umur data, jadi panjang riwayat bergantung pada frekuensi perintah di atas. Untuk membersihkan seluruh metrik, pakai php artisan horizon:clear-metrics.

Merawat Antrean: Tag, Silenced Jobs, dan Job Gagal

Horizon otomatis memberi tag berdasarkan model Eloquent di properti constructor: job yang membawa model Video id 1 mendapat tag App\Models\Video:1. Butuh tag sendiri? Tambahkan method tags() yang mengembalikan array string pada class job.

Untuk job pihak ketiga yang membanjiri daftar completed, gunakan opsi silenced berisi nama class atau silenced_tags, atau implementasikan interface Laravel\Horizon\Contracts\Silenced pada class job.

Job gagal dibersihkan lewat php artisan horizon:forget <id> atau --all; untuk mengosongkan satu antrean, pakai php artisan horizon:clear --queue=emails. Ingat, clear membuang job yang belum diproses — bukan menandainya selesai.

Kalau butuh notifikasi saat antrean menumpuk, panggil Horizon::routeMailNotificationsTo, Horizon::routeSlackNotificationsTo, atau Horizon::routeSmsNotificationsTo dari method boot di provider-nya. Ambang “menunggu lama” diatur per kombinasi koneksi dan antrean lewat opsi waits, default 60 detik. Ini pelengkap yang pas untuk Laravel Pulse yang memantau sisi aplikasi, bukan sisi antrean.

Horizon juga sering dipasang bersama fitur real-time: saat job selesai dan perlu mendorong update ke browser, Laravel Reverb mengirim lewat WebSocket sementara Horizon memastikan job benar-benar diproses. Untuk rilis bertahap, kombinasikan dengan Laravel Pennant agar job versi baru hanya jalan untuk pengguna yang masuk daftar.

FAQ

Apakah Horizon bisa dipakai dengan queue database?

Tidak. Horizon dirancang khusus untuk queue Redis dan belum mendukung Redis Cluster. Kalau aplikasimu masih memakai driver database, pilihannya memindahkan queue ke Redis atau tetap memakai queue:work dengan monitoring terpisah.

Kenapa perubahan kode job tidak terasa setelah deploy?

Hampir selalu karena proses Horizon lama masih berjalan. Jalankan php artisan horizon:terminate di pipeline deploy dan biarkan Supervisor menyalakannya ulang.

Bagaimana cara menghentikan Horizon tanpa memotong job yang sedang jalan?

Gunakan horizon:terminate, bukan kill proses: Horizon menyelesaikan job yang sedang dieksekusi lalu berhenti. Untuk jeda sementara, pakai horizon:pause dan horizon:continue, yang juga tersedia per supervisor lewat horizon:pause-supervisor dan horizon:continue-supervisor.

Kesimpulan

Laravel Horizon memberi dua keuntungan sekaligus: konfigurasi worker yang rapi di Git dan visibilitas atas apa yang terjadi di antrean. Mulai dari yang mendasar — pastikan queue memakai Redis, isi tries, timeout, dan backoff dengan sadar, kunci gate dashboard, jadwalkan horizon:snapshot, baru setelah itu mainkan strategi balancing. Jangan lupa horizon:terminate di langkah deploy; satu baris itu menyelamatkan banyak jam debugging.

Referensi resmi: Dokumentasi Laravel Horizon, repositori laravel/horizon, dan halaman paket di Packagist.

Exit mobile version