Files
mtusi2026lab6/monitoring/runbooks/api-availability.md
T

4.6 KiB
Raw Blame History

API availability SLO

Цель и сигналы

Объект контроля — бизнес-маршруты API за Nginx. Health endpoints исключены. Хорошими считаются ответы 2xx и ожидаемые клиентские 4xx; плохими — 5xx. Цель — не менее 99,5% хороших ответов за скользящие 30 дней, error budget равен 0,5%.

Основные сигналы:

  • messenger_http_requests_total{method,route,status_class} — число запросов;
  • messenger_http_request_duration_seconds_bucket{method,route} — распределение server latency;
  • up{job="messenger"} и up{job="nginx"} — доступность scrape targets;
  • messenger_db_pool_connections{state="used"} и rate(messenger_db_pool_waited_total[5m]) — использование пула и частота ожиданий свободного соединения;
  • trace messenger-api — путь одного запроса по зависимостям;
  • JSON-логи messenger-api с request_id, trace_id и span_id.

user_id, chat_id, message_id, attachment_id и request_id не используются как labels метрик.

Диагностика: metrics → trace → logs

  1. В Grafana открыть dashboard Messenger Lab 6 / API и установить общий временной диапазон инцидента.

  2. Проверить error ratio, RPS, p95/p99 и up. Рост 5xx при нормальном RPS подтверждает влияние на SLI; отсутствие трафика не считается успешностью.

  3. Сравнить DB pool used/waiting и состояние PostgreSQL. Рост ожидания пула указывает на зависимость, а не на CPU handler.

  4. В панели ошибок выбрать exemplar или перейти в Explore → Tempo. Если exemplar отсутствует, выполнить TraceQL:

    { resource.service.name = "messenger-api" && span.http.route != "/health/ready" && status = error }
    
  5. В trace найти первый error span. Проверить http.route, http.request.method, http.response.status_code, db.system, duration и resource attributes. Полный URL, токен и тело запроса в span отсутствуют.

  6. Скопировать trace_id, перейти по trace-to-logs или выполнить в Explore → Loki:

    {service_name="messenger-api"} | json | trace_id="<trace_id>"
    
  7. Сверить request_id, событие, severity и error class. Текст сообщений, Authorization и пароли в логах отсутствуют.

Проверка alert

Состояние правил видно в Grafana Alerting и в Prometheus:

curl -s http://127.0.0.1:9090/api/v1/alerts

Контролируемый отказ PostgreSQL:

ENV_FILE=lab6.env.example scripts/incident-database.sh

Сценарий сохраняет baseline, нагрузку, состояние деградации, alert-firing.json, восстановление и alert-resolved.json в evidence/runtime/. Trap запускает PostgreSQL и API даже при ошибке сценария. Volumes не удаляются.

Ожидаемая последовательность:

нормальный error ratio
→ PostgreSQL остановлен
→ 5xx растёт
→ MessengerAPIBusiness5xxHigh и MessengerAPIHighErrorBudgetBurnFast firing
→ PostgreSQL восстановлен
→ успешные ответы возвращаются
→ оперативный alert resolved; burn-rate хранит историю длинного окна

Действия

  1. Если up{job="nginx"}=0, восстановить ingress и проверить его логи.
  2. Если API targets недоступны, восстановить реплики по одной и проверить readiness.
  3. Если API работает, а DB spans завершаются ошибкой или pool waiting растёт, восстановить PostgreSQL и не увеличивать число API-реплик до устранения причины.
  4. После восстановления проверить успешный smoke, отсутствие firing alerts и возвращение latency к baseline.
  5. Не удалять volumes и не сбрасывать очередь ради закрытия alert.