Инцидентный runbook: debug ошибок за 10 минут

Goal

Быстро локализовать причину деградации/ошибок в production: понять что ломается (logs/tracing) и где узкое место (USDT wait events + eBPF).

Prerequisites

• Запущен angarabase-server.
• Доступ к серверным логам.
• Доступ к SQL-клиенту (psql/pgwire).
• Для USDT/eBPF: Linux с поддержкой eBPF, установлен bpftrace, есть права (CAP_BPF/CAP_PERFMON или root).

Быстрый сценарий (10 минут)

Шаг 1 (0-2 мин): зафиксировать симптом и affected sessions

Проверить активные сессии и wait state:

SELECT pid, state, wait_event_type, wait_event, query
FROM angara_stat_activity
ORDER BY pid;

Если проблема массовая — сохранить снимок в инцидентный тикет/чат.

Шаг 2 (2-4 мин): понять, что именно падает или деградирует

По логам найти ERROR/WARN по времени инцидента:

rg "ERROR|WARN|panic|timeout|failed|degraded" /var/log/angarabase.log

Если включён tracing (JSON), быстро отфильтровать длинные операции:

jq 'select(.fields.duration_ms != null and .fields.duration_ms > 1000)' /var/log/angarabase.log

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

• много Lock/timeout -> вероятен contention;
• много io/fsync/wal -> вероятен storage bottleneck;
• сетевые ошибки -> вероятен Net path.

Шаг 3 (4-7 мин): снять runtime evidence через USDT probes

Проверить, что probes доступны:

bpftrace -l 'usdt:./angarabase-server:angarabase:*'

Быстрая гистограмма lock waits:

bpftrace -e 'usdt:./angarabase-server:angarabase:lock_wait_end { @lock_us = hist(arg1); } interval:s:10 { print(@lock_us); clear(@lock_us); }'

Быстрая гистограмма I/O latency:

bpftrace -e 'usdt:./angarabase-server:angarabase:io_end { @io_us = hist(arg1); } interval:s:10 { print(@io_us); clear(@io_us); }'

Быстрый срез query latency:

bpftrace -e 'usdt:./angarabase-server:angarabase:query_end { @q_us = hist(arg2); } interval:s:10 { print(@q_us); clear(@q_us); }'

Шаг 4 (7-9 мин): корреляция и гипотеза root cause

Сопоставить:

• angara_stat_activity.wait_event_type
• логи/трейсы
• USDT-гистограммы

Правило triage:

• высокий lock_wait_end + wait_event_type=Lock -> contention/serialization;
• высокий io_end + storage warnings -> disk/flush path;
• нормальный lock/io, но высокий query_end -> planner/execute CPU path.

Шаг 5 (9-10 мин): зафиксировать evidence и next action

Минимум в отчёт:

• окно времени;
• top symptoms из логов;
• 1-2 команды и их вывод (гистограммы);
• предварительный root cause;
• immediate mitigation (например, снизить нагрузку, ограничить тяжелые запросы, усилить мониторинг).

Expected result

За 10 минут есть:

• воспроизводимый evidence-пакет;
• первичная классификация инцидента (Lock/IO/Net/CPU/Scheduler);
• понятный следующий шаг для mitigation/fix.

Troubleshooting

Links

• Structured logging: Структурированное логирование
• Tracing: Tracing
• USDT probes: USDT probes
• Общая диагностика: Диагностика