Files
mtusi2026lab6/docs/runbook.md

92 lines
7.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Runbook: лабораторная 6
Открыть [dashboard](http://localhost:3000/d/messenger-lab6). Выбрать время инцидента,
а не только последние пять минут. Все шаги диагностики ниже используют сохранённые
Prometheus/Loki/Tempo данные. Команды управления выполняются **после** диагноза.
Внешняя доставка alerts не настроена: состояние проверяется в Prometheus через
Grafana datasource proxy (`research/observations.py`).
## api
1. Проверить `API 5xx / all business requests`, RPS и p95/p99. Health и ошибочный
пароль не являются серверными 5xx. Посмотреть обе пары burn rate: 2m/30s и 6m/1m.
2. В Explore → Loki выполнить
`{service_name="messenger-api"} | json | status >= 500`.
По `request_id` найти ответ пользователя; скопировать `trace_id` или нажать TraceID.
3. В Tempo открыть trace. Развернуть server span и `postgresql.transaction`:
медленный `postgresql.SELECT/INSERT` с `error.type=_WaitTimeout` и длительностью
около 2s указывает на срабатывание I/O timeout ожидания PostgreSQL. Если сервер
успел вернуть `LockNotAvailable`, дополнительно подтверждена блокировка.
По одному `_WaitTimeout` нельзя отличить SQL lock от других причин медленной БД.
Это отличается от медленного handler:
при нём server span длинный, а DB spans короткие. `db.pool{state="used"}`
показывает занятые соединения, `waiting` — ожидание свободного соединения.
Наш эксперимент блокирует только messages, поэтому health остаётся успешным.
4. После определения причины дождаться окончания ограниченного failpoint.
Для досрочного восстановления своего учебного эксперимента:
```sh
docker compose exec -T postgres psql -U messenger -d messenger -c \
"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE application_name='lab6-incident'"
```
5. Проверить успешные записи, короткие DB spans и спад error ratio.
Alert должен перейти firing → inactive (resolved); long-window ratio может
оставаться высоким, но short window уже должен очищаться. Состояния измеряются
раз в 5s; не объявлять recovery по одному успешному запросу.
## ready
1. Проверить `Outstanding jobs` и `Oldest unfinished job age`. Это очередь
незавершённых **durable jobs в БД**, включая outbox/retry/processing;
длина Redis Stream сама по себе не отражает всю принятую работу.
2. Сопоставить worker capacity/busy, process CPU/RSS и rate успешных jobs.
Если capacity исчезла, successful jobs остановились, а acceptance продолжается
и backlog/age растут — worker не обрабатывает очередь. После 30s устаревшие
gauge series удаляются Collector; краткое сохранение старого значения допустимо.
3. В Loki:
`{service_name="messenger-api"} | json | event="attachment.accepted"`.
Открыть trace: виден API → `attachments publish`, но в интервале простоя
нет нового `attachments process`. После восстановления в том же trace появятся
consumer → S3 GET/PUT → PostgreSQL UPDATE. Retry — отдельные producer/consumer
spans с возрастающим `job.attempt` и логом `job.retry`.
4. Восстановить worker: `docker compose start worker`.
5. Проверить уменьшение backlog до 0, age до 0, возврат successful jobs и capacity.
Ready SLO остаётся нарушенным для опоздавших заданий: позднее ready не превращает
уже нарушенный 30s deadline в успешный. Дождаться resolved в обеих парах окон.
## telemetry
1. Проверить `up{job="collector"}`, `otelcol_exporter_queue_size` и
`otelcol_exporter_send_failed_log_records_total`. Ошибки экспортёра сами по себе
не равны числу окончательно потерянных записей: возможны retries.
2. При живом Collector и ошибках только `otlphttp/loki` проверить доступность
datasource Loki. Если API принимает сообщения и метрики/traces приходят,
это отдельный отказ хранилища логов, а не отказ бизнес-API.
3. Восстановить `docker compose start loki`. Collector ограничен 256 MiB,
memory limiter 192 MiB, очередь каждого экспортёра — 64 batch, максимальный
batch 128 records, retry не дольше 15s. SDK очереди traces/logs — по 256 записей;
сеть работает в фоновых потоках. При исчерпании лимитов telemetry теряется.
4. Проверить возобновление Loki ingestion и опустошение exporter queue.
В `lab6-checks.json` число потерянных request logs считается по известным
request IDs после восстановления, отдельно от счётчиков неудачных экспортов.
## SLO и интерпретация
- API: ≥99% business responses за скользящий час без 5xx. 4xx входят в
denominator, но не numerator. Отказы LB/сети до API требуют внешнего probe
и этим SLI не покрываются.
- Изображения: ≥95% accepted jobs готовы за ≤30s; cohort оценивается после
истечения deadline. Failed и не завершившиеся задания входят в bad.
Скользящее окно — час **созревших** cohorts (acceptance сдвинута на 30s).
- Fast burn: 6× бюджета одновременно за 2m и 30s, `for: 15s`.
Slow burn: 3× за 6m и 1m, `for: 30s`. Это учебные окна для 1h SLO,
а не механически перенесённые production окна для 30 дней.
- Guards: ≥30 API requests / ≥5 mature jobs в long window и ≥2 события в short.
Нет данных — нет утверждения об успешном SLO; проверять scrape и traffic.
- `APIHighErrorRate` — single-window comparator (5%/30s, for 5s),
`AttachmentQueueLag` — отдельный эксплуатационный warning (>20s, for 10s).
Сравнивать их с burn alerts, а не считать любой warning доказательством
исчерпания бюджета. Данные одного короткого эксперимента не доказывают
соблюдение SLO в течение полного часа или отсутствие ложных срабатываний вообще.