monitoring/PLAN.md

# План работ: мониторинг Garage-кластера

## Цель
Вывести статус кластера Garage (vps01, bigbox, vps02) в браузер через Grafana,
с Prometheus-метриками и сбором логов (Loki). Без трейсов (до них «не доросли»).

## Этап 1. Метрики Garage (выполнено ✅)

1. Понять, как Garage v2.1 отдаёт метрики.
   → Найдено: admin API на отдельном порту `[admin] api_bind_addr`; `/metrics` в
     Prometheus-формате; `metrics_token` опционален.
2. Добавить в `/opt/garage/garage.toml` на **трёх** нодах:
   ```toml
   [admin]
   api_bind_addr = "<WG-IP>:3903"
   metrics_token = "<token>"
   ```
   - bigbox: 10.8.0.2:3903 (файл — estorozhenko)
   - vps01: 10.8.0.1:3903 (файл — root, sudo)
   - vps02: 10.8.0.4:3903 (файл — root, sudo)
3. Открыть порт 3903 для WG-подсети на vps01 (ufw); на vps02/bigbox не требуется.
4. Перезапустить ноды по очереди: vps02 → vps01 → bigbox (пауза ~8с).
5. Проверить: `curl -H "Authorization: Bearer <token>" http://<ip>:3903/metrics` → 200.

**Результат:** все 3 ноды отдают метрики, кластер HEALTHY.

## Этап 2. Стек мониторинга на bigbox (выполнено ✅)

- [x] Создать `/opt/monitoring/` с docker-compose.yml, prometheus.yml, alerts.yml
- [x] Prometheus: таргеты garage x3 (:3903), health x3, node-exporters, self
- [x] Node-exporter на 3 хостах (10.8.0.x:9100)
- [x] Запустить `docker compose up -d`
- [x] Проверить Prometheus :9090 (`up{job="garage"}`, targets)
- [x] Grafana :3001: datasource Prometheus, дашборд Garage, alerts

## Этап 3. Логи (после метрик 🔄)

- [ ] Promtail (docker.sock) → Loki :3100 → Grafana
- [ ] Логи garage со всех нод (сейчас promtail только на bigbox)

## Этап 4. Git + катастрофоустойчивость (в работе 🔄)

- [x] MD-файлы: README.md, EXPERIENCE.md, PLAN.md
- [ ] git init в /opt/monitoring, первый коммит
- [ ] remote: git@gitverse.ru:kpa39l/monitoring.git (master)
- [ ] `git push -u origin master`
- [ ] В gitea: pull mirror репозитория из gitverse
- [ ] В gitea: добавить estorozhenko с полными правами (на случай поломки bigbox)

## Этап 5. Полировка (TODO)

- [ ] Разные admin_token / metrics_token (`openssl rand -base64 32`)
- [ ] Дашборд: статус нод, занятость диска, блоки, репликация
- [ ] Уведомления алертов (например, в Telegram/почту)

## Этап 6. Метрики tproxy-server (vps03) — TODO 🔄

WEB Proxy для Telegram Desktop развёрнут на vps03 (77.67.89.154, Debian 13):
Caddy → tproxy-server:8080 → MTProxy:2398. Admin-эндпоинты:

- `http://127.0.0.1:8081/readyz`  → 200 `ready` / 503 `backend unavailable`
  (TCP-проба ко всем backend-профилям, у нас 127.0.0.1:2398)
- `http://127.0.0.1:8081/healthz` → всегда `ok` (процесс жив)
- `http://127.0.0.1:8081/metrics` → Prometheus-формат (текст, version 0.0.4)

Метрики tproxy (счётчики из `internal/server/server.go` serveMetrics):

| Метрика | Смысл |
|---|---|
| tproxy_sessions_live / streams_live | активные сессии/потоки |
| tproxy_backend_dials_in_flight | исходящие к MTProxy в полёте |
| tproxy_pending_bytes / _items | очередь ожидающих данных |
| tproxy_sessions_created_total / closed_total | создано/закрыто (суммарно) |
| tproxy_streams_opened_total / rejected_total | открыто/отклонено потоков |
| tproxy_backend_dial_failures_total | **ошибки коннекта к MTProxy** (рост = проблема) |
| tproxy_bytes_up_total / down_total | трафик вверх/вниз (всего) |
| tproxy_limit_hits_total | срабатывания лимитов |

Задача:

- [x] **РЕШЕНО через SSH-туннель (не nft!)** — tproxy-server слушает `admin_listen: 127.0.0.1:8081`
      только на loopback (осознанно), простое nft-правило из плана НЕ сработало бы:
      соединение с bigbox упёрлось бы в `Connection refused` (проверено).
      Поэтому добавлен systemd-сервис `tproxy-tunnel.service` на bigbox:
      ```
      ssh -i /home/estorozhenko/.ssh/hostkeyVPS \
          -L 127.0.0.1:18081:127.0.0.1:8081 -N \
          root@77.67.89.154
      ```
      Порт 18081 (а НЕ 8081 — 8081 на bigbox занят ICQ-веб-чатом!).
      Prometheus скрейпит `127.0.0.1:18081`.
- [x] Job 'tproxy' в prometheus.yml: `targets: ['127.0.0.1:18081']` → up=1, метрики скрейпятся.
- [x] Дашборд Garage Cluster дополнен 3 панелями tproxy: live sessions/streams, traffic /sec,
      backend errors.
- [x] Алерты TProxyDown (critical) и TProxyBackendErrors (warning) в alerts.yml.
- [x] **Починен существующий баг: alerts.yml не был смонтирован в Prometheus** — garage-алерты
      не работали (0 групп правил). Добавлен volume `./alerts.yml:/etc/prometheus/alerts.yml:ro`
      в docker-compose.yml. Теперь загружено 6 правил (garage + tproxy).
- [x] **Починены пустые панели (NO DATA, 2026-09-02)**: три причины подряд —
      (1) у datasource не был задан `uid` (Grafana генерила случайный), добавлен
      `uid: Prometheus` в datasources.yml; (2) URL `http://prometheus:9090` не
      резолвился из Grafana (Prometheus на host-сети), заменён на `http://172.28.0.1:9090`
      (шлюз bridge-сети Grafana = адрес хоста); (3) панели и алерты ссылались
      на несуществующие метрики (`garage_block_count`, `garage_rpc_node_health_is_up`,
      `garage_api_s3_request_counter`) — переписаны на реальные (`block_resync_*`,
      `cluster_layout_node_connected`, `rate(api_s3_request_counter[5m])`). Подробности —
      EXPERIENCE.md п.12-17.
- [x] Relabel `instance` → hostname в prometheus.yml (garage/node/tproxy):
      `10.8.0.x` → `vps01|bigbox|vps02`, `127.0.0.1:18081` → `vps03:8081`.
      Легенды в Grafana — hostname, а не IP.

Заметки:
- `/metrics` и admin-эндпоинты слушают ТОЛЬКО loopback (127.0.0.1:8081). При
  открытии наружу — резать по источнику (IP bigbox) в nft, не публиковать всем.
- readyz сделает TCP-пробу К КАЖДОМУ профилю — если добавить второй профиль
  с мёртвым бэкендом, readyz станет 503 (это фича).
- Секреты WEB Proxy (profiles.json) к мониторингу отношения не имеют — в
  метрики не попадают.

## Риски / заметки

- Перезапуск нод кластера безопасен, но делать по очереди.
- Scratch-образ garage → для CLI-команд нужен `--entrypoint /garage` + монтирование meta.
- Интернет с bigbox частично ограничен; документация — через git.deuxfleurs.fr (ветка main-v1).
- Port 3000 занят gitea → Grafana на 3001.