Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
78 lines
8.1 KiB
Markdown
78 lines
8.1 KiB
Markdown
# 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 с; пропуск в истории не
|
||
восстанавливается.
|