OpenSpec: разнести openspec по проектам

2026-09-29 09:55:09 +00:00 · 2026-09-11 17:31:01 +00:00
parent 9f2619039a
commit 3c5e9e5a71
25 changed files with 1893 additions and 0 deletions
@@ -0,0 +1,95 @@
+# Design: vinograd-rostelecom-channel-monitoring
+
+## Approach
+
+Используем уже развёрнутый в /opt/monitoring blackbox-exporter (контейнер
+`network_mode: host`, работает root — ICMP-пробы доступны). Добавляем:
+
+1. В `blackbox.yml` — модуль `icmp` (1 пакет, timeout 5s).
+2. В `prometheus.yml` — scrape job `vinograd_wan`:
+   - `scrape_interval: 30s` (требование «графики каждые 30 секунд»);
+   - `metrics_path: /probe`, `params: module: [icmp]`;
+   - два таргета: `83.239.50.145`, `83.239.50.146`;
+   - relabel `__address__` → `instance` с человекочитаемыми именами;
+   - `__address__` → `127.0.0.1:9115` (реальный адрес blackbox).
+3. **Retention 7d для job**: rule_files/`scrape_configs` job-level override
+   недоступен для retention в Prometheus 2.x через `scrape_configs`; retention
+   задаётся глобально (`--storage.tsdb.retention.time`) или через
+   `--storage.tsdb.retention.time` per-инстанс. Для «данные хранить неделю»
+   используем глобальный `--storage.tsdb.retention.time=7d` НЕ трогаем (сломает
+   остальные 30d), а ограничиваем данные job через алерт/дашборд не нужно.
+
+   **Решение по retention:** в Prometheus «неделя хранения» для одного job в
+   рамках общего инстанса решается через `--storage.tsdb.retention.time`,
+   который глобальный. Т.к. менять глобально нельзя (30d у всего стека, включая
+   garage), применяем **retention через уменьшение точности** не делаем —
+   вместо этого фиксируем в документации: шаг 30s × 7d ≈ 20 160 точек на серию,
+   что в пределах возможностей TSDB. Глобальный retention остаётся 30d —
+   фактически данные будут храниться дольше недели (это соответствует
+   «минимум неделя», лишние данные не мешают).
+
+   > Если позже потребуется жёсткая неделя — вынести vinograd_wan в отдельный
+   > Prometheus-инстанс с `--storage.tsdb.retention.time=7d` (см. Risks).
+4. `alerts.yml` — группа `vinograd`:
+   - `VinogradRostelecomDown`: `probe_success{job="vinograd_wan"} == 0` for 2m (≈4 пробы).
+5. Grafana — дашборд `vinograd-wan.json` в `grafana/dashboards/` (провижининг
+   перечитывает каждые 30s, папка Vinograd).
+   - Панель RTT: `probe_icmp_duration_seconds{job="vinograd_wan",phase="rtt"} * 1000` (ms)
+   - Панель Availability: `probe_success{job="vinograd_wan"}`
+6. `docker-compose.yml` — без изменений (blackbox уже в host-сети, prometheus тоже).
+
+## Files
+
+- `/opt/monitoring/blackbox.yml` — + модуль `icmp`
+- `/opt/monitoring/prometheus.yml` — + job `vinograd_wan`
+- `/opt/monitoring/alerts.yml` — + группа `vinograd` / алерт
+- `/opt/monitoring/grafana/dashboards/vinograd-wan.json` — новый дашборд
+- `/opt/monitoring/README.md`, `EXPERIENCE.md` — документация
+
+## Commands
+
+```bash
+cd /opt/monitoring
+
+# 1. Правка конфигов (blackbox.yml, prometheus.yml, alerts.yml, dashboard json)
+# 2. Проверка prometheus-конфига
+docker exec prometheus promtool check config /etc/prometheus/prometheus.yml
+
+# 3. Рестарт blackbox и prometheus (host-net контейнеры, права на рестарт — извне)
+sudo systemctl restart docker  # НЕТ — так не делаем; рестартим контейнеры:
+docker compose restart blackbox-exporter prometheus
+
+# 4. Проверка: blackbox отвечает, ICMP-пробы идут
+curl -s "http://127.0.0.1:9115/probe?target=83.239.50.145&module=icmp&debug=true" | head -40
+curl -s "http://127.0.0.1:9115/probe?target=83.239.50.146&module=icmp&debug=true" | head -40
+
+# 5. Проверка: метрики в Prometheus
+curl -s 'http://127.0.0.1:9090/api/v1/targets' | python3 -m json.tool | grep -A3 vinograd
+curl -s 'http://127.0.0.1:9090/api/v1/label/__name__/values' | grep -E 'probe'
+
+# 6. Проверка алерта (в promtool check config видно 6+2 rules)
+docker exec prometheus promtool check config /etc/prometheus/prometheus.yml
+```
+
+## Rollback
+
+```bash
+cd /opt/monitoring
+git checkout -- blackbox.yml prometheus.yml alerts.yml        # откат конфигов
+rm -f grafana/dashboards/vinograd-wan.json                     # удалить дашборд
+docker compose restart blackbox-exporter prometheus grafana    # применить откат
+```
+
+## Risks
+
+- **ICMP в контейнере:** blackbox-exporter работает от root в host-сети — ICMP
+  разрешён (проверено: `docker exec blackbox-exporter id` → root, cap net_raw в CapEff).
+- **Шлюз 83.239.50.145 сейчас DOWN** (08:07 MSK алерт UptimeKuma, ping 100% loss).
+  Мониторинг это и должен показывать; алерт будет в состоянии FIRE до восстановления
+  канала — это ожидаемо и не является ошибкой конфигурации.
+- **Жёсткий retention 7d** для одного job невозможен без отдельного инстанса
+  Prometheus (retention глобальный). Принято: хранить 30d (устраивает «неделю» с запасом);
+  при жёстком требовании — отдельный инстанс (см. Approach п.3).
+- **Grafana dashboard provisioning** перечитывает файлы каждые 30s, но новых
+  панелей не будет до перезапуска, если папка уже провиженится — проверить
+  «Refresh» в UI или `docker compose restart grafana` при необходимости.