Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tracing

AngaraBase использует tracing. Есть два уровня наблюдаемости:

  1. Логи сервера — вербозность задаёт RUST_LOG (см. Логирование).
  2. Трассы запросов (OTel-спаны) — опциональный per-query экспорт спанов accept → parse → plan → execute → storage → commit.

Экспорт идёт только в stderr (через лог) или в локальный JSONL-файл. Сетевого OTLP-коллектора, Jaeger/Tempo, push по HTTP — нет.

Включение трасс запросов

Per-query трассы выключены по умолчанию. Управление — переменными окружения:

ПеременнаяНазначениеПо умолчанию
ANGARABASE_OTEL_ENABLEDвключить экспорт спанов (1/true/yes/on)off
ANGARABASE_OTEL_SAMPLE_RATE_PPMдоля сэмплируемых запросов в ppm (0 — выкл, 1000000 — 100%)1000000
ANGARABASE_OTEL_EXPORTERприёмник: stderr или filestderr
ANGARABASE_OTEL_ENDPOINTпуть к JSONL-файлу (только при EXPORTER=file)—
 
# 5% запросов в локальный JSONL-файл
export ANGARABASE_OTEL_ENABLED=1
export ANGARABASE_OTEL_SAMPLE_RATE_PPM=50000
export ANGARABASE_OTEL_EXPORTER=file
export ANGARABASE_OTEL_ENDPOINT=/var/log/angarabase/query-traces.jsonl
./angarabase-server --config-path /etc/angarabase/angarabase.conf

При EXPORTER=stderr строки спанов попадают в обычный лог сервера (на уровне info).

Что в спане

Каждая трасса запроса несёт идентификаторы, по которым её можно связать с sys.*-диагностикой:

  • логическая БД и пользователь;
  • класс запроса (QueryClass);
  • queryid и planid (если доступны) — те же идентификаторы, что в angara_stat_statements и EXPLAIN.

Разбор JSONL

# медленные запросы (>1s) из файла трасс
jq 'select(.duration_ms > 1000)' /var/log/angarabase/query-traces.jsonl

# распределение по queryid
jq -r '.queryid' /var/log/angarabase/query-traces.jsonl | sort | uniq -c | sort -rn | head

Для агрегатных метрик (latency-перцентили, частота медленных запросов) используйте Prometheus-эндпоинт — см. Мониторинг, а для точечного анализа плана — Диагностику.

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

⚠️ Спаны и логи могут содержать текст SQL с чувствительными данными.

  • Ограничьте доступ к файлу трасс: chmod 640, владелец — сервисный пользователь.
  • Настройте ротацию (см. logrotate в Логировании).
  • Не включайте 100%-сэмплинг с текстом SQL на проде без необходимости — это и объём, и риск утечки.

Если трасс нет

  • ANGARABASE_OTEL_ENABLED не установлен в 1/true — спаны не пишутся.
  • ANGARABASE_OTEL_SAMPLE_RATE_PPM=0 — сэмплинг выключен.
  • EXPORTER=file, но ANGARABASE_OTEL_ENDPOINT не задан или путь недоступен на запись — строка уходит в stderr-лог вместо файла.
  • Слишком строгий RUST_LOG для stderr-экспортёра — поднимите уровень (см. Логирование).

См. также