Files
mtusi2026lab6/openspec/changes/slo-alerts/tasks.md
T

26 KiB
Raw Blame History

Tasks

Решения — design.md (номера в скобках), требования — specs/. Стенд — проект mtusi-lab6; make wipe_data, down -v, docker volume rm и driver.py stand-from-scratch агенту запрещены (стенд с нуля — пользователем, QUESTIONS.md, ## otel-telemetry, вопрос 8). Известно и не чинится здесь: до последнего шага лабы make student_test красный ровно одним test_exclusion_evidence_exists (10 файлов evidence, QUESTIONS.md). Evidence — только с закоммиченного кода: коммит делает основная сессия между стадиями, поэтому раздел 11 выполняется после коммита кода (apply доводит разделы 1–10, оставляет 11 неотмеченным и называет это в отчёте). Пробные прогоны команд до коммита — в scratchpad, не в evidence/. Бюджет ВМ при выборе не ограничение (решение пользователя, QUESTIONS.md, ## slo-alerts): лимит, которого требует замер, поднимается, сумма записывается.

1. Правила и константы

  • 1.1 Прочитать (Read) правила telemetry.md, docker.md, balancer.md, infra.md, logging.md, settings.md, service-tests.md, run-modes.md, bench.md, student-tests.md — до правок файлов их слоёв. Проверка: каждое прочитано через Read в этой сессии.
  • 1.2 Константы src/utils/constants.py (8): имя переменной внутренних метрик SDK, имена гистограмм SDK, которые не отдаются (otel.sdk.exporter.operation.duration, otel.sdk.metric_reader.collection.duration). Проверка: make lint.

2. SDK: внутренние метрики (8, 9)

  • 2.1 src/infra/telemetry/sdk.py: сначала MeterProvider, затем процессоры span и журнала и экспортёры OTLP span и журнала с meter_provider=; переменная внутренних метрик ставится только на время их конструирования и удаляется в finally; Views DropAggregation для гистограмм SDK; otlp_exporters разделён так, чтобы экспортёры span и журнала получали провайдер. Тестовые получатели (core.Exporters) — прежним путём. Проверка: тесты 2.2; прежние тесты test_telemetry.py зелёные (там, где считаются все метрики провайдера, — с учётом имён otel.sdk.*).
  • 2.2 Быстрые тесты service-tests/unit/test_telemetry.py без сети: очередь 2 и блокирующий экспортёр — растёт otel.sdk.processor.span.processed с error.type = queue_full; экспортёр OTLP с подставной requests.Session, которая бросает ConnectionError, — растёт otel.sdk.exporter.span.exported с error.type; то же для журнала; гистограмм SDK нет; после start() переменной в окружении нет; внешняя OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED=false удалена с warning, а метрики есть; выключенная телеметрия — ничего. Проверка: make service_test; новые тесты красные на коде до 2.1 (вывод в отчёте apply).

3. HAProxy (2)

  • 3.1 infra/haproxy/haproxy.cfg, frontend monitor: http-request use-service prometheus-exporter if { path /metrics } с комментарием (забирает только Collector, наружу не публикуется). Проверка: haproxy -c в закреплённом образе с API_PORT; после 9.3 — make lb_stats (обе реплики UP), а /metrics?scope=frontend&scope=backend изнутри контейнера LB (bash и /dev/tcp) отдаёт haproxy_frontend_http_responses_total.

4. Collector (2, 6, 7)

  • 4.1 infra/otel/collector.yaml: приёмник prometheus/haproxy (цель haproxy:8404, /metrics, scope frontend и backend, 15 с, отбор имён решения 2) в pipeline metrics; batch — send_batch_max_size: 1024, у pipeline логов — batch/logs (256 и 256); otlp_http/loki и otlp_http/tempo — timeout: 5s, sending_queue (sizer: bytes, 16 и 8 МиБ, num_consumers: 2, block_on_overflow: false), retry_on_failure (1 / 5 / 30 с); экспортёр prometheus — metric_expiration: 1m; комментарии со ссылками на решения. Проверка: validate бинарника закреплённого образа (--network none) — код 0; после 9.3 в журнале старта нет deprecated, up{job="haproxy"} = 1, ряды отбора есть.

5. Prometheus: правила, тесты, конфигурация (1, 3, 4, 6, 9, 11)

  • 5.1 infra/otel/prometheus/rules.yml: группы messenger-sli (15 с: доли окон оповещений, telemetry:lost_items:total), messenger-slo (5 мин: приращения событий трёх SLI), messenger-alerts, telemetry-alerts — правила записи и семь оповещений решения 4 с for, severity, summary, description и runbook_url; le — "0.25", "30.0". Проверка: promtool check rules (5.4).
  • 5.2 infra/otel/prometheus/rules.test.yml: на каждое оповещение — срабатывание после for, нет срабатывания ниже порога и без трафика, снятие после восстановления; MessengerQueueMetricsMissing молчит при недоступном экспортёре Collector; TelemetryDataLoss — новый ряд, рост, сброс; значения правил записи. Проверка: promtool test rules зелёный; временное изменение порога в rules.yml даёт красный прогон (вывод в отчёте apply, правка не коммитится).
  • 5.3 infra/otel/prometheus/prometheus.yml: rule_files, глобальный scrape_protocols — явно прежний текстовый список Prometheus 3, у otel-collector-exporter — [PrometheusProto, OpenMetricsText1.0.0, PrometheusText0.0.4]; docker-compose.yml: флаг --enable-feature=created-timestamp-zero-ingestion, bind mount rules.yml длинной записью; .github/ci/compose.yml — configs prometheus_rules, .github/ci/stand-env.sh — CI_PROMETHEUS_RULES. Проверка: docker compose config --quiet рабочего стенда, CI (с переменными stand-env.sh), bench/ и стенда отказов — коды 0.
  • 5.4 Цель make alerts_test (своя секция Makefile): tar файлов infra/otel/prometheus/ в одноразовый контейнер закреплённого образа Prometheus (--network none, /etc/prometheus) — promtool check config, check rules, test rules; затем каждый runbook_url — существующий файл. Шаг make alerts_test в .github/workflows/application.yml. Проверка: make alerts_test — код 0; временно переименованный runbook — ненулевой код (правка не коммитится).

6. Runbooks (5, 12)

  • 6.1 Семь файлов infra/otel/runbooks/<оповещение>.md по разделам решения 5: значение и влияние, первые панели, диагностика по сохранённым наблюдениям с запросами Prometheus, LogQL и TraceQL и ожидаемым видом результата для каждой причины, действия, проверка восстановления, связанные оповещения. Проверка: make alerts_test (ссылки); запросы runbooks выполняются через Grafana без ошибки на пробном прогоне 9.6.

7. Grafana (3, 10)

  • 7.1 infra/otel/grafana/datasources.yaml: у Prometheus manageAlerts: true. Проверка: после 9.3 API Grafana отдаёт правила источника prometheus (эндпоинт — в отчёте apply), правка их через Grafana невозможна.
  • 7.2 infra/otel/grafana/dashboards/messenger-overview.json: строки «SLO and alerts» (сверху), «Load balancer», «Telemetry pipeline» по решению 10, id с 25, у рядов, которых может не быть, — or on() vector(0), единицы; прежние панели сдвинуты вниз без изменений запросов. Проверка: python3 -m json.tool; после 9.3 и пересоздания Grafana — dashboard provisioned, обход панелей telemetry-check и trace-chain без ошибок и с данными (9.6).

8. Драйвер скилла run-mtusi-messenger (11)

  • 8.1 Фоновая нагрузка драйвера: потоки через LB (отправка сообщения с ключом, чтение истории), счёт ответов по классам и времени, остановка по событию, без печати токенов. Проверка: python3 -m py_compile системным python3; используется в 8.2 и 8.3.
  • 8.2 Команда driver.py --port <LB> alerts-check (решение 11, шаги 1–6; спеки «Проверка оповещений отказами», «SLI и SLO», «Счётчики после перезапуска процесса», «Правила оповещений»): предусловие тихого стенда (код 2), моменты pending / firing / снятия по API правил и ALERTS, наблюдения для разбора инцидентов, таблица «шаг → ожидаемо → получено», коды 0 / 1 / 2, восстановление в finally (нагрузка, сессия блокировки, PostgreSQL, worker, relay, LB). Только stdlib и синтаксис 3.9. Проверка: py_compile; --help называет команду; пробный прогон 9.6 — код 0.
  • 8.3 Команда driver.py --port <LB> backend-outage (решение 11; спеки «Буферизация Collector и отказ хранилищ телеметрии», «Учёт потерь телеметрии»): Loki и Tempo коротко и долго, Prometheus, Collector под нагрузкой; память по cgroup и метрикам Collector, потери, оповещения, сверка записей stdout и Loki; восстановление в finally. Проверка: py_compile; пробный прогон 9.6 — код 0.
  • 8.4 SKILL.md — alerts-check, backend-outage, make alerts_test. Проверка: grep -n команд по SKILL.md.

9. Стенд и регрессия (до коммита)

  • 9.1 make lint, make service_test, make service_test_db. Проверка: зелёные; причины падений — в отчёте apply до правок.
  • 9.2 Конфигурации: docker compose config --quiet (четыре варианта 5.3), haproxy -c, validate Collector, make alerts_test. Проверка: коды 0.
  • 9.3 Развёртывание (Migration Plan): HAProxy, Collector, Prometheus, Grafana, затем make rolling_update и docker compose up -d --no-deps worker relay. Проверка: make lb_stats — UP; в Prometheus все группы правил загружены без ошибок, цели up = 1, up{job="haproxy"} = 1; источники Grafana проходят проверку.
  • 9.4 Имена в Prometheus: ряды отбора HAProxy с proxy и code; внутренние метрики SDK у messenger-api, messenger-worker, messenger-relay (ёмкость очередей 2048); ёмкость очередей экспорта Collector в байтах (16 и 8 МиБ); ряды messenger-sli через ~15 с, messenger-slo — через ≤ 5 мин; число рядов экспортёра до и после перехода на protobuf без двойников. Расхождение — правка запросов и правил, запись в «Уточнения apply». Проверка: запросы через Grafana.
  • 9.5 Время начала (6): worker остановлен дольше 2 мин, загрузка, запуск — в точках messenger_job_time_to_ready_seconds_count ноль в момент старта процесса и приращение ровно на число загрузок. Проверка: вывод запроса в scratchpad (evidence — alerts-check в 11.2).
  • 9.6 Пробные прогоны (scratchpad): alerts-check, backend-outage, telemetry-check, trace-chain, telemetry-outage. Проверка: коды 0; расхождение — сначала причина, потом правка.
  • 9.7 Регрессия: make test; make student_test через LB (красный только test_exclusion_evidence_exists); make test_isolated; make failure_checks; make test-persistence ACTION_SCRIPT=scripts/restart.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh со STOP_MODE stop и kill; после каждого — нет firing, кроме ожидаемых короткими отказами (/api/v1/alerts). Проверка: выводы команд; причины падений — до правок.
  • 9.8 Бюджет (13): пики Collector (долгий отказ хранилища под нагрузкой), Prometheus (alerts-check) и реплик API (отказ Collector) по memory.peak / memory.stat и правилу «лимит ≥ 1,5 × пика»; не выполняется — лимит поднимается; суммы по docker compose config и docker inspect; сколько CPU и памяти нужно ВМ. Проверка: числа в scratchpad для 11.4; суммы совпадают с docker.md и REPORT.md.

10. Документы

  • 10.1 Правила (14): telemetry.md, docker.md, balancer.md. Проверка: в каждом — ссылка на design change slo-alerts и нет пересказа спека; docker.md называет восемь configs CI и строку ВМ.
  • 10.2 AGENTS.md: состояние лабы (третий change), таблица важных файлов, команды make alerts_test, alerts-check, backend-outage, карта кода (rules.yml, rules.test.yml, runbooks/, evidence/alerts/). Проверка: grep новых путей и команд.
  • 10.3 REPORT.md по требованию «SLO, оповещения и инциденты в отчёте»: SLI/SLO, таблица оповещений, буферизация и потери, отказы хранилищ, счётчики после перезапуска, три инцидента по решению 12, бюджет и строка ВМ, строки «Доказательства критериев»; ограничения — без «ответов балансировщика вне метрик» и с 1 мин вместо 5. Числа из evidence — в 11.5. Проверка: сценарий «Отчёт по SLO и инцидентам» после 11.5.
  • 10.4 QUESTIONS.md, раздел ## slo-alerts (создан на propose) — решения и вопросы apply; design — «Уточнения apply» с отклонениями от решений. Проверка: каждое отклонение названо там.
  • 10.5 KNOWN_ISSUES.md — дефекты, найденные попутно вне change (путь и предложение правки), если есть. Проверка: записи в формате файла.

11. Evidence (после коммита кода основной сессией)

  • 11.1 make alerts_test → evidence/alerts/rules-test.md с commit в шапке. Проверка: сценарий «Тесты правил».
  • 11.2 driver.py --port 8080 alerts-check → код 0, evidence/alerts/check.md. Проверка: сценарии «Остановленный worker», «Остановленный relay», «Медленная БД», «Медленный handler не путается с БД», «Недоступная БД», «SLO считается», «Отказ БД виден в SLI доступности», «Тяжёлая ручка вне SLI задержки», «Правила загружены», «Перезапуск worker», «Остановленный relay уходит из рядов», «Ответы самого балансировщика», «История оповещения на панели».
  • 11.3 driver.py --port 8080 backend-outage → код 0, evidence/telemetry/backend-outage.md. Проверка: сценарии «Короткий отказ хранилища», «Долгий отказ хранилища», «Отказ Prometheus», «Отказ Collector под нагрузкой», «Потери SDK при недоступном Collector», «Потери Collector при недоступном хранилище», «Без потерь».
  • 11.4 Пересъёмка на том же commit: telemetry-check → evidence/telemetry/check.md, trace-chain → evidence/telemetry/trace-chain.md, telemetry-outage → evidence/telemetry/collector-outage.md (dashboard и SDK изменились); раздел change в evidence/telemetry/budget.md (9.8). Проверка: коды 0; сценарии «Новые панели после трафика», «Метрики балансировщика без доступа к сети хранилищ», load-balancing «Метрики балансировщика»; лимиты ≥ 1,5 × пика, суммы совпадают.
  • 11.5 Числа и наблюдения инцидентов в REPORT.md из 11.2–11.4, ссылки REPORT.md и AGENTS.md на файлы evidence и их commit; graphify update .. Проверка: файлы, названные в REPORT.md, существуют; у каждого инцидента — шаги со ссылкой на строки evidence.

12. Замечания проверки (verify 2026-11-14)

Код change — commit 15ea156, evidence — 107fe7f. Находки W1–W4, S1–S5 verify; решения без пользователя — design, «Уточнения apply», пп. 17–22, и QUESTIONS.md, ## slo-alerts, «Решения apply по verify».

  • 12.1 W1, первая потеря процесса SDK на панели потерь: в rules.yml к telemetry:lost_items:total — or sum by (job, instance) (otel_sdk_processor_span_queue_capacity) * 0 (ряд процесса SDK с нуля с его запуска); TelemetryDataLoss не меняется. Тест rules.test.yml: ёмкость с начала, потеря позже — increase(telemetry:lost_items:total[5m]) равен потере, до потери ряд 0, оповещение с тем же значением. Дельта observability, «Потери SDK при недоступном Collector»: «и это видно на панели потерь»; backend-outage проверяет панель 40 (запрос A из dashboard) в шагах [tempo long] / [loki long] (Collector) и [collector] (SDK реплик). Проверка: новый тест красный на прежнем правиле (вывод в отчёте) и зелёный после; на стенде после рестарта Prometheus ряд правила есть у каждого процесса SDK со значением ≥ 0.
  • 12.2 W2: REPORT.md, формулы SLI — сверка путей описана как в ограничениях (панели 26 и 28 — по рядам правил, alerts-check — сумма increase(…[5m]) исходных счётчиков в тех же окнах и increase одним окном часа). Проверка: текст не противоречит разделу «Ограничения SLI» и sli_rows драйвера.
  • 12.3 W3: дельта observability — THEN «SLO считается» (те же 5-минутные окна; у доступности и задержки — и increase одним окном того же интервала) и «Медленный handler не путается с БД» (пул ни одной реплики не занят целиком, отказов по сроку нет, pending_requests — наблюдение); alerts-check — строка сверки SLI доступности и задержки с increase одним окном часа (≤ 1 п. п.); вопрос verify в QUESTIONS.md закрыт ответом. Проверка: openspec validate slo-alerts --strict, py_compile.
  • 12.4 W4: alerts-check печатает момент pending рядом с каждой строкой firing (worker, relay, медленная БД, недоступная БД — оба оповещения). Проверка: py_compile; в коде у каждого alert_row firing — pending_note.
  • 12.5 S1: медленная БД — firing не позже 4 мин (дельта «Медленная БД», AC_SLOW_FIRING_S = 240, комментарии драйвера). Проверка: grep срока в спеке и драйвере.
  • 12.6 S2: REPORT.md — тесты правил записи названы блоками и проверками выражений, число — после 12.1 и 12.7 (по rules.test.yml); rules-test.md — при пересъёмке (12.10). Проверка: счёт по файлу тестов.
  • 12.7 S3: description у MessengerQueueMetricsMissing — возраст последнего снимка очереди (шаблон query), у TelemetryTargetDown — up цели ($value) и число недоступных целей правила; тесты exp_annotations. Проверка: make alerts_test.
  • 12.8 S4: telemetry-check — запросы панели потерь (id 40) на тихом стенде дают 0, TelemetryDataLoss неактивно (ожидание тишины до 330 с, время ожидания печатается). Проверка: py_compile; функция на стенде — 0.
  • 12.9 S5: «Остановленный relay уходит из рядов» — опрос рядов глубины и возраста очереди; backend-outage — ёмкость очередей SDK span и журнала. Проверка: py_compile.
  • 12.10 Применение и регрессия: Prometheus и Grafana перезапущены с новыми файлами (правила загружены без ошибок, dashboard provisioned); make lint, make alerts_test, make service_test, py_compile драйвера системным python3, docker compose config --quiet, openspec validate slo-alerts --strict, make test; стенд в штатном состоянии. Проверка: коды 0, make lb_stats — UP без ручных состояний.
  • 12.11 Пересъёмка evidence на commit правок (после коммита основной сессией): make alerts_test → evidence/alerts/rules-test.md (счёт S2), alerts-check → evidence/alerts/check.md, telemetry-check → evidence/telemetry/check.md, backend-outage → evidence/telemetry/backend-outage.md; числа и ссылки на строки в REPORT.md. Проверка: коды 0; сценарии 11.1–11.3 и новые строки (панель потерь, pending, одно окно). Состояние (2026-11-14, ef60b47): rules-test.md, alerts/check.md и backend-outage.md пересняты (коды 0), REPORT.md и AGENTS.md поправлены. telemetry-check дважды дал код 1 на строке «same relay pass records in Loki» (гонка проверки драйвера: relay_pass_records ждёт первой записи в Loki, а не всех записей stdout — вторая запись прохода приходит через секунды и в Loki есть); правка драйвера в стадии пересъёмки запрещена — задача открыта, evidence/telemetry/check.md пока на 15ea156.