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
- [ ] Node-exporter на 3 хостах (10.8.0.x:9100)
- [ ] Запустить `docker compose up -d`
- [ ] Проверить Prometheus :9090 (`up{job="garage"}`, targets)
- [ ] 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 | срабатывания лимитов |

Задача:

- [ ] Обеспечить доступ Prometheus (bigbox) к `:8081` на vps03.
      vps03 НЕ в WG-сети (10.8.0.0/24 = vps01/bigbox/vps02).
      Варианты:
      a) открыть 8081 на vps03 для IP bigbox в nft (правило в
         `/etc/tproxy-server/firewall.nft` или отдельный файл) — самый простой;
      b) добавить vps03 в WG (если хочется закрытый контур);
      c) node-exporter + textfile-коллектор — не наш случай (метрики уже в HTTP).
      Рекомендация: (a).
      **Конкретные шаги (рекомендуемый вариант a):**
      - [ ] На vps03 (77.67.89.154) добавить nft-правило, разрешающее TCP 8081
            с публичного IP bigbox **178.176.197.2** (проверить актуальный IP
            bigbox перед выполнением: `curl -s https://api.ipify.org`):
            ```
            nft add rule inet filter input ip saddr 178.176.197.2 tcp dport 8081 accept
            ```
            (или внести в `/etc/tproxy-server/firewall.nft`, если он в авто-загрузке)
      - [ ] Проверить с bigbox:
            `curl -s http://77.67.89.154:8081/metrics | head`
            → должен вернуть метрики tproxy (не timeout/refused).
      - [ ] Добавить job 'tproxy' в `/opt/monitoring/prometheus.yml`:
            ```yaml
            - job_name: 'tproxy'
              static_configs:
                - targets: ['77.67.89.154:8081']
                  labels:
                    host: vps03
                    service: tproxy
            ```
      - [ ] `docker compose restart prometheus` в /opt/monitoring,
            проверить `up{job="tproxy"}` на 127.0.0.1:9090 = 1.
- [ ] (Опционально) blackbox-job для внешнего HTTPS-чека vps03.nixg.ru:
      `probe_success` — контролирует Caddy+сайт снаружи.
- [ ] Дашборд в Grafana: сессии, трафик (bytes_up/down rate), ошибки бэкенда.
- [ ] Алерт: `tproxy_backend_dial_failures_total` растёт, или `/readyz` 503
      (можно ч/з blackbox по HTTP :8081, если открыт).

Заметки:
- `/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.