# Monitor

Запускає фоновий монітор, який передає події від тривалого скрипту. Кожен рядок стандартного виводу стає сповіщенням — продовжуйте працювати, поки події надходять у чат.

## Коли використовувати

- Відстеження помилок, попереджень або сигнатур збоїв у файлі журналу під час виконання розгортання
- Опитування віддаленого API, PR або конвеєра CI кожні 30 секунд для виявлення нових подій стану
- Спостереження за змінами в каталозі файлової системи або у виводі збірки в реальному часі
- Очікування певної умови протягом багатьох ітерацій (наприклад, контрольна точка кроку навчання або спорожнення черги)
- **Не** для простого "чекати до завершення" — для цього використовуйте `Bash` з `run_in_background`; він надсилає одне сповіщення про завершення, коли процес завершується

## Параметри

- `command` (рядок, обов'язковий): Команда оболонки або скрипт для запуску. Кожен рядок, записаний у стандартний вивід, стає окремою подією сповіщення. Монітор завершується, коли завершується процес.
- `description` (рядок, обов'язковий): Коротка читабельна мітка, що відображається в кожному сповіщенні. Бути конкретним — "помилки в deploy.log" краще, ніж "спостереження за журналами". Ця мітка визначає, який монітор спрацював.
- `timeout_ms` (число, за замовчуванням `300000`, макс `3600000`): Кінцевий термін примусового завершення в мілісекундах. Після цього часу процес завершується. Ігнорується при `persistent: true`.
- `persistent` (логічне, за замовчуванням `false`): Коли `true`, монітор працює протягом усього часу сесії без тайм-ауту. Зупинити явно за допомогою `TaskStop`.

## Приклади

### Приклад 1: Відстеження файлу журналу на наявність помилок і збоїв

Цей приклад охоплює всі кінцеві стани: маркер успіху, зворотне трасування, поширені ключові слова помилок, завершення через OOM і несподіхваний вихід процесу.

```bash
tail -F /var/log/deploy.log | grep -E --line-buffered \
  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
```

Використовувати `grep --line-buffered` у кожному конвеєрі. Без цього ОС буферизує вивід блоками по 4 КБ і події можуть затримуватися на хвилини. Шаблон чергування охоплює як шлях успіху (`deployed`), так і шляхи збою (`Traceback`, `Error`, `FAILED`, `Killed`, `OOM`). Монітор, що спостерігає лише за маркером успіху, мовчить під час збою — мовчання нерозрізненне від "все ще працює".

### Приклад 2: Опитування віддаленого API кожні 30 секунд

```bash
while true; do
  curl -sf "https://api.example.com/status" || true
  sleep 30
done | grep --line-buffered -E "completed|failed|error"
```

`|| true` запобігає завершенню циклу через тимчасовий збій мережі. Інтервали опитування 30 секунд і більше підходять для віддалених API, щоб уникнути обмежень частоти запитів. Налаштувати шаблон grep для захоплення як успішних, так і помилкових відповідей, щоб помилки на стороні API не маскувалися мовчанням.

## Примітки

- **Завжди використовувати `grep --line-buffered` у конвеєрах.** Без цього буферизація конвеєра затримує події на хвилини, оскільки ОС накопичує вивід до заповнення блоку 4 КБ. `--line-buffered` примусово скидає буфер після кожного рядка.
- **Фільтр повинен охоплювати як сигнатури успіху, так і збою.** Монітор, що спостерігає лише за маркером успіху, мовчить при збої, зависанні або несподіваному виході. Розширити чергування: включити `Error`, `Traceback`, `FAILED`, `Killed`, `OOM` і подібні маркери кінцевого стану поряд із ключовим словом успіху.
- **Інтервали опитування: 30 секунд і більше для віддалених API.** Часте опитування зовнішніх сервісів ризикує отримати помилки обмеження частоти запитів або блокування. Для локальних перевірок файлової системи або процесів підходить 0,5–1 секунда.
- **Використовувати `persistent: true` для моніторів на час сесії.** Стандартний `timeout_ms` у 300 000 мс (5 хвилин) завершує процес. Для моніторів, які повинні працювати до явної зупинки, встановити `persistent: true` і викликати `TaskStop` після завершення.
- **Автоматична зупинка при потоці подій.** Кожен рядок стандартного виводу — це повідомлення в розмові. Якщо фільтр занадто широкий і виробляє занадто багато подій, монітор зупиняється автоматично. Перезапустити з більш строгим шаблоном `grep`. Рядки, що надходять протягом 200 мс, об'єднуються в одне сповіщення.
