vidconf/docs/deploy/monitoring.md

Мониторинг (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. Запуск

docker compose -f deploy/docker-compose.yml --env-file .env --profile monitoring up -d

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001 (логин/пароль — .env, GRAFANA_ADMIN_USER/GRAFANA_ADMIN_PASSWORD; install.sh генерирует пароль при первой установке)

⚠️ На боевом сервере оба порта публикуются ТОЛЬКО на 127.0.0.1 (deploy/docker-compose.yml) — открытые наружу admin-панели без дополнительной аутентификации ранее уже приводили к компрометации сервисов на этом проекте (см. .forcc/deploy/SESSION2-FINDINGS.md). С другой машины используйте ssh-туннель:

ssh -L 9090:127.0.0.1:9090 -L 3001:127.0.0.1:3001 <user>@<host>

и открывайте http://localhost:9090 / http://localhost:3001 у себя.

Дашборд «Пайплайны пост-обработки» (папка 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 без дублирования.

По умолчанию job llm закомментирован в prometheus.yml (вместе с алертом LlmDown в alerts.yml) — целевой набор профилей compose (media,monitoring, см. .env.example) не включает llm/llm-gpu, и таргет llm:8080 не резолвится вовсе. Раскомментируйте job и алерт вместе, если инсталляция запущена с профилем llm/llm-gpu (пресеты 3–5 install.sh) — иначе панель «LLM-сервер доступен» дашборда «Пайплайны пост-обработки» будет показывать «No data».

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) — по умолчанию (профили media,monitoring, без AI) правило закомментировано в alerts.yml вместе с job llm в prometheus.yml. Раскомментируйте оба, если поднимаете профиль llm/llm-gpu.

Проверка (после раскомментирования job/алерта, на инсталляции с профилем llm/llm-gpu) — искусственно завалить пайплайн и убедиться, что алерт срабатывает:

# Стек с профилями media, transcribe, llm, monitoring уже поднят,
# идёт активная суммаризация (сеанс в статусе summarizing).
docker compose -f deploy/docker-compose.yml --env-file .env 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 --env-file .env start llm

5. Хранение

prometheus_data/grafana_data — именованные тома, переживают пересоздание контейнеров. Ретеншен Prometheus — дефолт образа (15 дней); для прод-инсталляций с длинным горизонтом донастраивается флагом --storage.tsdb.retention.time (не задан в deploy/docker-compose.yml — осознанный dev/small-prod дефолт, донастраивается отдельно при необходимости).