Laravel Horizon: удобный мониторинг очередей в Laravel

Очереди в Laravel давно стали стандартом для обработки тяжелых задач: отправки email, генерации изображений, импорта данных, уведомлений и работы с AI. Но когда задач становится много, появляется другая проблема - как контролировать их выполнение.

Именно для этого в Laravel существует Laravel Horizon - официальный инструмент для мониторинга и управления очередями на базе Redis.

Что такое Laravel Horizon

Laravel Horizon - это панель мониторинга очередей для Laravel, которая показывает:

• активные Jobs,

• failed Jobs,

• скорость обработки,

• нагрузку на очереди,

• статистику воркеров,

• время выполнения задач.

По сути, Horizon превращает работу с очередями в полноценную систему мониторинга.

Установка Laravel Horizon

Сначала понадобится Redis.

Устанавливаем пакет через Composer:

composer require laravel/horizon

После установки публикуем конфигурацию:

php artisan horizon:install

Теперь запускаем миграции:

php artisan migrate

Запуск Horizon

Для запуска используется команда:

php artisan horizon

После запуска панель будет доступна по адресу:

/horizon

Настройка Redis

В .env обычно указывают:

QUEUE_CONNECTION=redis

Laravel Horizon работает именно через Redis, поэтому database-драйвер не подойдет.

Создаем первую очередь

Например, Job для отправки email.

Создаем Job:

php artisan make:job SendWelcomeEmail

Пример Job:

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        sleep(3);

        logger('Email отправлен');
    }
}

Отправляем задачу в очередь:

SendWelcomeEmail::dispatch();

После этого задача появится в Horizon.

Основные возможности Horizon

Мониторинг задач

В панели можно увидеть:

• pending jobs,

• completed jobs,

• failed jobs,

• время выполнения,

• нагрузку на Redis.

Это особенно полезно на проектах с большим количеством очередей.

Failed Jobs

Если задача упала с ошибкой, Horizon покажет:

• stack trace,

• exception,

• время ошибки,

• payload задачи.

Это сильно упрощает отладку.

Повторные попытки задач

Laravel Horizon поддерживает retries.

Пример:

public int $tries = 3;

Laravel попробует выполнить задачу три раза.

Можно добавить задержку:

public int $backoff = 10;

Новая попытка произойдет через 10 секунд.

Настройка Supervisor

Основная конфигурация находится в:

config/horizon.php

Пример:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'auto',
            'processes' => 10,
            'tries' => 3,
        ],
    ],
],

Автоматическое масштабирование

Одна из сильных сторон Horizon - автоматическое распределение нагрузки.

Параметр:

'balance' => 'auto'

позволяет Horizon автоматически увеличивать количество воркеров при росте очереди.

Horizon и Docker

Если Laravel работает в Docker, Horizon обычно запускают отдельным контейнером:

  horizon:
  build: .
  command: php artisan horizon

Это позволяет изолировать обработку очередей от основного приложения.

Horizon для AI и тяжелых задач

Сейчас Horizon особенно полезен в проектах с AI:

• генерация текста,

• обработка изображений,

• AI-очереди,

• Telegram-боты,

• импорт больших файлов,

• webhook-системы.

Без очередей такие операции начинают тормозить сайт.

Оптимизация Horizon

Несколько полезных советов:

Используйте отдельные очереди

Например:

SendEmailJob::dispatch()->onQueue('emails');

или:

GenerateImageJob::dispatch()->onQueue('images');

Не держите тяжелые задачи в default

Лучше разделять:

• emails,

• notifications,

• ai,

• exports,

• webhooks.

Ограничивайте время выполнения

Например:

public int $timeout = 120;

Команды Horizon

Запуск:

php artisan horizon

Остановка:

php artisan horizon:terminate

Статус:

php artisan horizon:status

Horizon vs обычный queue:work

Обычный воркер:

php artisan queue:work

подходит для небольших проектов.

Но Horizon дает:

• UI мониторинга,

• балансировку,

• статистику,

• автоматическое масштабирование,

• удобную диагностику ошибок.

Итог

Laravel Horizon - один из самых полезных инструментов экосистемы Laravel для работы с очередями. Он особенно важен для современных проектов с AI, webhook-системами, email-рассылками и тяжелыми фоновыми задачами.

Если проект начинает активно использовать очереди, Horizon быстро становится практически обязательным инструментом для мониторинга и стабильной работы приложения.