Налаштування 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 показує: активні завдання, ті, що очікують, завершені, упалі. З упалих завдань можна вручну запустити повтор.

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

Або написати кастомний endpoint:

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 годин.