KAL
Menu

Horizon

Pemantauan antrian Redis beserta dashboard dan metriknya.

Daftar isi

Horizon adalah panel pemantauan dan pengatur antrian (queue) untuk aplikasi Laravel yang menggunakan driver Redis. Topik ini membahas kedudukan Horizon di samping worker antrian bawaan, kebutuhan yang terbaca dari metadata package, konfigurasi supervisor, serta dashboard dan metrik yang disediakan Horizon. Sebagai bagian dari peta ekosistem, pembahasan terbatas pada pemeriksaan metadata dan struktur konfigurasi, sedangkan instalasi lengkap menuntut server Redis.

Kedudukan Horizon di samping worker#

Driver antrian menentukan tempat job disimpan, sedangkan worker mengeksekusi job tersebut. Pada aplikasi catatan, worker dijalankan sebagai satu proses queue:work yang dipanggil secara manual. Horizon mengambil alih peran pengelolaan proses itu. Satu proses Horizon memunculkan dan mengawasi sekumpulan proses worker Redis sesuai konfigurasi, merestart proses yang berhenti, dan menyeimbangkan beban kerja antarproses. Horizon bukan driver antrian dan bukan pengganti antrian, melainkan lapisan pengelolaan dan pemantauan di atasnya.

Deskripsi resmi package ini menyebut dashboard dan code-driven configuration, yaitu konfigurasi yang dinyatakan sebagai kode. Jumlah proses worker, daftar antrian yang dilayani, dan strategi penyeimbangan dituliskan di berkas config/horizon.php, bukan sebagai deretan argumen command line yang panjang. Karena konfigurasinya berupa kode, perubahan pengaturan worker melewati alur yang sama dengan perubahan kode aplikasi lain, dari pemeriksaan hingga commit.

Kebutuhan yang terbaca dari metadata#

Sebelum sebuah package diadopsi, metadata-nya dapat diperiksa tanpa memasang apa pun. Perintah composer show dengan opsi --available membaca informasi package dari packagist.org, meliputi versi, lisensi, dan daftar dependensinya. Perintah berikut dijalankan dari direktori mana pun di luar proyek Composer, dan baris pertama keluarannya justru berupa pemberitahuan tentang hal itu.

bash 
# membaca metadata package horizon tanpa memasangnya
composer show laravel/horizon v5.50.1 --available
text Keluaran 
No composer.json found in the current directory, showing available packages from packagist.org
name     : laravel/horizon
descrip. : Dashboard and code-driven configuration for Laravel queues.
keywords : queue, laravel
versions : v5.50.1
type     : library
license  : MIT License (MIT) (OSI approved) https://spdx.org/licenses/MIT.html#licenseText
homepage : 
source   : [git] https://github.com/laravel/horizon.git 9d65cae809688179ce2c4ace64eb75e886e245c5
dist     : [zip] https://api.github.com/repos/laravel/horizon/zipball/9d65cae809688179ce2c4ace64eb75e886e245c5 9d65cae809688179ce2c4ace64eb75e886e245c5
names    : laravel/horizon

support
issues : https://github.com/laravel/horizon/issues
source : https://github.com/laravel/horizon/tree/v5.50.1

autoload
psr-4
Laravel\Horizon\ => src/

requires
php ^8.0
ext-json *
ext-pcntl *
ext-posix *
illuminate/contracts ^9.21|^10.0|^11.0|^12.0|^13.0
illuminate/queue ^9.21|^10.0|^11.0|^12.0|^13.0
illuminate/support ^9.21|^10.0|^11.0|^12.0|^13.0
laravel/sentinel ^1.0
nesbot/carbon ^2.17|^3.0
ramsey/uuid ^4.0
symfony/console ^6.0|^7.0|^8.0
symfony/error-handler ^6.0|^7.0|^8.0
symfony/polyfill-php83 ^1.28
symfony/process ^6.0|^7.0|^8.0

requires (dev)
mockery/mockery ^1.0
orchestra/testbench ^7.56|^8.37|^9.16|^10.9|^11.0
phpstan/phpstan ^1.10|^2.0
predis/predis ^1.1|^2.0|^3.0

suggests
ext-redis Required to use the Redis PHP driver.
predis/predis Required when not using the Redis PHP driver (^1.1|^2.0|^3.0).

Bagian requires dan suggests memuat tiga kelompok informasi yang menjelaskan cara kerja Horizon. Ekstensi ext-pcntl dan ext-posix adalah kebutuhan untuk mengendalikan proses, sesuai tugas Horizon untuk memunculkan dan mengawasi proses worker. Rentang illuminate/* yang mencantumkan ^13.0 menunjukkan bahwa versi v5.50.1 mendukung Laravel 13. Bagian suggests menyatakan pilihan driver Redis, yaitu ekstensi ext-redis apabila tersedia di server, atau package predis/predis apabila tidak.

Memasang dan mengonfigurasi supervisor#

Pemasangan Horizon terdiri atas dua langkah, yaitu mendaftarkan package melalui Composer dan menjalankan perintah penerbitan berkas konfigurasinya. Perintah horizon:install menerbitkan config/horizon.php sekaligus membuat HorizonServiceProvider di direktori app/Providers. Blok berikut tidak dieksekusi ulang pada contoh ini karena server Redis tidak tersedia di lingkungan pengembangan.

bash 
# tidak-dijalankan
# memasang Horizon lalu menerbitkan berkas konfigurasinya
cd ~/aplikasi-catatan
composer require laravel/horizon
php artisan horizon:install

Inti konfigurasi Horizon adalah daftar supervisor per lingkungan. Supervisor adalah kumpulan proses worker yang bernama dan berbagi pengaturan yang sama. Potongan berikut memperlihatkan konfigurasi sebuah supervisor bernama supervisor-1 pada lingkungan production.

php Contoh: potongan berkas config/horizon.php 
// tidak-dijalankan
'production' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'maxProcesses' => 10,
        'tries' => 1,
        'timeout' => 60,
        'memory' => 128,
    ],
],

Kunci connection menunjuk koneksi Redis pada config/queue.php, sedangkan queue menyatakan daftar antrian yang dilayani kumpulan worker ini. Kunci balance bernilai auto membuat Horizon memindahkan proses worker ke antrian yang lebih padat secara berkala, dan maxProcesses menetapkan batas atas jumlah proses worker. Kunci tries dan timeout berlaku sebagai nilai bawaan untuk job yang tidak menyatakan keduanya sendiri.

Dashboard, metrik, dan job yang gagal#

Supervisor beserta seluruh proses worker-nya dimulai dengan satu perintah.

bash 
# tidak-dijalankan
# menjalankan supervisor Horizon, proses berjalan terus
cd ~/aplikasi-catatan
php artisan horizon

Perintah tersebut berjalan terus dan tidak selesai sendiri, sehingga pada server produksi prosesnya diserahkan kepada pengelola proses seperti systemd. Selama Horizon berjalan, dashboard dapat dibuka pada rute /horizon. Dashboard menampilkan jumlah job per menit, waktu tunggu (wait time) job sebelum dieksekusi, laju pemrosesan (throughput) antrian, serta daftar job yang gagal beserta pengecualiannya. Seluruh metrik tersebut dihitung dari data yang tersimpan di Redis sendiri, sehingga dashboard hanya membaca data itu dan tidak mencatatnya ke media lain. Job yang gagal dapat diperiksa penyebabnya dan diulang langsung dari dashboard, sementara penandaan job dengan tag memungkinkan pencarian job milik satu model, misalnya App\Models\Note:42.

Akses ke dashboard dikendalikan oleh sebuah gate, yaitu aturan otorisasi Laravel yang bernama viewHorizon. Definisi gate tersebut berada pada metode gate() di HorizonServiceProvider, dan tanpa definisinya dashboard hanya terbuka pada lingkungan lokal.

php Contoh: gerbang akses dashboard di HorizonServiceProvider 
// tidak-dijalankan
protected function gate(): void
{
    Gate::define('viewHorizon', function ($user = null) {
        return in_array($user?->email, [
            '[email protected]',
        ]);
    });
}

Rangkaian hubungan antara aplikasi, Redis, supervisor, dan dashboard dirangkum pada diagram berikut.

Aplikasi Laraveldispatch jobRedisantrian + metrikDashboard /horizonstatistik antrianSupervisor Horizonkumpulan proses workerpush jobbaca metrikspawn worker, ambil job
Arsitektur Horizon dari dispatch hingga dashboard

Kesalahan umum#

Kesalahan pertama adalah memasang Horizon pada aplikasi yang driver antriannya masih database atau sync. Horizon akan berjalan tanpa memantau apa pun, karena media antrian yang dipantaunya hanyalah Redis. Pindahkan driver antrian ke redis dan pastikan koneksi Redis dapat dibuka sebelum menilai hasil pemasangan.

Kesalahan kedua adalah menjalankan php artisan horizon di lingkungan yang tidak memiliki ekstensi pcntl dan posix, misalnya PHP di Windows. Horizon gagal memunculkan proses worker karena keduanya adalah prasyarat pengelolaan proses yang terbaca pada metadata package. Lingkungan pengembangan Windows dapat menggunakan WSL agar ekstensi tersebut tersedia.

Kesalahan ketiga adalah membuka rute /horizon ke publik tanpa mengatur gate viewHorizon. Dashboard memperlihatkan isi antrian, payload job, dan job yang gagal, sehingga akses dashboard wajib dibatasi pada pengguna tertentu sebelum aplikasi berjalan di lingkungan produksi.

Ringkasan#

  • Horizon adalah lapisan pengelolaan dan pemantauan untuk antrian Redis, bukan driver antrian dan bukan pengganti worker.
  • Metadata package menyatakan kebutuhannya, yaitu ekstensi pcntl dan posix untuk mengendalikan proses serta driver Redis berupa ekstensi ext-redis atau package predis.
  • Konfigurasinya berupa kode: daftar supervisor di config/horizon.php menetapkan jumlah proses, antrian yang dilayani, dan strategi penyeimbangan auto.
  • Dashboard pada rute /horizon membaca metrik antrian dari Redis dan aksesnya dikendalikan oleh gate viewHorizon.

Referensi#

  • Horizon — Laravel — Dokumentasi resmi Horizon, mencakup pemasangan, konfigurasi supervisor, dashboard, dan tag.
  • Queues — Laravel — Dokumentasi antrian Laravel yang menjadi dasar driver Redis dan konsep worker pada topik ini.