Files
mtusi2026lab6/openspec/changes/slo-alerts/proposal.md
T
2026-11-11 22:07:18 +03:00

9.0 KiB
Raw Blame History

Proposal

Why

Уровень «4» рубрики README.md лабы 6, вторая из двух частей (PLAN.md, раздел «3. slo-alerts»; решение пользователя 3). После change job-trace-propagation сигналы уровня 4 есть, но на них ничего не опирается: нет проверяемого SLI/SLO и окна, нет alert rules в git с runbooks и проверки firing / resolved искусственным отказом, а Collector экспортирует в Loki и Tempo с очередью по умолчанию (1000 пакетов без предела в байтах) и потери телеметрии нигде не считаются. Ответы, которые генерирует сам HAProxy (502, 503, 504), в метрики не попадают совсем (QUESTIONS.md, ## otel-telemetry, вопрос 4): при недоступной БД реплики выходят из LB, клиент получает 503 от LB, а доля ошибок API считается по почти нулевому знаменателю и оповещение о высокой доле ошибок гасло бы посреди отказа. Плюс замечание S1 verify change job-trace-propagation: increase() недосчитывает после перезапуска worker под тем же instance — ровно в сценарии первого инцидента (остановлен worker). Без этого нет двух инцидентов уровня 4 и третьего — недоступности хранилища телеметрии.

What Changes

  • SLI и SLO (окно — 7 суток, срок хранения Prometheus): доступность — доля ответов клиентам без 5xx на публичном frontend LB, вместе с ответами самого LB (SLO 99,5 %); задержка — доля «лёгких» запросов API не дольше 0,25 с, без KDF входа и регистрации и без передачи байтов вложений (99 %); время до ready — доля готовых вложений не дольше 30 с от устойчивого приёма (99 %). Recording rules в git, формулы PromQL и значения — в REPORT.md.
  • Метрики балансировщика. Встроенный экспортёр Prometheus HAProxy на внутреннем порту статистики; забирает его Collector (приёмник prometheus) и отдаёт в Prometheus вместе с метриками приложения — изоляция сети хранилищ прежняя.
  • Alert rules в git (правила Prometheus, без Alertmanager и без доставки наружу): высокая доля ошибок, медленные запросы, нет готовых реплик, растущий queue lag, нет снимка очереди relay, недоступна цель сбора метрик, потери телеметрии; у каждого — условие, окно, порог, for, описание и локальный runbook infra/otel/runbooks/<alert>.md. Модульные тесты правил promtool — make alerts_test (и в CI). Состояние firing / resolved — Prometheus и Grafana.
  • Счётчики после перезапуска процесса (S1): Prometheus принимает время начала cumulative-рядов (created timestamp) экспортёра Collector по protobuf и пишет ноль при новом процессе; ряды остановленного процесса экспортёр убирает через минуту, а не через пять.
  • Устойчивость телеметрии. Экспорт Collector в Loki и Tempo — очередь в памяти с пределом в байтах, повторы с пределом времени, memory_limiter прежний. Внутренние метрики SDK OpenTelemetry (потери из-за полной очереди и неудачные отправки) включаются кодом, без OTEL_*. Каждое место потери считается, сумма — recording rule, оповещение о потерях.
  • Dashboard (тот же JSON): SLO и бюджет, доли окон оповещений, история состояний оповещений, ответы LB и готовые реплики, конвейер телеметрии (очереди, потери, память Collector, цели сбора).
  • Проверки: команда драйвера alerts-check — под своей нагрузкой остановленный worker, остановленный relay, медленная БД, медленный handler для сравнения, недоступная БД: firing, затем resolved, и наблюдения для разбора инцидентов; команда backend-outage — остановка Loki, Tempo (коротко и долго), Prometheus и Collector под нагрузкой: работа API, память Collector и реплик, учёт потерь. Evidence — после коммита кода.
  • Отчёт: SLI/SLO, таблица оповещений, буферизация и потери, два инцидента — остановленный worker; медленная или недоступная БД против медленного handler — и третий — недоступное хранилище телеметрии, с шагами диагностики только по сохранённым наблюдениям; сумма лимитов и ресурсы ВМ.

Не входит: burn-rate с несколькими окнами (трек 2 не выбран), доставка оповещений наружу и Alertmanager, профиль цены телеметрии и sampling (track1-telemetry-cost), метрики PostgreSQL, S3 и брокера как процессов, новая histogram длительности запросов PostgreSQL, evidence исключений сверки покрытия последнего шага.

Не меняются: бизнес-API и контракт (contracts/), tests/, README.md, COURSE.md, lab.json; поведение API, worker, relay и уборщика вне телеметрии; настройки [telemetry] и SDK (очереди, сроки); новых сервисов compose нет.

Capabilities

New Capabilities

Нет: SLO, оповещения и устойчивость конвейера — capability observability (change otel-telemetry).

Modified Capabilities

  • observability: ответы балансировщика в метриках, SLI и SLO, правила оповещений и runbooks, проверка оповещений отказами, буферизация Collector и отказ хранилищ телеметрии, учёт потерь телеметрии, счётчики после перезапуска процесса, панели SLO, оповещений и конвейера, SLO, оповещения и инциденты в REPORT.md.
  • load-balancing: статистика балансировщика внутри сети — ещё и метрики в формате Prometheus на том же внутреннем порту.

Impact

  • API и контракт: не меняются; ответы, коды и заголовки прежние.
  • Код: src/infra/telemetry/sdk.py (внутренние метрики SDK, порядок сборки провайдеров, без гистограмм SDK), src/utils/constants.py; быстрые тесты service-tests/unit/test_telemetry.py.
  • Стенд: infra/otel/collector.yaml (очереди, повторы, приёмник HAProxy, срок рядов), infra/haproxy/haproxy.cfg (/metrics на порту статистики), infra/otel/prometheus/prometheus.yml (правила, протоколы scrape), новые infra/otel/prometheus/rules.yml, rules.test.yml, infra/otel/runbooks/, infra/otel/grafana/datasources.yaml, dashboards/messenger-overview.json, docker-compose.yml (флаг Prometheus, bind mount правил), .github/ci/compose.yml и stand-env.sh (ещё один configs), .github/workflows/application.yml (шаг make alerts_test), Makefile (alerts_test). Новых сервисов и портов нет; лимит Collector — по замеру.
  • Инструменты: драйвер скилла run-mtusi-messenger (alerts-check, backend-outage, нагрузка драйвера), SKILL.md.
  • Документы: .claude/rules/ (telemetry.md, docker.md, balancer.md), AGENTS.md, REPORT.md, QUESTIONS.md.