Files
mtusi2026lab6/docs/runbook.md
T

78 lines
8.1 KiB
Markdown
Raw 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: alerts и инциденты lab6
Правила — `infra/prometheus/alerts.yml`, состояние — Grafana → Alerting (источник Prometheus) или
`docker compose exec -T prometheus wget -qO- http://localhost:9090/api/v1/alerts`. Dashboard —
Grafana → «Messenger — API, worker, очередь» (provisioning, uid `messenger-lab6`).
Порядок всегда один: **метрика** (что и насколько сломано) → **лог** (какая операция, request_id/job_id) →
**trace** (в каком span теряется время или возникает ошибка) → проверка зависимости → восстановление → проверка resolved.
## ApiAvailabilityFastBurn / ApiAvailabilitySlowBurn / ApiHighErrorRate
Смысл: доля 5xx среди бизнес-запросов (без `/health/*`) выше нормы. Fast burn (14.4×, окна 2m30s + 30s) — острый
отказ, нужен немедленный ответ; slow burn (6×, 15m + 1m30s) — длительная частичная деградация; ApiHighErrorRate —
простой порог 5 % за 1 мин, реагирует и на короткие всплески (см. REPORT.md, трек 2).
1. Панель «API: запросы/с по маршруту и классу статуса»: какие маршруты дают 5xx, все или один.
```promql
sum by (http_route, http_response_status_code) (rate(http_server_request_duration_seconds_count{job="messenger-api", http_response_status_code=~"5.."}[5m]))
sum by (instance) (rate(http_server_request_duration_seconds_count{job="messenger-api", http_response_status_code=~"5.."}[5m]))
```
Одна реплика (`instance`) → проблема процесса/контейнера; все реплики и один маршрут → зависимость этого маршрута.
2. Логи ошибок (панель логов или Explore → Loki):
```logql
{service_name="messenger-api"} | event="http.request" | http_response_status_code=~"5.."
{service_name="messenger-api"} | detected_level="error"
```
В записи есть `request_id` (тот же, что в заголовке `X-Request-Id` и в теле ошибки) и `trace_id` → ссылка в Tempo.
3. Trace (Explore → Tempo, TraceQL): `{ resource.service.name = "messenger-api" && status = error }`. Смотрим, какой
дочерний span красный: JDBC (PostgreSQL), `GET`/`SET` Redis, `S3.PutObject`/`GetObject` (SeaweedFS), `attachments publish`
(RabbitMQ).
4. Проверить зависимость: `docker compose ps`; для БД — `db_client_connections_pending_requests` на панели «Пул соединений БД»,
для брокера — `docker compose exec rabbitmq rabbitmq-diagnostics -q check_port_connectivity`.
5. Особый случай учебного стенда: `http_route` пустой/`unmatched`, нет дочерних span, тело `injected fault` — это
инъекция `X-Fault-Inject: http-500` (работает только при `FAULT_INJECTION=1`), а не дефект кода.
6. Восстановление: поднять зависимость (`docker compose start <service>`), убедиться, что доля 5xx на панели падает; fast burn
гаснет через ~30–60 с, slow burn — через ~1–2 мин (короткое окно), ApiHighErrorRate — через ~1 мин.
## QueueLagHigh / WorkerAbsent / TimeToReady*
Смысл: QueueLagHigh — старейшее queued-задание ждёт > 60 с (gauge из таблицы `jobs`, отдают API и worker);
WorkerAbsent — метрик worker нет 1 мин; TimeToReadyFast/SlowBurn — вложения становятся ready дольше 10 с
(считается при ready, поэтому при полностью остановленном worker молчит и срабатывает уже на разборе backlog).
1. Панель «Очередь: глубина и возраст самого старого задания»: возраст растёт линейно, глубина растёт → задания не забирают.
2. WorkerAbsent тоже firing → процесс worker не жив: `docker compose ps worker`, `docker compose logs --tail=50 worker`
(OOM, ошибка старта, healthcheck). Не firing → worker жив, но не успевает или не получает сообщения:
- «Worker: занятость (busy / capacity)» около 1 → насыщение; «Worker: длительность попытки p95» выросла → медленная обработка
(S3, размер картинок, CPU-лимит контейнера);
- занятость около 0 при растущей очереди → сообщения не доходят: `docker compose exec rabbitmq rabbitmqctl list_queues name messages consumers`,
в логах API `outbox relay paused` (брокер недоступен, outbox копится в БД);
- `{service_name="messenger-worker"} | event=~"job.retry|job.failed"` — задания падают и уходят в backoff.
3. По одному заданию: в логе worker `job <job_id> attempt N …` → trace_id → trace от `POST /api/v1/chats/{id}/attachments`
через `attachments publish` до `attachments.process process` и S3/JDBC; повторные попытки — дочерние span той же трассы.
Статус задания: `docker compose --profile tools run --rm jobctl status`.
4. Восстановление: `docker compose start worker` (или устранить причину из п. 2). Проверка: глубина → 0, QueueLagHigh и
WorkerAbsent resolved; TimeToReady* может кратко сработать на разборе backlog и погаснуть по короткому окну.
## Медленная БД (p99 растёт, 5xx нет)
Признак: на «API: длительность p50/p95/p99» p99 вырос, доля 5xx нет; `db_client_connections_pending_requests` > 0 или
`usage{state="used"}` у предела пула.
1. Tempo: `{ resource.service.name = "messenger-api" && duration > 2s }`. Если почти вся длительность SERVER span — это
один JDBC span (`INSERT messenger.messages` и т. п.) — ждём БД; если JDBC span короткие, а SERVER длинный — медленный
код обработчика/внешний вызов.
2. В БД: `docker compose exec -T postgres psql -U messenger -d messenger -c "select pid, wait_event_type, wait_event, now()-xact_start as xact, left(query,60) from pg_stat_activity where datname='messenger' and state<>'idle'"` —
блокировка (`Lock`), долгая транзакция; `select pg_terminate_backend(<pid>)` для зависшей сессии.
3. Проверка: p99 возвращается к норме, pending = 0.
## Недоступен backend телеметрии (Loki/Tempo/Prometheus)
Признак: в Grafana ошибки источника, пустые панели логов/трасс; API отвечает нормально.
1. `docker compose ps loki tempo prometheus`; метрики Collector (если жив Prometheus):
`otelcol_exporter_queue_size`, `otelcol_exporter_send_failed_spans_total`, `otelcol_exporter_send_failed_log_records_total`,
`otelcol_exporter_enqueue_failed_*`.
2. Collector держит очередь ≤ 500 батчей на exporter и повторяет ≤ 60 с, `memory_limiter` (180 MiB) ограничивает память:
данные дольше этого окна теряются и учитываются в `send_failed`/`enqueue_failed`; бизнес-запросы от этого не зависят.
3. Восстановление: `docker compose start loki tempo`; новые логи/трассы появляются через ~10–20 с; пропуск в истории не
восстанавливается.