Runbook: `CommitLatencyTuning`

Sources of truth:

RM-0.6.3.10 (Track B S11/S12/S13) — group-commit baseline.

RM-0.6.4.0 (Sprint 2/3) — WAL contract, SyncAtCommit mode.

Что означает

Runbook для ситуации, когда COMMIT latency выше ожидаемой либо нестабильна между одинаковыми нагрузками (single-client cron jobs, batch DML, mixed RW).

После RM-0.6.4.0 введён режим sync_at_commit (alias strict): каждый COMMIT принудительно fsync-ирует WAL перед подтверждением. Это добавляет новые режимы в таблицу ожидаемых latency.

Режимы durability (RM-0.6.4.0+)

Настраиваются через ANGARABASE_TRANSACTION_LOG_DURABILITY (env).

Режим	Env значение	Характеристика	Применение
Relaxed	`relaxed`	WAL буферизуется, без fsync per commit	Dev/bench только
Group commit	`group_commit`	WAL pump коалесцирует и fsync по батчу	Production (по умолчанию)
Sync at commit	`sync_at_commit` или `strict`	fsync на каждом COMMIT	Банки, финансы, max durability

Важно: SET [LOCAL] durability = ... и COMMIT WITH DURABILITY = ... зарезервированы для v0.6.5 и возвращают SQLSTATE 0A000 feature_not_supported. Для конфигурации используйте env.

Базовые ожидания по latency

Режим	Условие	Ожидание (ориентир)
`relaxed`	`fsync=false`	sub-ms COMMIT; не для production
`group_commit`	`fsync=false`	COMMIT ~0.1–5 ms; батчи сглаживают spikes
`group_commit`	`fsync=true`	COMMIT 2–20 ms; доминирует диск
`sync_at_commit`	NVMe	COMMIT 1–5 ms per tx (один fsync)
`sync_at_commit`	HDD	COMMIT 5–20+ ms per tx

Если p50 или p99 существенно выше диапазона, проверяй диагностический блок ниже.

Какие метрики смотреть

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

curl -sf http://127.0.0.1:9898/metrics | rg "wal_commit|wal_durability|wal_barrier"

Метрика	Смысл
`angarabase_wal_commit_fsync_total`	Число fsync вызовов WAL writer (рост = активный sync)
`angarabase_wal_durability_epoch`	Монотонный счётчик эпох durability barrier
`angarabase_wal_barrier_wait_total`	Число транзакций ожидавших durability barrier
`angarabase_wal_barrier_duration_seconds`	Гистограмма времени ожидания barrier

Базовые метрики (group commit / write path)

curl -sf http://127.0.0.1:9898/metrics | rg "write_path_phase_b|group_commit|transaction_log"

Метрика	Смысл
`angarabase_write_path_phase_b_duration_seconds`	Гистограмма фазы B (commit hot-path)
`angarabase_write_path_phase_b_timeout_total`	Таймауты фазы B — должен быть низким
`angarabase_group_commit_batches_total`	Число батчей pump
`angarabase_group_commit_batch_size`	Распределение размеров батча
`angarabase_transaction_log_group_commit_pumps_total`	Число прогонов pump
`angarabase_transaction_log_group_commit_pump_duration_ms`	Длительность одного pump

Быстрая диагностика

# Новые WAL метрики (RM-0.6.4.0)
curl -sf http://127.0.0.1:9898/metrics | rg "wal_(commit|durability|barrier)"
# Group commit baseline
curl -sf http://127.0.0.1:9898/metrics | rg "write_path_phase_b|group_commit|transaction_log_group_commit"
# I/O correlate
iostat -xm 1 5

Если iostat показывает высокий await/util и одновременно растут *_pump_duration_ms и p99 COMMIT, проблема почти всегда в I/O слое.

При sync_at_commit: если angarabase_wal_commit_fsync_total растёт пропорционально tx rate — режим работает корректно. Если rate несоразмерно высок, проверить wal_barrier_duration_seconds на наличие stall.

Тюнинг-порядок

Подтверди режим durability (ANGARABASE_TRANSACTION_LOG_DURABILITY) и целевой SLA.
Для sync_at_commit: убедись, что WAL файлы на NVMe / отдельном шпинделе.
Проверь, не ушёл ли workload в burst: сравни tx-rate и batch-size histogram.
Для production сначала стабилизируй диск, затем подбирай group_commit_interval_ms.
Для bench/dev допускается relaxed, но фиксируй это в отчёте.

DML-coverage check

Для triage полезно подтвердить, что latency-аномалия не маскирует regression:

INSERT INTO t(...) VALUES (..., now()) — должен успешно проходить.
UPDATE t SET x = x + 1 WHERE ... — выражение должно применяться.
UPDATE/DELETE в autocommit и в txn должны возвращать корректный row count.

Эскалация

Если fsync=true и p99 COMMIT > 200 ms более 10 минут — эскалировать как durability-risk инцидент.
Если wal_barrier_duration_seconds p99 > 50 ms при sync_at_commit — проверить I/O stall.
Если errors_total > 0 в TPC-B-lite smoke — стоп на performance claims до устранения correctness.

AngaraBook