Tutorial Laravel Horizon: Monitoring Queue Secara Real-Time

Bayangkan kamu punya aplikasi Laravel yang sibuk memproses ribuan email, notifikasi, dan task background setiap hari. Tiba-tiba, ada job yang stuck, antrean menumpuk, atau worker tiba-tiba mati. Tanpa monitoring, kamu seperti pilot yang terbang tanpa radar. Di sinilah Laravel Horizon hadir sebagai solusi monitoring queue yang powerful dan user-friendly.

Laravel Horizon adalah dashboard real-time untuk memantau, mengelola, dan mengoptimalkan queue berbasis Redis di Laravel. Dengan Horizon, kamu bisa melihat status job, performa worker, retry, dan notifikasi—all in one place. Artikel ini akan membimbing kamu dari setup awal hingga best practices production.

Prerequisites dan Setup Environment

Sebelum mulai, pastikan environment kamu sudah siap:

Laravel 9+ (tutorial ini menggunakan Laravel 11)
Redis sudah terinstall dan running
PHP 8.1+
Composer
Queue driver di .env sudah di-set ke redis

QUEUE_CONNECTION=redis

Instalasi Laravel Horizon

Install package Horizon via Composer:

composer require laravel/horizon

Setelah install, publish asset dan konfigurasi:

php artisan horizon:install

Command ini akan membuat file config/horizon.php untuk konfigurasi supervisor, balancing, dan notifikasi.

Menjalankan Horizon dan Dashboard

Untuk menjalankan Horizon, cukup jalankan:

php artisan horizon

Dashboard Horizon bisa diakses di /horizon pada browser. Di sini kamu bisa melihat:

Status queue dan job
Worker dan supervisor
Metrics performa
Failed jobs dan retry
Real-time monitoring

Konfigurasi Supervisor dan Worker

Supervisor adalah process manager yang mengatur worker di Horizon. Contoh konfigurasi di config/horizon.php:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'emails'],
            'balance' => 'auto',
            'minProcesses' => 2,
            'maxProcesses' => 10,
            'tries' => 3,
        ],
    ],
    'local' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'simple',
            'maxProcesses' => 3,
        ],
    ],
],

balance: auto untuk scaling otomatis, simple untuk distribusi rata
minProcesses dan maxProcesses: jumlah worker minimum dan maksimum
tries: jumlah percobaan job sebelum dianggap gagal

Monitoring dan Notifikasi

Horizon mendukung notifikasi ke Slack, email, dan SMS untuk event penting seperti job gagal atau antrean terlalu lama. Contoh setup di App\Providers\HorizonServiceProvider:

public function boot(): void
{
    Horizon::routeMailNotificationsTo('[email protected]');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
    Horizon::routeSmsNotificationsTo('15556667777');
}

Kamu juga bisa mengatur threshold antrean lama di config/horizon.php:

'waits' => [
    'redis:critical' => 30,
    'redis:default' => 60,
],

Supervisor di Production

Agar Horizon tetap berjalan di server production, gunakan Supervisor (process monitor):

Install Supervisor di Ubuntu:

sudo apt-get install supervisor

Buat file /etc/supervisor/conf.d/horizon.conf:

[program:horizon]
process_name=%(program_name)s
command=php /path/to/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/path/to/horizon.log
stopwaitsecs=3600

Aktifkan supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

Manajemen dan Maintenance

Beberapa command penting untuk manajemen Horizon:

# Cek status Horizon
php artisan horizon:status

# Pause/continue seluruh Horizon
php artisan horizon:pause
php artisan horizon:continue

# Pause/continue supervisor tertentu
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# Terminate Horizon secara graceful
php artisan horizon:terminate

# Clear jobs dari queue
php artisan horizon:clear
php artisan horizon:clear --queue=emails

# Hapus failed jobs
php artisan horizon:forget --all
php artisan horizon:forget <job-id>

# Snapshot metrics untuk dashboard
php artisan horizon:snapshot

Authorization Dashboard

Untuk membatasi akses dashboard di production, definisikan gate di HorizonServiceProvider:

protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

Tagging dan Tracking Job

Horizon otomatis men-tag job berdasarkan model Eloquent yang dikirim ke queue. Kamu juga bisa menambahkan tag custom di job:

class RenderVideo implements ShouldQueue
{
    public function tags(): array
    {
        return ['render', 'video:' . $this->video->id];
    }
}

Best Practices dan Tips

Selalu gunakan Redis untuk queue di Horizon
Atur balancing dan scaling sesuai workload aplikasi
Aktifkan notifikasi untuk job gagal dan antrean panjang
Monitor dashboard secara rutin, terutama di jam sibuk
Gunakan tag untuk tracking job penting
Batasi akses dashboard di production
Lakukan snapshot metrics secara berkala
Pastikan Supervisor selalu running

Troubleshooting dan Maintenance

Jika worker stuck, gunakan horizon:terminate lalu restart supervisor
Cek log di file horizon.log untuk error detail
Clear antrean jika ada job corrupt dengan horizon:clear
Hapus failed jobs secara berkala
Update konfigurasi supervisor jika scaling berubah

Next Steps dan Eksplorasi Lanjutan

Setelah menguasai Horizon, kamu bisa explore fitur advanced seperti:

Auto scaling dengan strategi time-based
Custom notification channel
Integrasi dengan monitoring eksternal
Tagging dan batch management untuk job analytics
Konfigurasi balancing untuk multi-queue

Laravel Horizon adalah tool wajib untuk aplikasi yang mengandalkan queue dan background jobs. Dengan dashboard real-time, notifikasi, dan manajemen worker yang mudah, kamu bisa menjaga aplikasi tetap scalable, responsif, dan minim downtime.

Mulai implementasi Horizon di project kamu, dan rasakan bedanya monitoring queue yang profesional!