openspec-lab/openspec/changes/archive/2026-09-08-vinograd-rostelecom-channel-monitoring/design.md

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

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

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 при необходимости.