Watchtower: комплексний моніторинг задач, черг та помилок у Laravel

Watchtower - це Laravel-пакет, який об'єднує моніторинг запланованих задач (scheduled tasks), черг, job'ів та винятків на єдиній панелі керування, призначеній для роботи в production-середовищі. Пакет надає не лише видимість процесів, а й можливість активних дій: запуск задачі за вимогою, масове повторення failed jobs, позначення помилок як вирішених.

Ключові можливості

Пакет підтримує будь-який драйвер черг - database, Redis або SQS - без жорсткої залежності від Redis. Watchtower враховує конфігурації з однією базою даних, кількома базами або multi-tenant архітектурою. Запис даних відбувається безпечно для production завдяки відкладеному запису, sampling та автоматичному pruning.

Доступ до панелі контролюється через gate-механізм у стилі Horizon та Telescope. Опціонально можна налаштувати сповіщення через Slack, webhook або email.

Три вкладки для фонових процесів

Панель розділена на три основні розділи:

Schedule

Вкладка Schedule відображає всі заплановані задачі з їхніми cron-виразами, записаними людською мовою. Тут можна побачити історію виконання, тривалість кожного запуску та виявлення пропущених запусків. Кнопка "Run now" дозволяє негайно запустити будь-яку задачу.

Queues & Jobs

Розділ Queues & Jobs показує live-метрики черг поруч з таблицею failed jobs. Ви можете повторити виконання окремого job'а або масово повторити всі job'и за типом винятку чи часовим проміжком.

Errors

Вкладка Errors групує винятки за типом та кількістю виникнень. Для кожного винятку доступні повні stack traces, контекст запиту та job'а, а також контроли для позначення помилки як вирішеної або повторного відкриття.

Усе це не прив'язане до конкретного драйвера: черги можуть працювати на database, Redis або SQS, а Watchtower читає дані з окремого підключення, коли додаток використовує кілька баз даних або tenants.

Безпека для production за замовчуванням

Запис активності на кожному request та job міг би стати навантаженням для застосунку, тому Watchtower відкладає запис даних до callback'а terminating() у Laravel, виносячи його за межі основного шляху запиту.

Додатки з високим трафіком можуть записувати лише частину активності, використовуючи sampling rate, при цьому всі збої та запуски schedule продовжують фіксуватися повністю. Усі збережені поля обрізаються для обмеження розміру рядків. Щоденна команда watchtower:prune очищає застарілі записи згідно з налаштованими періодами зберігання: 30 днів для schedule runs та exceptions, 7 днів для queue records за замовчуванням.

Більшість параметрів налаштовується через змінні оточення:

WATCHTOWER_ENABLED=true
WATCHTOWER_DB_CONNECTION=monitoring
WATCHTOWER_SAMPLING_RATE=0.25
WATCHTOWER_AFTER_RESPONSE=true
WATCHTOWER_RETAIN_EXCEPTIONS=30

Встановлення WATCHTOWER_ENABLED=false діє як аварійний вимикач, що миттєво зупиняє запис. Списки ігнорування для jobs, commands та exceptions дозволяють прибрати зайві елементи з панелі.

Авторизація

За замовчуванням панель доступна лише в local-середовищі. Для відкриття доступу в інших середовищах потрібно визначити gate viewWatchtower:

use Illuminate\Support\Facades\Gate;

Gate::define('viewWatchtower', function ($user) {
    return $user !== null && $user->isAdmin();
});

Альтернативно можна використати fluent callback, щоб тримати логіку авторизації разом з пакетом:

use Watchtower\Watchtower;

Watchtower::auth(fn ($request) => $request->user()?->isAdmin());

Неавторизовані запити отримують відповідь 403.

Опціональні сповіщення

Watchtower може сповіщати про збій запланованої задачі, пропущений запуск або перевищення порогу failed jobs (за замовчуванням 25 за 60 хвилин). Сповіщення вимкнені до встановлення WATCHTOWER_ALERTS_ENABLED=true і можуть надсилатися через Slack, generic webhook або email.

Перевірки виконуються командою watchtower:monitor, яку потрібно додати до розкладу:

$schedule->command('watchtower:monitor')->everyFiveMinutes();

Вимоги та ліцензія

Watchtower потребує PHP 8.2+ та Laravel 11 або 12. Пакет розповсюджується під ліцензією MIT. Вихідний код, довідку з конфігурації та інструкції з встановлення можна знайти на GitHub.