feat(openspec): vesti-alerts — 6 алертов на компоненты VESTI (web/publisher/tunnel/db/stale); OpenSpec change

openspec/changes/2026-09-13-vesti-alerts/design.md

@@ -0,0 +1,61 @@
+# Design
+
+## Механизм алертов
+
+В стеке /opt/monitoring алерты реализованы **Prometheus Alerting rules** (prometheus.yml
+`rule_files: /etc/prometheus/alerts.yml`, Prometheus 3.1+ встроенный алертинг с мульти-секционной
+группировкой `groups:`/`rules:`). Формат rules (алерты на базе PromQL-выражений с `for` = время
+удержания условия, `labels.severity`, `annotations.summary`). Доставка уведомлений — согласно
+существующей конфигурации (webhook/канал, настроенный в Prometheus или в той же alerts.yml
+внешним получателем — проверить фактический механизм доставки в стеке; в референсах скилла
+указано, что уведомления приходят в чат).
+
+## Метрики VESTI (textfile-коллектор, job `node`, label `component="vesti"`)
+
+| Метрика | Смысл | Алерт |
+|---|---|---|
+| vesti_web_up | web :8400 (systemd) | ==0 → critical |
+| vesti_publisher_health | publisher :8410 /healthz | ==0 → critical |
+| vesti_publisher_docker | контейнер publisher (docker ps) | ==0 → critical |
+| vesti_telegram_tunnel | SOCKS5-туннель :1080 | ==0 → critical |
+| vesti_db_ok | SQLite vesti.db доступна | ==0 → critical |
+| vesti_db_last_run_ts | Unix-ts последнего рan краулера | time()-ts >1800 → warning |
+
+## Формат rules (из alerts.yml)
+
+```yaml
+groups:
+- name: vesti
+  rules:
+  - alert: VestiWebDown
+    expr: vesti_web_up{component="vesti"} == 0
+    for: 2m
+    labels:
+      severity: critical
+    annotations:
+      summary: VESTI web (:8400) is down
+```
+
+Время реакции: `for: 2m` — алерт срабатывает после 2 минут непрерывного условия
+(метрики обновляются раз в минуту скриптом vesti-metrics.sh → 2-3 пробы подряд).
+
+## Верификация
+
+1. `docker exec prometheus promtool check config /etc/prometheus/prometheus.yml` → OK
+   (проверяет и rule_files).
+2. `docker compose restart prometheus` (перечитывает alerts.yml).
+3. Запрос в Prometheus API: значения метрик vesti_* присутствуют.
+4. Проверка алертов: имитация (временно выставить метрику в 0, убедиться что алерт firing,
+   вернуть обратно) — или проверка через Prometheus /api/v1/rules/дубликат.
+5. Обновить README.md + EXPERIENCE.md, openspec validate + archive.
+
+## Риски
+
+- При `for: 2m` и интервале скрипта 1 мин алерт может срабатывать с задержкой до 3 мин
+  (приемлемо для внутреннего сервиса).
+- Метрики пишутся только при успешном выполнении скрипта; если textfile-файл пропадёт
+  (сломан скрипт) — метрики исчезнут и алерт по `==0` не сработает. Для этого есть
+  `VestiDbStale` (time() - ts) — он тоже покроет случай пропадания данных? Нет: если файл
+  пропал, ts не обновится → last_run_ts останется старым → VestiDbStale сработает.
+  Дополнительно можно добавить expr на отсутствие данных (deadman), но это выходит за рамки
+  текущего change — зафиксировать в EXPERIENCE.md как известное ограничение.