Первоначальная версия VidConf

docs/deploy/monitoring.md

@@ -0,0 +1,90 @@
+# Мониторинг (Prometheus + Grafana, профиль compose `monitoring`)
+
+Независимый compose-профиль — можно поднимать вместе
+с любым пресетом инсталлятора (1–5) или отдельно.
+
+## 1. Компоненты
+
+| Сервис | Образ | Порт (хост) | Назначение |
+|---|---|---|---|
+| `prometheus` | `prom/prometheus:v3.13.1` | `9090` | сбор и хранение метрик, оценка правил алертинга |
+| `postgres-exporter` | `quay.io/prometheuscommunity/postgres-exporter:v0.20.1` | — (внутренний) | метрики PostgreSQL |
+| `redis-exporter` | `oliver006/redis_exporter:v1.87.0-alpine` | — (внутренний) | метрики Redis |
+| `grafana` | `grafana/grafana:13.1.0` | `3001` (внутри контейнера `3000`) | дашборд «Пайплайны пост-обработки» |
+
+Файлы: `deploy/monitoring/prometheus.yml`, `deploy/monitoring/alerts.yml`,
+`deploy/monitoring/grafana/provisioning/` (datasource + провайдер
+дашбордов), `deploy/monitoring/grafana/dashboards/pipelines.json`.
+
+## 2. Запуск
+
+```bash
+docker compose -f deploy/docker-compose.yml --profile monitoring up -d
+```
+
+- Prometheus: http://localhost:9090
+- Grafana: http://localhost:3001 (логин/пароль — `.env`,
+  `GRAFANA_ADMIN_USER`/`GRAFANA_ADMIN_PASSWORD`; `install.sh` генерирует
+  пароль при первой установке)
+
+Дашборд «Пайплайны пост-обработки» (папка VidConf в Grafana) появляется
+сразу — источник данных и дашборд провижинятся из файлов, без ручной
+настройки.
+
+## 3. Метрики backend
+
+`GET /metrics` (`backend/api/metrics.py`, без авторизации внутри
+приложения — снаружи периметра закрыт явным `return 403` в
+`deploy/nginx/nginx.conf`; Prometheus ходит в backend напрямую по docker-сети,
+`backend:8000/metrics`, минуя nginx):
+
+- `vidconf_http_request_duration_seconds` (histogram, `method`/`path`/`status`) —
+  латентность HTTP по шаблону маршрута.
+- `vidconf_pipeline_sessions` (gauge, `status`) — число сеансов конференций в
+  каждом статусе `pipeline_status`
+  (recording→transcribing→summarizing→notified|failed).
+- `vidconf_celery_queue_depth` (gauge, `queue`) — глубина очередей Celery
+  (`transcription`/`summarize`/`notify`/`celery`, redis `LLEN`), карта
+  очередей — `docs/deploy/scaling.md`.
+
+Job `llm` в `prometheus.yml` скрейпит `llm:8080/metrics`
+(`LLAMA_ARG_ENDPOINT_METRICS=1`) — этот адрес резолвится ЛИБО сервисом
+`llm` (CPU, профиль `llm`), ЛИБО `llm-gpu` (у него есть сетевой алиас `llm`,
+см. `deploy/docker-compose.yml`) — профили `llm`/`llm-gpu` взаимоисключающи
+по пресету, поэтому один job без дублирования.
+
+## 4. Алерты (`deploy/monitoring/alerts.yml`)
+
+| Алерт | Условие | severity |
+|---|---|---|
+| `PipelineFailed` | рост числа сеансов в статусе `failed` за 15 минут | critical |
+| `QueueGrowing` | глубина очереди растёт 15 минут подряд и превышает 10 задач | warning |
+| `LlmDown` | `up{job="llm"} == 0` дольше 2 минут | critical |
+
+`LlmDown` актуален только на инсталляциях с профилем `llm`/`llm-gpu`
+(пресеты 3–5) — на пресетах 1/2 (без AI) таргет `llm:8080` в принципе не
+резолвится и алерт будет постоянно активен, если профиль `monitoring`
+включён без AI-профиля; в таком случае правило можно закомментировать в
+локальной копии `alerts.yml`.
+
+Проверка — искусственно завалить пайплайн и убедиться, что алерт срабатывает:
+
+```bash
+# Стек с профилями media, transcribe, llm, monitoring уже поднят,
+# идёт активная суммаризация (сеанс в статусе summarizing).
+docker compose -f deploy/docker-compose.yml stop llm
+# Подождать > 2 минут → Prometheus (http://localhost:9090/alerts)
+# должен показать LlmDown в состоянии firing, следом — QueueGrowing
+# (очередь summarize перестаёт разбираться) и, если сеанс не восстановится
+# за 15 минут (recover_stuck_summaries переставит задачу, workers/celery_app.py),
+# PipelineFailed.
+docker compose -f deploy/docker-compose.yml start llm
+```
+
+## 5. Хранение
+
+`prometheus_data`/`grafana_data` — именованные тома, переживают
+пересоздание контейнеров. Ретеншен Prometheus — дефолт образа (15 дней);
+для прод-инсталляций с длинным горизонтом донастраивается флагом
+`--storage.tsdb.retention.time` (не задан в `deploy/docker-compose.yml` —
+осознанный dev/small-prod дефолт, донастраивается отдельно при необходимости).