Laravel Horizon - Knowledge of Laravel

Cos’è Horizon

Laravel Horizon è una dashboard di monitoraggio dedicata alle code Redis di Laravel. Visualizza in tempo reale throughput, tempi di esecuzione e job falliti, e gestisce la configurazione dei worker come codice.

Horizon è un pacchetto che estende le funzionalità di base delle code. Prima leggi le basi di Code e job. Come backend è sempre necessario Redis.

Installazione

Horizon usa Redis come backend delle code. Verifica che in config/queue.php QUEUE_CONNECTION sia impostato su redis. Al momento non è supportato Redis Cluster.

Installa via Composer.

composer require laravel/horizon

Dopo l’installazione, pubblica asset e file di configurazione.

php artisan horizon:install

Il comando genera config/horizon.php e app/Providers/HorizonServiceProvider.php.

Configurazione

Struttura di config/horizon.php

config/horizon.php gestisce tutta la configurazione dei worker. L’opzione centrale è environments.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 60,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            // gli altri valori sono ereditati dalla sezione defaults
            'maxProcesses' => 3,
        ],
    ],
],

Internamente Horizon usa una connessione Redis chiamata horizon. Non usare questo nome per altre connessioni in config/database.php.

CSP nonce (Content Security Policy)

Se, come parte della tua Content Security Policy, vuoi impostare un attributo nonce sui tag script / style delle view di Horizon, usa Horizon::cspNonce. Poiché per ogni richiesta va assegnato un nuovo nonce, di solito lo chiami all’interno di un middleware.

use Closure;
use Illuminate\Http\Request;
use Laravel\Horizon\Horizon;
use Symfony\Component\HttpFoundation\Response;

public function handle(Request $request, Closure $next): Response
{
    Horizon::cspNonce('csp-nonce');

    return $next($request);
}

Aggiungi questo middleware all’opzione middleware di config/horizon.php.

'middleware' => [
    'web',
    App\Http\Middleware\AddHorizonCspNonce::class,
],

Supervisor

Ogni ambiente può avere uno o più “supervisor”. Un supervisor è l’unità di gestione di un gruppo di worker e in uno stesso ambiente possono coesistere più supervisor con code, strategie di bilanciamento e numeri di processi diversi.

Valori di default

Con l’opzione defaults puoi impostare valori applicati a tutti i supervisor.

'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'tries' => 1,
        'timeout' => 60,
        'maxProcesses' => 1,
    ],
],

Modalità manutenzione

Quando l’applicazione è in modalità manutenzione, Horizon di default non processa job. Per forzare l’elaborazione usa l’opzione force.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'force' => true,
        ],
    ],
],

Numero massimo di tentativi

'environments' => [
    'production' => [
        'supervisor-1' => [
            'tries' => 10,
        ],
    ],
],

Impostando tries a 0 consenti retry illimitati.

Timeout dei job

'environments' => [
    'production' => [
        'supervisor-1' => [
            'timeout' => 60,
        ],
    ],
],

Imposta timeout a qualche secondo in meno rispetto a retry_after di config/queue.php. Inoltre, con la strategia di balancing auto, i job più lunghi di questo valore possono essere forzatamente terminati.

Backoff (attesa prima del retry)

Indica i secondi da attendere prima di un nuovo tentativo dopo un’eccezione.

// valore fisso
'backoff' => 10,

// progressivo (backoff esponenziale)
'backoff' => [1, 5, 10],

Altre opzioni dei worker

Oltre a tries, timeout e backoff, ogni supervisor accetta opzioni per controllare il comportamento dei worker e il momento del riavvio automatico. Riavviare periodicamente i processi long-running è una buona prassi per prevenire memory leak.

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'memory' => 128,
            'maxJobs' => 1000,
            'maxTime' => 3600,
            'sleep' => 3,
            'rest' => 0,
            'nice' => 0,
        ],
    ],
],

memory — memoria massima (MB) che un worker può consumare prima del riavvio. Default 128.
maxJobs — numero di job processati prima del riavvio. 0 significa illimitato. Default 0.
maxTime — secondi di attività di un worker prima del riavvio. 0 disabilita il riavvio a tempo. Default 0.
sleep — secondi di attesa tra un polling e il successivo quando non ci sono job. Default 3.
rest — secondi di pausa tra l’elaborazione di un job e il successivo. Default 0.
nice — priorità (“niceness”) del processo. Valori più alti significano priorità più bassa. Default 0.

Strategie di bilanciamento

Horizon offre tre strategie di bilanciamento dei worker.

auto (default)

Adegua automaticamente il numero di worker in base al carico della coda. L’intervallo si imposta con minProcesses e maxProcesses.

'supervisor-1' => [
    'balance' => 'auto',
    'autoScalingStrategy' => 'time', // oppure 'size'
    'minProcesses' => 1,
    'maxProcesses' => 10,
    'balanceMaxShift' => 1,
    'balanceCooldown' => 3,
],

time — scaling in base al tempo stimato per svuotare la coda
size — scaling in base al numero di job in coda

Con la strategia auto l’ordine delle code non indica la priorità. Se ti serve forzare la priorità, usa più supervisor.

simple

Fissa il numero di worker e li distribuisce uniformemente sulle code indicate.

'supervisor-1' => [
    'balance' => 'simple',
    'processes' => 10,
    'queue' => ['default', 'notifications'],
],

Nell’esempio, 5 processi vengono assegnati a default e 5 a notifications.

false (nessun bilanciamento)

Rispetta rigorosamente l’ordine di priorità delle code elencate. Comportamento identico al sistema di code di Laravel di default, ma con scaling del numero di worker in base agli arretrati.

'supervisor-1' => [
    'balance' => false,
    'queue' => ['default', 'notifications'],
    'minProcesses' => 1,
    'maxProcesses' => 10,
],

I job della coda default vengono sempre processati prima di quelli di notifications.

Autorizzazione della dashboard

La dashboard di Horizon è accessibile alla route /horizon. In locale è aperta a tutti; in produzione limita l’accesso con una gate. Modifica il metodo gate() in app/Providers/HorizonServiceProvider.php.

use App\Models\User;
use Illuminate\Support\Facades\Gate;

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

Se non usi l’autenticazione (proteggendo per IP ecc.), rendi opzionale l’argomento.

Gate::define('viewHorizon', function (User $user = null) {
    // se protetto tramite IP ecc.
    return true;
});

Avvio di Horizon

Comandi principali

# avvio
php artisan horizon

# pausa / ripresa
php artisan horizon:pause
php artisan horizon:continue

# pausa / ripresa di un supervisor specifico
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# stato
php artisan horizon:status
php artisan horizon:supervisor-status supervisor-1

# shutdown graceful
php artisan horizon:terminate

Sviluppo locale: riavvio automatico

Per riavviare Horizon automaticamente al variare dei file usa horizon:listen.

npm install --save-dev chokidar
php artisan horizon:listen

# in ambienti Docker / Vagrant
php artisan horizon:listen --poll

Sempre attivo con Supervisor

In produzione mantieni Horizon sempre attivo con Supervisor.

Installazione di Supervisor

sudo apt-get install supervisor

File di configurazione

Crea /etc/supervisor/conf.d/horizon.conf.

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600

Imposta stopwaitsecs a un valore maggiore della durata del job più lungo. Se è troppo basso, Supervisor terminerà forzatamente i job in corso.

Avvio di Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

Al deploy

Ad ogni deploy, riavvia Horizon per applicare le modifiche.

php artisan horizon:terminate

Se Supervisor ha autostart=true / autorestart=true, Horizon verrà riavviato automaticamente dopo la terminazione.

Gestione dei job

Tag

Horizon rileva automaticamente i modelli Eloquent legati ai job e aggiunge tag.

// job che riceve Video (id=1) → tag automatico "App\Models\Video:1"
RenderVideo::dispatch(Video::find(1));

Per tag manuali, implementa il metodo tags().

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

Per gli event listener, l’istanza dell’evento viene passata al metodo tags().

class SendRenderNotifications implements ShouldQueue
{
    public function tags(VideoRendered $event): array
    {
        return ['video:'.$event->video->id];
    }
}

Silenziare i job

I job che non vuoi vedere nella lista “job completati” della dashboard si silenziano da config/horizon.php.

'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

// silenziamento per tag
'silenced_tags' => [
    'notifications',
],

In alternativa puoi implementare l’interfaccia Silenced.

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;
    // ...
}

Metriche e monitoring

La dashboard delle metriche di Horizon mostra throughput e tempi di esecuzione di job e code. Per registrare periodicamente uno snapshot, imposta uno schedule.

// routes/console.php
use Illuminate\Support\Facades\Schedule;

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

L’opzione metrics.trim_snapshots di config/horizon.php imposta quanti snapshot conservare per i grafici delle metriche. Poiché la retention è espressa in numero e non in tempo, il periodo effettivo dipende dalla frequenza di horizon:snapshot.

'metrics' => [
    'trim_snapshots' => [
        'job' => 24,
        'queue' => 24,
    ],
],

Per eliminare tutte le metriche:

php artisan horizon:clear-metrics

Notifiche di fallimento job

Puoi essere notificato quando i tempi di attesa in coda si allungano. Configura nel metodo boot() di app/Providers/HorizonServiceProvider.php.

use Laravel\Horizon\Horizon;

public function boot(): void
{
    parent::boot();

    Horizon::routeMailNotificationsTo('[email protected]');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#ops');
    Horizon::routeSmsNotificationsTo('15556667777');
}

Soglie di attesa

L’opzione waits di config/horizon.php imposta la soglia (in secondi) che attiva la notifica.

'waits' => [
    'redis:critical' => 30,  // notifica dopo 30s di attesa
    'redis:default' => 60,
    'redis:batch' => 120,
],

Impostando 0 disabiliti le notifiche per quella coda.

Gestione dei job falliti

Puoi eliminare i job falliti per ID o UUID.

# elimina un job fallito specifico
php artisan horizon:forget 5

# elimina tutti i job falliti
php artisan horizon:forget --all

Per svuotare tutti i job di una coda:

# svuota la coda di default
php artisan horizon:clear

# svuota una coda specifica
php artisan horizon:clear --queue=emails

Upgrade

Ad ogni major di Horizon consulta sempre la guida di upgrade.

Pagine correlate

Code e job

Fondamenti delle code Laravel: creazione, dispatch, batch e gestione dei fallimenti.

Redis

Configurazione e uso di Redis, il backend richiesto da Horizon.

​Cos’è Horizon

​Installazione

​Configurazione

​Struttura di config/horizon.php

​CSP nonce (Content Security Policy)

​Supervisor

​Valori di default

​Modalità manutenzione

​Numero massimo di tentativi

​Timeout dei job

​Backoff (attesa prima del retry)

​Altre opzioni dei worker

​Strategie di bilanciamento

​Autorizzazione della dashboard

​Avvio di Horizon

​Comandi principali

​Sviluppo locale: riavvio automatico

​Sempre attivo con Supervisor

​Installazione di Supervisor

​File di configurazione

​Avvio di Supervisor

​Al deploy

​Gestione dei job

​Tag

​Silenziare i job

​Metriche e monitoring

​Notifiche di fallimento job

​Soglie di attesa

​Gestione dei job falliti

​Upgrade

​Pagine correlate

Code e job

Redis

Cos’è Horizon

Installazione

Configurazione

Struttura di config/horizon.php

CSP nonce (Content Security Policy)

Supervisor

Valori di default

Modalità manutenzione

Numero massimo di tentativi

Timeout dei job

Backoff (attesa prima del retry)

Altre opzioni dei worker

Strategie di bilanciamento

Autorizzazione della dashboard

Avvio di Horizon

Comandi principali

Sviluppo locale: riavvio automatico

Sempre attivo con Supervisor

Installazione di Supervisor

File di configurazione

Avvio di Supervisor

Al deploy

Gestione dei job

Tag

Silenziare i job

Metriche e monitoring

Notifiche di fallimento job

Soglie di attesa

Gestione dei job falliti

Upgrade

Pagine correlate