Monitoring Setup

Установка стека мониторинга: Prometheus, Grafana, Loki, Promtail, Tempo.

1. Обзор стека

Сервис	Внешний доступ	Назначение
Grafana	`grafana.goloot.online` (Traefik + SSL)	Дашборды и визуализация
Prometheus	Нет (только внутри Docker)	Сбор метрик (scrape)
Loki	Нет (только внутри Docker)	Агрегация логов
Promtail	Нет (только внутри Docker)	Сбор и отправка логов
Tempo	Нет (только внутри Docker)	Distributed tracing

Безопасность

Все сервисы кроме Grafana не имеют внешних портов. Grafana доступна через Traefik с SSL и защищена встроенной авторизацией. Прямые порты (9090, 3100, 3200) убраны — весь трафик идёт через Traefik (:80/:443).

2. Предварительные условия

Docker-сеть dokploy-network существует
Backend уже задеплоен
Docker log rotation настроена (см. Server Setup)

Проверить сеть:

docker network ls | grep dokploy

Обычно уже существует

Dokploy создаёт эту сеть при установке. Если по какой-то причине нет — она автоматически создастся при первом деплое сервиса.

3. Деплой мониторинга

Один проект для всего

Все сервисы (включая мониторинг) живут в одном проекте goLoot — так проще управлять и видеть общую картину.

Dokploy UI → Projects → проект goLoot
New Service → Docker Compose
Имя сервиса: monitoring
Source: GitHub → репозиторий goLoot
Compose Path: monitoring/docker-compose.yml
Environment Variables:

GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=YOUR_SECURE_PASSWORD

Deploy

4. Доступ к Grafana

Grafana доступна через Traefik: grafana.goloot.online

Домен настроен через Dokploy (Domains tab в monitoring compose). Прямой порт :3030 убран — весь трафик через Traefik с SSL.

Авторизация — встроенная Grafana auth (логин/пароль задаются через GRAFANA_ADMIN_USER / GRAFANA_ADMIN_PASSWORD в Environment).

5. Что мониторится

Логи (Loki + Promtail)

Promtail автоматически собирает логи из Docker-контейнеров. Фильтры настроены по паттернам имён контейнеров:

Фильтр	Описание
`goloot-.*`	Все сервисы goLoot
`backend.*`	Backend API
`frontend.*`	Frontend
`admin.*`	Admin Panel
`redirect.*`	Redirect Service

tip

Имена контейнеров генерируются Dokploy автоматически (например, goloot-backend-abc123). Фильтры используют regex, поэтому backend.* поймает любое имя, содержащее backend.

Пайплайн обработки:

Парсинг Docker JSON → извлечение log, stream, time
Парсинг Pino JSON → извлечение level, msg, requestId, userId, method, path, statusCode, duration
Фильтрация шума: /health, /metrics, /favicon — отбрасываются

Retention: 7 дней (настраивается в loki-config.yml)

Метрики (Prometheus)

Prometheus scrape targets:

Job	Target	Interval
`backend`	`golootstaging-backend-z9c2jc:4000`	15s
`redirect-service`	`redirect-service:3000`	15s
`prometheus`	`localhost:9090`	15s

Имя контейнера

Target Backend использует имя Dokploy-сервиса (стабильное). Найти его: docker ps | grep backend.

Кэш-метрики (Redis Cache Layer):

Метрика	Тип	Labels	Описание
`cache_hit_total`	Counter	`key_prefix`	Попадания в кэш
`cache_miss_total`	Counter	`key_prefix`	Промахи (запрос в БД)
`cache_error_total`	Counter	`operation`	Ошибки Redis

Полезные PromQL запросы:

# Cache hit rate (%)
cache_hit_total / (cache_hit_total + cache_miss_total) * 100

# Hits per second by prefix
rate(cache_hit_total[5m])

# Errors per second
rate(cache_error_total[5m])

Alert rules:

Alert	Условие	Severity
HighErrorRate	Error rate > 5% за 5 мин	critical
HighResponseTime	p95 > 1s за 5 мин	warning

Трейсы (Tempo)

Backend отправляет трейсы через OpenTelemetry:

Receiver	Порт	Протокол
OTLP gRPC	4317	gRPC
OTLP HTTP	4318	HTTP

Retention: 48 часов

6. Grafana: полезные запросы

LogQL (Loki)

# Все ошибки backend
{container=~".*backend.*"} | json | level = "error"

# Медленные запросы (>1s)
{container=~".*backend.*"} | json | duration > 1000

# По userId
{container=~".*backend.*"} | json | userId = "user-id-here"

# По requestId (трейсинг запроса)
{container=~".*backend.*"} | json | requestId = "req-id-here"

Pino Log Levels

Level	Число	Фильтр
fatal	60	`level >= 60`
error	50	`level >= 50`
warn	40	`level >= 40`
info	30	`level >= 30`
debug	20	`level >= 20`

7. Troubleshooting

Логи не появляются в Grafana

Проверить Promtail:

docker logs $(docker ps -q -f name=promtail) --tail 20

Проверить Loki:

curl http://localhost:3100/ready
# Should return "ready"

Promtail может не видеть контейнеры — проверить Docker socket:

docker exec $(docker ps -q -f name=promtail) ls /var/run/docker.sock

Высокое потребление диска

# Проверить размер данных
du -sh /var/lib/docker/volumes/monitoring_*

# Очистить старые данные Loki
docker restart $(docker ps -q -f name=loki)

"Entry out of order" ошибки в Loki

Добавь в loki-config.yml:

limits_config:
  reject_old_samples: true
  reject_old_samples_max_age: 168h

8. Docker log rotation на сервере

Обязательно настроить

Без rotation Docker логи заполнят диск. Настройка описана в Server Setup → Docker log rotation.

Быстрая проверка что rotation уже настроена:

cat /etc/docker/daemon.json
# Должен содержать "max-size" и "max-file"

10. Grafana API для автоматизации

Service Account

Grafana поддерживает Service Accounts — специальные аккаунты для API-доступа без пароля. Используются для:

Автоматической диагностики (AI-агент запрашивает метрики и логи)
Скриптов мониторинга
Интеграции с внешними системами

Создание Service Account

Grafana → Administration → Service Accounts
Add Service Account → имя (например, AI-Diagnostics), роль: Viewer
Add Service Account Token → скопировать токен (glsa_xxx...)

Токен показывается один раз

После закрытия окна токен нельзя посмотреть — только пересоздать. Сохрани сразу.

Viewer = read-only

Роль Viewer даёт только чтение — нельзя изменить dashboards, datasource или настройки. Безопасно для автоматизации.

Datasource UIDs

Datasource	UID	Proxy URL
Prometheus	`prometheus`	`/api/datasources/proxy/uid/prometheus/`
Loki	`loki`	`/api/datasources/proxy/uid/loki/`
Tempo	`tempo`	`/api/datasources/proxy/uid/tempo/`

Примеры API-запросов

Prometheus (метрики):

TOKEN="glsa_xxx"
BASE="https://grafana.goloot.online/api/datasources/proxy/uid/prometheus"

# Текущие значения cache метрик
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/query?query=cache_hit_total"

# Cache hit rate (%)
curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/query?query=cache_hit_total/(cache_hit_total%2Bcache_miss_total)*100"

# Статус всех targets (UP/DOWN)
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/targets"

Loki (логи):

TOKEN="glsa_xxx"
BASE="https://grafana.goloot.online/api/datasources/proxy/uid/loki"

# Ошибки backend за последний час
curl -s -G -H "Authorization: Bearer $TOKEN" "$BASE/loki/api/v1/query_range" \
  --data-urlencode 'query={container=~".*backend.*"} | json | level >= 50' \
  --data-urlencode "start=$(date -d '1 hour ago' +%s)" \
  --data-urlencode "end=$(date +%s)" \
  --data-urlencode "limit=20"

# Логи конкретного пользователя
curl -s -G -H "Authorization: Bearer $TOKEN" "$BASE/loki/api/v1/query_range" \
  --data-urlencode 'query={container=~".*backend.*"} | json | userId = "USER_UUID"' \
  --data-urlencode "start=$(date -d '1 hour ago' +%s)" \
  --data-urlencode "end=$(date +%s)"

Grafana Health:

# Проверка что Grafana работает
curl -s -H "Authorization: Bearer $TOKEN" "https://grafana.goloot.online/api/health"

# Список datasources
curl -s -H "Authorization: Bearer $TOKEN" "https://grafana.goloot.online/api/datasources"

Хранение токена

Токен хранится вне git-репозитория:

# Для Claude Code (локальный проект)
~/.claude/projects/-root-goloot/grafana-token

# Для других инструментов — .env файл (gitignored)
echo "GRAFANA_SA_TOKEN=glsa_xxx" >> backend/.env

Безопасность

Токен НЕ коммитится в репозиторий
Роль Viewer — минимально необходимые права
Токен можно отозвать в любой момент (Grafana → Service Accounts → Delete Token)
При компрометации — удалить и пересоздать

11. Чеклист

dokploy-network существует
Monitoring stack задеплоен через Dokploy (Docker Compose сервис)
Grafana доступна через grafana.goloot.online
Нет прямых внешних портов (9090, 3030, 3100, 3200 закрыты)
Логи backend видны в Grafana → Explore → Loki
Метрики Prometheus собираются (backend target = UP)
Cache метрики видны: cache_hit_total, cache_miss_total
Docker log rotation настроена
Grafana Service Account создан (роль Viewer) для API-доступа

Server Setup — Docker log rotation
Services Deployment — предыдущий шаг
CI/CD Setup — следующий шаг
Observability — детали логирования в приложении
Logging Architecture — архитектура логов

1. Обзор стека​

2. Предварительные условия​

3. Деплой мониторинга​

4. Доступ к Grafana​

5. Что мониторится​

Логи (Loki + Promtail)​

Метрики (Prometheus)​

Трейсы (Tempo)​

6. Grafana: полезные запросы​

LogQL (Loki)​

Pino Log Levels​

7. Troubleshooting​

Логи не появляются в Grafana​

Высокое потребление диска​

"Entry out of order" ошибки в Loki​

8. Docker log rotation на сервере​

10. Grafana API для автоматизации​

Service Account​

Создание Service Account​

Datasource UIDs​

Примеры API-запросов​

Хранение токена​

11. Чеклист​

Related​