Observability Metrics Reference

Полный справочник метрик AngaraBase с диагностическими маршрутами и quick reference card. Каноничный источник: этот runbook в angarabook/src/operations/.

Quick Reference Card (Top-10 для wallboard)

Распечатайте и повесьте у дежурного. Эти 10 метрик закрывают 80% production incidents.

Полный справочник метрик

Соединения и сессии

Диагностика соединений:

SELECT pid, state, consumer_id, wait_event FROM angara_stat_activity;

Транзакции и MVCC

PromQL — TPS:

rate(angarabase_txn_commit_total[1m])

PromQL — Conflict ratio:

rate(angarabase_txn_commit_conflicts_total[5m]) / rate(angarabase_txn_commit_total[5m])

WAL и durability

PromQL — WAL durability gap (байт):

angarabase_transaction_log_flush_lsn - angarabase_transaction_log_durable_lsn

PromQL — per-DB durable LSN (прогресс checkpoint по БД, RM-0.6.7.12):

# durable LSN конкретной пользовательской БД
angarabase_wal_durable_lsn{db="orders"}

# БД, чей durable_lsn не двигался 5 мин (checkpoint stall):
# ВНИМАНИЕ: метрика обновляется только на per-DB checkpoint, поэтому для
# idle-БД (без write) значение тоже не меняется — это НЕ stall. Сопоставляйте
# с активностью записи (напр. с ростом angarabase_transaction_log_bytes_appended_total).
changes(angarabase_wal_durable_lsn[5m]) == 0

PromQL — восстановление строк при последнем старте (S2):

# Instant value показывает итог последнего recovery pass
angarabase_wal_redo_heap_rows_reconstructed_total

Note: Метрики angarabase_wal_redo_heap_* инкрементируются только во время WAL redo pass при старте после некорректного завершения (SIGKILL/crash). В стабильном состоянии (steady state) их значения не меняются.

Storage и buffer pool

PromQL — Buffer pool hit ratio:

rate(angarabase_buffer_pool_hit_total[5m]) /
  (rate(angarabase_buffer_pool_hit_total[5m]) + rate(angarabase_buffer_pool_miss_total[5m]))

Checkpoint и bgwriter

SQL — состояние bgwriter:

SELECT * FROM angara_stat_bgwriter;

PromQL — checkpoint avg duration:

rate(angarabase_checkpoint_duration_ms_sum[5m]) / rate(angarabase_checkpoint_duration_ms_count[5m])

PromQL — интенсивность материализации overlay (S1):

# Индикатор давления на HeapStore со стороны overlay-слоев
rate(angarabase_overlay_flush_on_checkpoint_slots_total[5m])

Query execution

PromQL — P99 latency:

histogram_quantile(0.99,
  rate(angarabase_query_exec_duration_ms_bucket[5m])
)

SQL — медленные запросы:

SELECT query, calls, mean_exec_time_ms, max_exec_time_ms
FROM angara_stat_statements
ORDER BY mean_exec_time_ms DESC LIMIT 10;

Memory

QoS Scheduler

Troubleshooting by Dashboard

Маршрут 1: Высокий P99 latency

angarabase_query_exec_duration_ms P99 > 500ms?
  │
  ├─ Да → angara_stat_activity: есть waiting sessions?
  │        │
  │        ├─ Да (wait_event != '') → Lock contention или WAL sync wait
  │        │   → смотреть angarabase_txn_commit_conflicts_total
  │        │   → смотреть angarabase_wal_sync_wait_total
  │        │
  │        └─ Нет → angara_stat_statements: top queries by max_exec_time_ms
  │            → EXPLAIN на топ-запрос
  │            → проверить buffer_pool_miss_total rate (I/O bound?)
  │
  └─ Нет → baseline нормальный, false alarm

SQL:

SELECT query, calls, max_exec_time_ms, mean_exec_time_ms
FROM angara_stat_statements
ORDER BY max_exec_time_ms DESC LIMIT 5;

Маршрут 2: QPS Drop (внезапное падение SELECT rate)

rate(angarabase_query_exec_total_ok_select[1m]) резко упал?
  │
  ├─ connections_active тоже упал → процесс restarted? uptime < 60s?
  │   → смотреть логи на panic / OOM / segfault
  │
  ├─ connections_active высокий, QPS низкий → scheduler saturation?
  │   → qos_rejected_* > 0?
  │   → qos_blocking_inflight высокий?
  │   → spawn_blocking_active ≈ spawn_blocking_max?
  │
  └─ Connections нормальные → долгая транзакция блокирует?
      → angara_stat_activity WHERE state = 'idle in transaction'
      → txn_oldest_snapshot_age_seconds > 60s?

Маршрут 3: GC Pressure / MVCC bloat

mvcc_history_versions_total монотонно растёт без снижения?
  │
  ├─ txn_oldest_snapshot_age_seconds > 120s → долгий открытый snapshot
  │   → найти pid из angara_stat_activity ORDER BY query_start ASC
  │   → завершить или дождаться завершения
  │
  ├─ columnar_pending_deleted_rows > 1M → compaction lagging
  │   → проверить Background Compactor в angara_stat_activity
  │   → временно SET angarabase.compaction_enabled = true
  │
  └─ memory_rss_bytes растёт вместе → GC bloat + memory pressure
      → смотреть mvcc-gc.md runbook

Маршрут 4: Checkpoint Issues

checkpoint_errors_total изменился?
  │
  ├─ Да → немедленно смотреть логи (disk full? I/O error?)
  │   → storage_backpressure_events_total > 0?
  │   → df -h на data directory
  │
  └─ Нет, но dirty_pages_total высокий (> 10 000)?
      → checkpoint не поспевает за writes
      → снизить checkpoint_interval_ms
      → или ограничить write throughput
      → SQL: SELECT * FROM angara_stat_bgwriter;

Memory and Buffer Pool Metrics (RM-0.6.5.8)

Goal

Держать минимально достаточный набор сигналов для:

• durability;
• concurrency/locks;
• storage/checkpoint;
• recovery.

Metrics source

• ANGARABASE_METRICS_ADDR=host:port
• endpoint: GET /metrics (Prometheus format)

Must-have groups

• Transactions / concurrency
• Transaction log / durability
• Locks
• Storage / writeback / checkpoint
• Query diagnostics / stats
• Recovery / replay outcomes

Memory and Buffer Pool Metrics (RM-0.6.5.8)

PromQL — Алерт при приближении к soft limit:

# Замените <soft_limit_bytes> на значение soft_limit_mb * 1024 * 1024
# Например, для soft_limit_mb = 4096: порог = 4294967296
angarabase_memory_rss_bytes > <soft_limit_bytes> * 0.9

Storage and Checkpoint Metrics (RM-0.6.5.8)

Visibility Map and Index-Only Scan (RM-0.6.4.3)

Конкретные имена метрик с привязкой к dashboard-панелям: см. таблицу Полный contract имён фиксируется тестом, ссылка ниже в «Contract pinning».

Новые метрики RM-0.6.4.0 (WAL Commit-Path + Durability)

Добавлены в Sprint 2/3 RM-0.6.4.0 (RFC-2026-090). Покрывают новый режим sync_at_commit и группу durability barrier.

curl -sf http://127.0.0.1:9898/metrics | rg "wal_(sync_wait|group_commit_wait)|wait_events_total\\{event=\"wal_"

Диагностика по режиму

• relaxed: wal_sync_wait_total и wal_group_commit_wait_total близки к 0.
• group_commit: растёт wal_group_commit_wait_total; wal_sync_wait_total обычно заметно ниже.
• sync_at_commit / strict: растёт wal_sync_wait_total; wait_events_total{event="wal_sync"} отражает долговременную нагрузку sync-path.

Режим durability проверяется через env ANGARABASE_TRANSACTION_LOG_DURABILITY. SQL SET durability / COMMIT WITH DURABILITY зарезервированы для v0.6.5 → SQLSTATE 0A000. Подробнее: WAL writer contract spec (wal_writer_contract_v0.md) и RFC-2026-090.

HTAP / Vector Execution Metrics (RM-0.6.4.13 / RM-0.6.4.14 / RM-0.6.6.9)

HTAP-специфичные метрики для диагностики векторного и stream-пути выполнения. Контракт меток стабильный начиная с v0.6.x.

curl -sf http://127.0.0.1:9898/metrics | grep -E "scan_stream|vector_fallback|vector_memory|columnar_manifest|vector_columnar_native|columnar_batched_scan|segments_pruned|parallel_agg|vector_numeric_float_backed|vector_columnar_grouped_agg"

Примечание: метки reason= у angarabase_scan_stream_materialize_total — стабильный оператор-facing контракт в рамках v0.6.x.

Columnar DV Pressure (RM-0.6.4.19 Track C C2)

angarabase_columnar_pending_deleted_rows — signed gauge, показывающий суммарное количество логически удалённых строк в живых сегментах, ещё не reclaimed compaction.

• Increment при AttachDeleteVector (при каждом columnar DELETE): +row_count из DV op.
• Decrement при compact_l0_to_l1: -rows_reclaimed по числу строк, не вошедших в L1 pack.

В норме gauge растёт после DELETE и снижается после Background Compactor runа. Если gauge монотонно растёт — compaction lagging или compaction полностью отключён.

curl -sf http://127.0.0.1:9898/metrics | rg "pending_deleted_rows"

Alert правило (DV fragmentation)

# Alert если накопленный DV pressure > 5 млн строк.
angarabase_columnar_pending_deleted_rows > 5_000_000

Рекомендуемые severity:

• warning при превышении >1M строк — compaction, вероятно, отстаёт;
• critical при превышении >10M строк — возможна деградация scan performance.

Интерпретация:

• gauge ≤ 0 — нормально (все DV reclaimed, возможно небольшой transient underflow при replay);
• gauge растёт без уменьшения > 30 минут — проверьте Background Compactor (angara_stat_activity, angarabase_columnar_compaction_total).

Heap fetch fallback reason metrics (RM-0.6.5.6)

• angarabase_heap_point_fetch_fallback_reason_stale_tid_index_total — fallback из-за stale tid index
• angarabase_heap_point_fetch_fallback_reason_not_found_total — fallback из-за row not found

Быстрая проверка (curl):

curl -s http://localhost:8080/metrics | grep "fallback_reason"
# angarabase_heap_point_fetch_fallback_reason_stale_tid_index_total 0
# angarabase_heap_point_fetch_fallback_reason_not_found_total 0

PromQL — rate fallback по причинам:

rate(angarabase_heap_point_fetch_fallback_reason_stale_tid_index_total[5m])
rate(angarabase_heap_point_fetch_fallback_reason_not_found_total[5m])

Если stale_tid_index растёт — возможна проблема с V3 chain path или index rebuild. Если not_found растёт — возможна потеря данных или баг в MVCC visibility.

QoS Scheduler и spawn_blocking (RM-0.6.4.10 / RM-0.6.4.19)

RM-0.6.4.10 добавляет runtime-сигналы для QoS scheduler и blocking path. Они помогают отличать SQL contention от scheduler saturation: если растут QoS rejections или qos_blocking, проблема находится в очередях выполнения, а не в row/table locks.

curl -sf http://127.0.0.1:9898/metrics | rg "qos_(queued|rejected|blocking)|spawn_blocking"

Очереди QoS по уровням:

rate({__name__=~"angarabase_qos_queued_.*_total"}[5m])

Отказы QoS по уровням:

rate({__name__=~"angarabase_qos_rejected_.*_total"}[5m])

Alert на любой отказ scheduler:

sum(rate({__name__=~"angarabase_qos_rejected_.*_total"}[5m])) > 0

Blocking pressure:

angarabase_qos_blocking_inflight > 0

Запас blocking budget:

angarabase_spawn_blocking_max - angarabase_spawn_blocking_active

Интерпретация:

• растёт queued_background_total, но нет rejected_* — scheduler принимает batch workload, обычно это нормальная картина;
• растёт rejected_background_total — batch/ETL слишком агрессивен, снижайте concurrency или повышайте ANGARABASE_QOS_MAX_QUEUED;
• растёт rejected_critical_total — это production incident candidate: CRITICAL workload не должен регулярно упираться в queue cap;
• qos_blocking_inflight > 0 вместе with ростом qos_blocking wait event означает pressure в blocking runtime path.

Query Execution Duration Histogram (RM-0.6.5.10)

angarabase_query_exec_duration_ms — histogram задержки выполнения SQL-запросов.

Note (RM-0.6.5.10 S6): histogram_quantile(0.99) корректен только если значение < 10 000ms. При p99 ≥ 10 000ms смотреть долю в bucket +Inf. Buckets: [1,5,10,50,100,500,1000,2500,5000,10000,+Inf] ms.

SLO-oriented usage

• Latency: histogram_quantile() по *_bucket (p95/p99)
• Throughput: rate() по counters
• Errors/contention: conflict/timeout/deadlock rates
• Saturation: backpressure counters and queue depth

Contract pinning

Имена must-have метрик считаются частью operability contract и защищаются тестом:

• crates/angarabase/src/metrics.rs
• prometheus_export_contains_must_have_metrics_names

Дальше

• Performance tuning guide — какие метрики читать в первую очередь при деградации.
• Parallel runtime observability runbook — узкоспецифичные метрики параллельного рантайма.
• MVCC and GC operator minimum — отдельный пакет MVCC/GC-метрик и алертов.

Materialized View Metrics

Online DDL Metrics

Метрики статистики (RM-0.6.7.2)