Files
mtusi2026lab6/docs/runbooks.md

124 lines
10 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.
# Runbooks алертов (lab6)
Правила — `infra/prometheus/rules/alerts.yml`, unit-тесты правил — `infra/prometheus/tests/alerts_test.yml`.
Состояние алертов: http://127.0.0.1:9090/alerts или Grafana → Alerting → Alert rules (data source rules).
Dashboard: Grafana http://127.0.0.1:3000 → Messenger → «Messenger — lab6 observability».
Общий порядок: **метрика говорит «что и когда», трасса — «где именно», лог — «почему»**.
Ссылки на трассу из лога: Grafana → Explore → Loki → запись → поле `trace_id` → «Открыть трассу».
Из спана в логи: Tempo → спан → «Logs for this span» (запрос по `trace_id`).
---
## MessengerHighErrorRate
**Что значит.** Больше 5% бизнес-запросов API (без `/health/*`) за минуту закончились 5xx, дольше минуты,
при трафике > 0,2 запроса/с. 4xx (неверный пароль, чужой чат) сюда не входят.
**Влияние.** Пользователи получают 503/500, SLO-1 (99% без 5xx за час) расходует бюджет в 5+ раз быстрее нормы.
**Найти причину.**
1. Какие маршруты и коды: dashboard «RPS по классу статуса» или
`sum by (http_route, http_response_status_code) (rate(http_server_request_duration_seconds_count{job="messenger-api", http_response_status_class="5xx"}[1m]))`.
503 — недоступна зависимость, 500 — ошибка кода.
2. Медленная БД или медленный обработчик:
- `histogram_quantile(0.95, sum by (le) (rate(db_client_connection_wait_time_seconds_bucket[1m])))` и
`db_client_connection_pending_requests` — запросы ждут соединение из пула → соединения заняты долгими запросами;
- Tempo, TraceQL `{ resource.service.name = "messenger-api" && status = error }` → открыть трассу:
если почти всё время server-спана занимает дочерний спан `INSERT`/`SELECT` (PostgreSQL) с ошибкой —
проблема в БД; если время в `argon2id hash`/`inspect image` или «пустое» время самого server-спана — в обработчике;
`redis GET` с ошибкой — Redis; `S3 PutObject` — SeaweedFS.
3. Логи API: `{service_name="messenger-api"} | event="db.unavailable"` (поле `error_type`: `QueryCanceled` —
statement_timeout 5 с, `PoolTimeout` — нет свободного соединения 3 с, `OperationalError` — БД недоступна);
`| event="redis.unavailable"`, `| event="s3.unavailable"`.
4. В PostgreSQL (если трассы указывают на БД): `docker compose exec postgres psql -U messenger -d messenger -c
"SELECT pid, state, wait_event_type, wait_event, now()-query_start AS age, left(query,60) FROM pg_stat_activity
WHERE datname='messenger' ORDER BY age DESC"` — блокировки (`wait_event_type = Lock`) и долгие запросы.
**Исправить.** Снять блокировку/долгий запрос (`pg_terminate_backend(pid)`), восстановить зависимость
(`docker compose start postgres|redis|s3`). Не перезапускать API «на всякий случай»: причина не в нём.
**Проверить восстановление.** Доля 5xx на dashboard → 0, алерт становится inactive через ~1–2 минуты
(окно rate 1m). Пример разбора: REPORT.md, инцидент 2.
---
## MessengerQueueLagGrowing
**Что значит.** Старейшее задание обработки вложения, которое уже можно брать (статус `queued`,
`available_at` прошёл), ждёт больше 30 с дольше минуты. Пока задания не забирают, возраст растёт линейно.
**Влияние.** Вложения остаются `queued`, клиенты не получают превью; SLO-3 (95% ready ≤ 30 с) нарушается.
**Найти причину.**
1. `messenger_queue_consumers{messaging_destination_name="attachments.process.v1"}` = 0 → worker не подключён
(см. MessengerWorkerNoConsumers). > 0 → worker есть, но не успевает или падает на заданиях.
2. Насыщение worker: `sum(messenger_worker_busy) / sum(messenger_worker_capacity)` ≈ 1 и растёт
`messenger_queue_depth` → нужно больше потоков/реплик worker (`WORKER_CONCURRENCY`, `--scale worker=2`).
3. Ошибки обработки: `sum by (outcome) (rate(messenger_job_duration_seconds_count[5m]))` — много `retry`/`failed`;
логи `{service_name="messenger-worker"} | event=~"job.retry|job.failed"` (поле `error_type`).
4. Отличить от проблемы публикации: `messenger_outbox_oldest_age_seconds` большой → сообщения не доходят до
брокера (dispatcher/RabbitMQ), а не worker; лог `{service_name="messenger-dispatcher"} | event="broker.unavailable"`.
5. Трасса любой зависшей загрузки (по `trace_id` из лога API `event="http.request"` для POST attachments):
есть `publish attachments`, но нет `process attachments.process.v1` → сообщение в брокере, его никто не взял.
**Исправить.** `docker compose start worker` (или `scripts/worker.sh start`); при насыщении — увеличить
параллелизм; при массовых ошибках — устранить их причину, затем `ops.py replay` для failed.
**Проверить восстановление.** `messenger_jobs_backlog{status="queued"}` → 0, возраст → 0, вложения `ready`,
алерт inactive через ~15–30 с. Пример: REPORT.md, инцидент 1.
---
## MessengerWorkerNoConsumers
**Что значит.** RabbitMQ дольше минуты не видит ни одного подписчика очереди `attachments.process.v1`.
**Найти причину.** `docker compose ps worker`; последние записи `{service_name="messenger-worker"}` в Loki
(`event="service.stopped"` — остановлен штатно; `event="broker.unavailable"` — не может подключиться к брокеру;
отсутствие записей и метрик `messenger_worker_capacity` — процесс не запущен).
**Исправить.** Запустить worker / восстановить RabbitMQ. Принятые задания не теряются (outbox + durable очередь).
---
## MessengerDbPoolSaturated
**Что значит.** На реплике API запросы дольше минуты ждут свободное соединение из пула (`DB_POOL_MAX`=10).
**Найти причину.** Почти всегда это следствие медленных запросов или блокировок в PostgreSQL, а не нехватки
соединений: те же шаги, что в MessengerHighErrorRate (трассы с долгими DB-спанами, `pg_stat_activity`).
Увеличивать пул имеет смысл, только если DB-спаны быстрые, а ожидание пула долгое при высоком RPS.
---
## TelemetryExportFailing
**Что значит.** Collector не может отправить данные в Tempo / Loki / Prometheus (метка `exporter`): очередь
exporter дольше минуты заполнена больше чем на 5% (хранилище не принимает), либо пакеты уже теряются —
у пакета истекло окно повторов 120 с (`send_failed`) или очередь переполнена (`enqueue_failed`). Окно повторов
считается для пакета с первой попытки, время ожидания в очереди в него не входит: очередь (200 пакетов) —
это и есть буфер на время недоступности.
**Влияние.** На пользователей не влияет. Телеметрия этого периода частично потеряна (сколько — счётчики
`otelcol_exporter_send_failed_*`, `otelcol_exporter_enqueue_failed_*`).
**Найти причину.** `docker compose ps tempo loki prometheus`; `otelcol_exporter_queue_size / otelcol_exporter_queue_capacity`;
логи Collector: `docker compose logs otel-collector --tail 50` (через Loki их не смотреть — это тот же конвейер).
**Исправить.** `docker compose start tempo loki prometheus`. Очередь Collector досылается сама (в пределах окна
повторов). Проверить: `otelcol_exporter_queue_size` → 0, свежая трасса находится. Пример: REPORT.md, инцидент 3.
---
## TelemetryCollectorDown
**Что значит.** Prometheus не может забрать метрики Collector (`up{job="otel-collector"} == 0`).
**Влияние.** Приложение работает; SDK каждого процесса держит не больше 2048 спанов и 2048 записей логов.
Потери считаются в самом процессе: пакет, который Collector не принял, — `otel_sdk_exporter_span_exported_total{error_type!=""}`
(обычно `ConnectionError`), переполнение очереди — `otel_sdk_processor_span_processed_total{error_type="queue_full"}`. Метрик приложения за
этот период нет (пропуск на графиках), cumulative-счётчики после восстановления продолжат расти без потери итогов.
**Исправить.** `docker compose start otel-collector`; проверить, что трассы и метрики снова приходят.