# 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 мс, объединяются в одно уведомление.
