Настройка Background Job мониторинга (Sidekiq Dashboard / Bull Board / Flower)

Настройка Background Job мониторинга (Sidekiq Dashboard / Bull Board / Flower)

Очередь без мониторинга — это чёрный ящик. Задачи зависли, упали, накопились тысячами — узнаёшь об этом от пользователей. Дашборд очереди решает проблему: видно состояние каждой задачи, количество неудачных попыток, время ожидания в очереди.

Laravel Horizon

Для Laravel + Redis-очередей — стандартный инструмент. Устанавливается как пакет, предоставляет веб-интерфейс, API метрик и тонкую настройку пулов воркеров.

composer require laravel/horizon
php artisan horizon:install
php artisan migrate

Конфигурация воркеров в config/horizon.php:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue'      => ['high', 'default', 'low'],
            'balance'    => 'auto',
            'minProcesses' => 2,
            'maxProcesses' => 10,
            'tries'      => 3,
            'timeout'    => 60,
        ],
        'supervisor-media' => [
            'connection' => 'redis',
            'queue'      => ['media', 'transcoding'],
            'balance'    => 'simple',
            'processes'  => 2,
            'timeout'    => 3600,
        ],
    ],
],

balance: auto — Horizon автоматически масштабирует количество процессов в зависимости от глубины очереди.

Запуск Horizon:

php artisan horizon

В production через Supervisor:

[program:horizon]
command=php /var/www/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/horizon.log

Дашборд доступен по /horizon. По умолчанию только в локальном окружении. Для production — настраиваем HorizonServiceProvider::gate():

// app/Providers/HorizonServiceProvider.php
protected function gate(): void
{
    Gate::define('viewHorizon', function ($user) {
        return in_array($user->email, config('horizon.admin_emails', []));
    });
}

Метрики из Horizon через API — для интеграции с внешним мониторингом:

curl https://yoursite.com/horizon/api/stats \
  -H "Cookie: laravel_session=..."

Bull Board (Node.js / BullMQ)

Если бэкенд на Node.js с BullMQ или Bull:

npm install @bull-board/express @bull-board/api bullmq

import { createBullBoard } from '@bull-board/api';
import { BullMQAdapter }    from '@bull-board/api/bullMQAdapter';
import { ExpressAdapter }   from '@bull-board/express';
import { Queue }            from 'bullmq';
import express              from 'express';

const emailQueue  = new Queue('email',  { connection: { host: 'localhost', port: 6379 } });
const mediaQueue  = new Queue('media',  { connection: { host: 'localhost', port: 6379 } });
const reportQueue = new Queue('reports',{ connection: { host: 'localhost', port: 6379 } });

const serverAdapter = new ExpressAdapter();
serverAdapter.setBasePath('/admin/queues');

createBullBoard({
    queues: [
        new BullMQAdapter(emailQueue),
        new BullMQAdapter(mediaQueue),
        new BullMQAdapter(reportQueue),
    ],
    serverAdapter,
});

const app = express();

// Middleware авторизации перед дашбордом
app.use('/admin/queues', (req, res, next) => {
    const token = req.headers['x-admin-token'];
    if (token !== process.env.ADMIN_TOKEN) {
        return res.status(403).json({ error: 'Forbidden' });
    }
    next();
}, serverAdapter.getRouter());

app.listen(3000);

Bull Board показывает: активные задачи, ожидающие, завершённые, упавшие (failed). Из failed-задач можно вручную запустить повтор.

Flower (Celery / Python)

Для Python-стека с Celery:

pip install flower
celery -A myapp flower --port=5555 --basic_auth=admin:secretpass

Или через Docker:

# docker-compose.yml
flower:
  image: mher/flower:2.0
  command: celery --broker=redis://redis:6379/0 flower --port=5555
  environment:
    - FLOWER_BASIC_AUTH=admin:secretpass
    - FLOWER_URL_PREFIX=/flower
  ports:
    - "5555:5555"
  depends_on:
    - redis

Flower предоставляет REST API для автоматизации:

# Статус всех воркеров
curl http://localhost:5555/api/workers

# Задачи в очереди
curl http://localhost:5555/api/tasks

# Отменить задачу
curl -X POST http://localhost:5555/api/task/revoke/{task_id}?terminate=true

Алертинг при накоплении очереди

Horizon — настройка уведомлений при превышении пороговых значений:

// config/horizon.php
'waits' => [
    'redis:default'    => 60,   // алерт если задача ждёт > 60 сек
    'redis:high'       => 10,
    'redis:transcoding'=> 300,
],

Кастомная интеграция с Telegram/Slack — через слушатель событий Horizon:

// app/Providers/EventServiceProvider.php
use Laravel\Horizon\Events\LongWaitDetected;

protected $listen = [
    LongWaitDetected::class => [
        \App\Listeners\NotifyOnLongQueueWait::class,
    ],
];

// app/Listeners/NotifyOnLongQueueWait.php
class NotifyOnLongQueueWait
{
    public function handle(LongWaitDetected $event): void
    {
        $message = "Queue alert: `{$event->queue}` wait time {$event->wait}s exceeds threshold";
        Http::post(config('services.telegram.webhook_url'), [
            'chat_id' => config('services.telegram.admin_chat_id'),
            'text'    => $message,
            'parse_mode' => 'Markdown',
        ]);
    }
}

Метрики для Prometheus / Grafana

Если используется Prometheus-стек, Laravel Horizon экспортирует метрики через пакет spatie/laravel-prometheus:

composer require spatie/laravel-prometheus

Или написать кастомный эндпоинт:

Route::get('/metrics', function () {
    $stats   = app(\Laravel\Horizon\Contracts\MetricsRepository::class);
    $output  = "# HELP horizon_queue_size Queue depth\n";
    $output .= "# TYPE horizon_queue_size gauge\n";

    foreach (['default', 'high', 'low', 'media'] as $queue) {
        $size    = \Illuminate\Support\Facades\Redis::llen("queues:{$queue}");
        $output .= "horizon_queue_size{queue=\"{$queue}\"} {$size}\n";
    }

    return response($output, 200, ['Content-Type' => 'text/plain']);
})->middleware('throttle:60,1');

Сроки

Установка Horizon/Bull Board/Flower, базовая конфигурация пулов воркеров — 3–4 часа. Настройка авторизации дашборда, алертинг в Slack/Telegram — ещё 2–3 часа. Интеграция с Prometheus/Grafana — отдельно, 4–6 часов.