Laravel Horizon

• Introducción
• Instalación
  • Configuración
  • Estrategias de balanceo
  • Autorización del panel
  • Trabajos silenciados
• Actualizando Horizon
• Ejecutando Horizon
  • Desplegando Horizon
• Etiquetas
• Notificaciones
• Métricas
• Eliminando trabajos fallidos
• Limpiando trabajos de las colas

#Introducción

Laravel Horizon proporciona un panel hermoso y una configuración basada en código para sus colas Redis impulsadas por Laravel. Horizon le permite monitorear fácilmente métricas clave de su sistema de colas, como el rendimiento de trabajos, tiempo de ejecución y fallos de trabajos.

Al usar Horizon, toda la configuración de sus workers de cola se almacena en un solo archivo de configuración simple. Al definir la configuración de los workers de su aplicación en un archivo controlado por versiones, puede escalar o modificar fácilmente los workers de cola al desplegar su aplicación.

#Instalación

Puede instalar Horizon en su proyecto usando el gestor de paquetes Composer:

composer require laravel/horizon

Después de instalar Horizon, publique sus assets usando el comando Artisan horizon:install:

php artisan horizon:install

#Configuración

Después de publicar los assets de Horizon, su archivo principal de configuración estará ubicado en config/horizon.php. Este archivo le permite configurar las opciones de los workers de cola para su aplicación. Cada opción de configuración incluye una descripción de su propósito, así que asegúrese de explorar este archivo a fondo.

#Entornos

Después de la instalación, la opción principal de configuración de Horizon con la que debería familiarizarse es la opción environments. Esta opción es un arreglo de entornos en los que su aplicación se ejecuta y define las opciones de procesos worker para cada entorno. Por defecto, esta entrada contiene un entorno production y otro local. Sin embargo, puede agregar más entornos según sea necesario:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            'maxProcesses' => 3,
        ],
    ],
],

Cuando inicia Horizon, usará las opciones de configuración de procesos worker para el entorno en el que se está ejecutando su aplicación. Normalmente, el entorno se determina por el valor de la variable de entorno APP_ENV (environment variable). Por ejemplo, el entorno local predeterminado de Horizon está configurado para iniciar tres procesos worker y balancear automáticamente el número de procesos asignados a cada cola. El entorno production predeterminado está configurado para iniciar un máximo de 10 procesos worker y balancear automáticamente el número de procesos asignados a cada cola.

#Supervisores

Como puede ver en el archivo de configuración predeterminado de Horizon, cada entorno puede contener uno o más "supervisores". Por defecto, el archivo de configuración define este supervisor como supervisor-1; sin embargo, puede nombrar sus supervisores como desee. Cada supervisor es responsable de "supervisar" un grupo de procesos worker y se encarga de balancear los procesos worker entre las colas.

Puede agregar supervisores adicionales a un entorno dado si desea definir un nuevo grupo de procesos worker que se ejecutarán en ese entorno. Esto puede ser útil si desea definir una estrategia de balanceo diferente o un conteo distinto de procesos worker para una cola específica usada por su aplicación.

#Modo de mantenimiento

Mientras su aplicación esté en modo de mantenimiento, los trabajos en cola no serán procesados por Horizon a menos que la opción force del supervisor esté definida como true en el archivo de configuración de Horizon:

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

#Valores predeterminados

En el archivo de configuración predeterminado de Horizon, notará una opción defaults. Esta opción especifica los valores predeterminados para los supervisores de su aplicación. Los valores predeterminados del supervisor se fusionarán con la configuración del supervisor para cada entorno, permitiéndole evitar repeticiones innecesarias al definir sus supervisores.

#Estrategias de balanceo

A diferencia del sistema de colas predeterminado de Laravel, Horizon le permite elegir entre tres estrategias de balanceo de workers: simple, auto y false. La estrategia simple divide los trabajos entrantes de manera uniforme entre los procesos worker:

'balance' => 'simple',

La estrategia auto, que es la predeterminada en el archivo de configuración, ajusta el número de procesos worker por cola según la carga actual de la cola. Por ejemplo, si su cola notifications tiene 1,000 trabajos pendientes mientras que su cola render está vacía, Horizon asignará más workers a la cola notifications hasta que esta esté vacía.

Al usar la estrategia auto, puede definir las opciones de configuración minProcesses y maxProcesses para controlar el número mínimo y máximo de procesos worker a los que Horizon debe escalar:

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

El valor de configuración autoScalingStrategy determina si Horizon asignará más procesos worker a las colas basándose en el tiempo total que tomará limpiar la cola (estrategia time) o en el número total de trabajos en la cola (estrategia size).

Los valores de configuración balanceMaxShift y balanceCooldown determinan qué tan rápido Horizon escalará para satisfacer la demanda de workers. En el ejemplo anterior, se creará o destruirá un máximo de un proceso nuevo cada tres segundos. Puede ajustar estos valores según las necesidades de su aplicación.

Cuando la opción balance está configurada como false, se usará el comportamiento predeterminado de Laravel, donde las colas se procesan en el orden en que están listadas en su configuración.

#Autorización del panel

El panel de Horizon puede accederse a través de la ruta /horizon. Por defecto, solo podrá acceder a este panel en el entorno local. Sin embargo, dentro del archivo app/Providers/HorizonServiceProvider.php hay una definición de authorization gate. Esta puerta de autorización controla el acceso a Horizon en entornos no locales. Puede modificar esta puerta según sea necesario para restringir el acceso a su instalación de Horizon:

/**
 * Registrar la puerta de Horizon.
 *
 * Esta puerta determina quién puede acceder a Horizon en entornos no locales.
 */
protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

#Estrategias alternativas de autenticación

Recuerde que Laravel inyecta automáticamente el usuario autenticado en el cierre de la puerta. Si su aplicación proporciona seguridad para Horizon mediante otro método, como restricciones por IP, entonces sus usuarios de Horizon pueden no necesitar "iniciar sesión". Por lo tanto, deberá cambiar la firma del cierre function (User $user) arriba a function (User $user = null) para forzar que Laravel no requiera autenticación.

#Trabajos silenciados

A veces, puede que no le interese ver ciertos trabajos despachados por su aplicación o paquetes de terceros. En lugar de que estos trabajos ocupen espacio en su lista de "Trabajos completados", puede silenciarlos. Para comenzar, agregue el nombre de la clase del trabajo a la opción de configuración silenced en el archivo de configuración horizon de su aplicación:

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

Alternativamente, el trabajo que desea silenciar puede implementar la interfaz Laravel\Horizon\Contracts\Silenced. Si un trabajo implementa esta interfaz, se silenciará automáticamente, incluso si no está presente en el arreglo de configuración silenced:

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    // ...
}

#Actualizando Horizon

Al actualizar a una nueva versión mayor de Horizon, es importante que revise cuidadosamente la guía de actualización. Además, al actualizar a cualquier nueva versión de Horizon, debe volver a publicar los assets de Horizon:

php artisan horizon:publish

Para mantener los assets actualizados y evitar problemas en futuras actualizaciones, puede agregar el comando vendor:publish --tag=laravel-assets a los scripts post-update-cmd en el archivo composer.json de su aplicación:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

#Ejecutando Horizon

Una vez que haya configurado sus supervisores y workers en el archivo de configuración config/horizon.php de su aplicación, puede iniciar Horizon usando el comando Artisan horizon. Este único comando iniciará todos los procesos worker configurados para el entorno actual:

php artisan horizon

Puede pausar el proceso de Horizon e indicarle que continúe procesando trabajos usando los comandos Artisan horizon:pause y horizon:continue:

php artisan horizon:pause

php artisan horizon:continue

También puede pausar y reanudar supervisores específicos de Horizon usando los comandos Artisan horizon:pause-supervisor y horizon:continue-supervisor:

php artisan horizon:pause-supervisor supervisor-1

php artisan horizon:continue-supervisor supervisor-1

Puede verificar el estado actual del proceso Horizon usando el comando Artisan horizon:status:

php artisan horizon:status

Puede terminar el proceso Horizon de forma ordenada usando el comando Artisan horizon:terminate. Cualquier trabajo que esté siendo procesado se completará y luego Horizon dejará de ejecutarse:

php artisan horizon:terminate

#Desplegando Horizon

Cuando esté listo para desplegar Horizon en el servidor real de su aplicación, debe configurar un monitor de procesos para supervisar el comando php artisan horizon y reiniciarlo si se detiene inesperadamente. No se preocupe, a continuación explicaremos cómo instalar un monitor de procesos.

Durante el proceso de despliegue de su aplicación, debe indicar al proceso Horizon que termine para que sea reiniciado por su monitor de procesos y reciba los cambios de código:

php artisan horizon:terminate

#Instalando Supervisor

Supervisor es un monitor de procesos para el sistema operativo Linux y reiniciará automáticamente su proceso horizon si deja de ejecutarse. Para instalar Supervisor en Ubuntu, puede usar el siguiente comando. Si no usa Ubuntu, probablemente pueda instalar Supervisor usando el gestor de paquetes de su sistema operativo:

sudo apt-get install supervisor

#Configuración de Supervisor

Los archivos de configuración de Supervisor normalmente se almacenan en el directorio /etc/supervisor/conf.d de su servidor. Dentro de este directorio, puede crear cualquier cantidad de archivos de configuración que indiquen a Supervisor cómo debe monitorear sus procesos. Por ejemplo, vamos a crear un archivo horizon.conf que inicie y supervise un proceso horizon:

[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

Al definir su configuración de Supervisor, debe asegurarse de que el valor de stopwaitsecs sea mayor que el número de segundos que consume su trabajo de mayor duración. De lo contrario, Supervisor podría matar el trabajo antes de que termine de procesarse.

#Iniciando Supervisor

Una vez creado el archivo de configuración, puede actualizar la configuración de Supervisor e iniciar los procesos monitoreados usando los siguientes comandos:

sudo supervisorctl reread

sudo supervisorctl update

sudo supervisorctl start horizon

#Etiquetas

Horizon le permite asignar “etiquetas” a trabajos, incluyendo mailables, eventos broadcast, notificaciones y listeners de eventos en cola. De hecho, Horizon etiquetará de forma inteligente y automática la mayoría de los trabajos según los modelos Eloquent que estén adjuntos al trabajo. Por ejemplo, observe el siguiente trabajo:

<?php

namespace App\Jobs;

use App\Models\Video;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class RenderVideo implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Crear una nueva instancia del trabajo.
     */
    public function __construct(
        public Video $video,
    ) {}

    /**
     * Ejecutar el trabajo.
     */
    public function handle(): void
    {
        // ...
    }
}

Si este trabajo se pone en cola con una instancia App\Models\Video que tiene un atributo id con valor 1, recibirá automáticamente la etiqueta App\Models\Video:1. Esto se debe a que Horizon buscará en las propiedades del trabajo cualquier modelo Eloquent. Si encuentra modelos Eloquent, Horizon etiquetará inteligentemente el trabajo usando el nombre de la clase del modelo y su clave primaria:

use App\Jobs\RenderVideo;
use App\Models\Video;

$video = Video::find(1);

RenderVideo::dispatch($video);

#Etiquetado manual de trabajos

Si desea definir manualmente las etiquetas para uno de sus objetos en cola, puede definir un método tags en la clase:

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

#Etiquetado manual de listeners de eventos

Al obtener las etiquetas para un listener de eventos en cola, Horizon pasará automáticamente la instancia del evento al método tags, permitiéndole agregar datos del evento a las etiquetas:

class SendRenderNotifications implements ShouldQueue
{
    /**
     * Obtener las etiquetas que deben asignarse al listener.
     *
     * @return array<int, string>
     */
    public function tags(VideoRendered $event): array
    {
        return ['video:'.$event->video->id];
    }
}

#Notificaciones

Si desea ser notificado cuando una de sus colas tenga un tiempo de espera prolongado, puede usar los métodos Horizon::routeMailNotificationsTo, Horizon::routeSlackNotificationsTo y Horizon::routeSmsNotificationsTo. Puede llamar a estos métodos desde el método boot del App\Providers\HorizonServiceProvider de su aplicación:

/**
 * Inicializar cualquier servicio de la aplicación.
 */
public function boot(): void
{
    parent::boot();

    Horizon::routeSmsNotificationsTo('15556667777');
    Horizon::routeMailNotificationsTo('example@example.com');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
}

#Configurando umbrales de tiempo de espera para notificaciones

Puede configurar cuántos segundos se consideran un "tiempo de espera prolongado" dentro del archivo de configuración config/horizon.php de su aplicación. La opción de configuración waits dentro de este archivo le permite controlar el umbral de tiempo de espera prolongado para cada combinación conexión / cola. Cualquier combinación conexión / cola no definida usará un umbral de espera prolongada de 60 segundos por defecto:

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

#Métricas

Horizon incluye un panel de métricas que proporciona información sobre los tiempos de espera y rendimiento de sus trabajos y colas. Para poblar este panel, debe configurar el comando Artisan snapshot de Horizon para que se ejecute cada cinco minutos mediante el scheduler de su aplicación:

/**
 * Definir el cronograma de comandos de la aplicación.
 */
protected function schedule(Schedule $schedule): void
{
    $schedule->command('horizon:snapshot')->everyFiveMinutes();
}

#Eliminando trabajos fallidos

Si desea eliminar un trabajo fallido, puede usar el comando horizon:forget. El comando horizon:forget acepta el ID o UUID del trabajo fallido como su único argumento:

php artisan horizon:forget 5

#Limpiando trabajos de las colas

Si desea eliminar todos los trabajos de la cola predeterminada de su aplicación, puede hacerlo usando el comando Artisan horizon:clear:

php artisan horizon:clear

Puede proporcionar la opción queue para eliminar trabajos de una cola específica:

php artisan horizon:clear --queue=emails