26 KiB
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; ViewsDropAggregationдля гистограмм 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,scopefrontend и backend, 15 с, отбор имён решения 2) в pipelinemetrics;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 mountrules.ymlдлинной записью;.github/ci/compose.yml—configsprometheus_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: у PrometheusmanageAlerts: 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,validateCollector,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_MODEstopи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 changeslo-alertsи нет пересказа спека;docker.mdназывает восемьconfigsCI и строку ВМ. - 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_rowfiring —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.