Відстежуйте Laravel Queues, Commands та Schedulers на будь-якому Driver за допомогою Vigilance

Vigilance — це панель моніторингу, яка відстежує роботу фонових процесів у production. Вона реєструє виконання Job, Artisan-команд та запланованих завдань на всіх етапах: від потрапляння в чергу до успішного завершення або помилки, фіксуючи параметри, коди виходу та Exception traces.

Головна перевага Vigilance — універсальність. На відміну від інших інструментів, він працює з будь-яким драйвером черг: database, Redis, SQS, Beanstalkd або sync, зводячи всі звіти в єдиний інтерфейс. Для роботи потрібні PHP 8.2+, Laravel 12 або 13, Livewire 3.5+ або 4. Пакет розповсюджується за ліцензією MIT.

# Один запис на кожен запуск для всіх драйверів

Якщо Horizon підтримує лише Redis, а Telescope створений переважно для локального налагодження, то Vigilance орієнтований на production. Він створює один рядок для кожного запуску та оновлює його протягом усього життєвого циклу. Ви отримуєте цілісну хронологію, що охоплює Job у чергах, команди CLI та роботу планувальника (scheduler). Кожен запис містить параметри виконання, фінальний статус і очищений від конфіденційних даних Exception trace.

Оскільки зберігання кожного успішного запуску може бути витратним, Vigilance використовує семплювання, але завжди зберігає помилки:

VIGILANCE_SAMPLE_RATE=0.1
VIGILANCE_RETENTION_DAYS=7
VIGILANCE_DB_CONNECTION=monitoring

Налаштування VIGILANCE_SAMPLE_RATE=0.1 дозволяє зберігати лише 10% успішних операцій, що зменшує навантаження на базу даних. Параметр VIGILANCE_DB_CONNECTION дозволяє винести моніторинг в окрему БД, щоб не навантажувати основне з'єднання застосунку.

# Ручний запуск через типізовані форми

Vigilance дозволяє запускати Job безпосередньо з панелі керування. Якщо позначити Job контрактом Dispatchable, система за допомогою Reflection проаналізує конструктор і автоматично побудує форму:

use Vigilance\Contracts\Dispatchable;

class ProcessPodcast implements ShouldQueue, Dispatchable
{
    public static string $vigilanceLabel = 'Process a podcast';

    public function __construct(public Podcast $podcast, public bool $notify = true) {}
}

Форма підтримує скалярні типи, Enums, дати та прив’язку моделей Eloquent. Аналогічний механізм працює і для дозволених Artisan-команд. Ці функції вимкнені за замовчуванням і активуються в конфігурації:

VIGILANCE_CONTROL_ENABLED=true

# Власні метрики та Core Web Vitals

Окрім історії запусків, Vigilance збирає два типи даних. Бізнес-метрики можна відстежувати за допомогою Counter та Gauge API:

use Vigilance\Vigilance;

Vigilance::increment('signups');
Vigilance::gauge('cart_value', $cart->total());

Для фронтенду можна увімкнути Real User Monitoring (RUM). Додавання Blade-директиви в макет дозволяє збирати показники Core Web Vitals (LCP, INP, CLS, FCP, TTFB) реальних відвідувачів:

VIGILANCE_RUM=true

@vigilanceRum

Ці дані відображаються на графіках продуктивності разом із затримками (p50, p95, p99) та рівнем помилок.

# Встановлення та захист панелі

Щоб почати роботу, встановіть пакет і запустіть міграції:

composer require anousss007/vigilance
php artisan vigilance:install
php artisan migrate

За замовчуванням доступ до панелі за адресою /vigilance дозволено лише в локальному середовищі. Для production доступ налаштовується через Gate або метод boot() у Service Provider:

use Vigilance\Vigilance;

Vigilance::auth(fn ($request) => in_array($request->user()?->email, [
    'you@example.com',
]));

Окрім базового моніторингу черг, Vigilance пропонує: групування помилок в єдиний Inbox (web, jobs, CLI, browser), відстеження SLO та бюджетів помилок, аналіз здоров’я релізів, детекцію N+1 запитів, uptime-чеки, інтеграцію логів із трасуванням та сповіщення у Slack, Discord або Teams. Також доступний Worker Supervisor для драйверів, відмінних від Redis, та доступ для AI-агентів через MCP-сервер.

Документація та вихідний код доступні на GitHub.