Files
mtusi2026lab6/PLAN.md
T

20 KiB
Raw Blame History

План лабы 6: наблюдаемость

Рабочий план изменений OpenSpec лабы 6 для прогона /openspec-cycle. Задание — README.md, сигналы — contracts/observability.md, роли — contracts/infrastructure.json, что положить в infra/ — infra/otel/README.md. Перенос из лабы 5 и найденное при нём — QUESTIONS.md, «Перенос из лабы 5». После закрытия всех changes план удаляется, итоги — в REPORT.md (как в лабах 3 и 4).

Что решает пользователь

Ответы записать в QUESTIONS.md («Ответы пользователя перед прогоном») и передавать в промпт propose как решения, которые не пересматриваются.

# Решение Рекомендация Почему
1 Цель и трек 5 принято 2026-11-11: 5, трек 1 «Цена наблюдаемости» стенд bench/ уже меряет latency (k6), CPU и память по контейнерам (сэмплер), сравнивает метки; трек 2 требует долгих окон burn-rate и долгих прогонов на ложные срабатывания, их честно не уменьшить до учебного стенда
2 Хранилища принято 2026-11-11: Prometheus (метрики), Loki (логи), Tempo (трассы), отдельными сервисами все три принимают OTLP, у каждого понятная роль и свой volume; grafana/otel-lgtm одним контейнером прячет Collector и хранилища, а рубрика требует отдельный Collector и объяснить каждое хранилище
3 Уровень 4 — один change или два принято 2026-11-11: два — связь и насыщение, затем SLO, alerts и устойчивость verify каждого уже; второй опирается на метрики первого. Цена — ещё один цикл из четырёх стадий
4 Что можно без пользователя принято 2026-11-11: как в лабе 5: коммиты на feat/<change>, ff-merge в solution/bvt2301-safronov, архивация, зависимости и образы, стенд и замеры; push — в конце; PR не открывать без разрешения на коммиты цикл идёт без них (скилл openspec-cycle)
5 Длинные замеры исключений (bench_uploads ~50 мин, bench_queue ~2 ч 10 мин) принято 2026-11-11: в последнем шаге, на коде лабы 6 с включённой телеметрией на стенде mtusi-bench (уточнено 2026-11-11, вопрос 5 ## otel-telemetry) доказывают, что свойства лаб 4 и 5 сохранились вместе с телеметрией; снятые раньше пришлось бы снимать заново. Выключатель телеметрии bench/ — из change 4

Шаг 0. Перенос (без OpenSpec)

  1. Сделано 2026-11-11: ветка solution/bvt2301-safronov от main, commit переноса 9cc6c0c (источник — mtusi2026lab5-safronov, 046ec9e).
  2. Сделано: commit «до» профилей bench/ (rollout_from, uploads_before, reconcile_before) → 9cc6c0c, код успеха «до» у uploads — 202 (QUESTIONS.md).
  3. graphify update . (граф локальный, в git не идёт).
  4. Evidence исключений сверки покрытия — в последнем шаге (решение 5). До него make student_test красный ровно одним test_exclusion_evidence_exists (10 файлов, QUESTIONS.md): в промпт apply и verify — «известно, не чинить».

Changes

# Change Уровень Суть Зависит от
1 otel-telemetry 3 Collector, Prometheus, Loki, Tempo, Grafana в стенде; SDK в API и worker; сигналы уровня 3; dashboard из provisioning; первый старт с нуля шаг 0
2 job-trace-propagation 4 W3C trace context API → outbox → relay → broker → worker; время до ready; очередь, возраст старейшей job, пул БД, saturation worker; p50/p95/p99 и доля ошибок 1
3 slo-alerts 4 SLI/SLO, alert rules с runbooks, проверка firing / resolved отказами; Collector и SDK с ограниченной памятью и очередью; отказ хранилища телеметрии; два инцидента 2
4 track1-telemetry-cost 5 цена телеметрии и потери при sampling (решение 1) 3
— последний шаг — evidence исключений, полные проверки, REPORT.md 4

1. otel-telemetry (уровень 3)

Входит:

  • Стенд: отдельный OTel Collector (infra/otel/collector.yaml: OTLP receivers на внутренней сети, memory_limiter и batch уже здесь, три pipeline на реальные хранилища), Prometheus, Loki, Tempo с persistent volumes и ограниченным сроком хранения, Grafana с provisioning datasources и dashboards и dashboard JSON в git, порт Grafana только на 127.0.0.1, пароль администратора — случайный из make env_setup. Образы — тег и digest индекса, лимиты CPU/RAM у всех, healthcheck, секреты по сервисам (docker.md).
  • SDK в API (все реплики) и worker: resource attributes service.name (messenger-api, messenger-worker), service.version, service.instance.id (= instance_id, X-Instance-Id), deployment.environment.name=lab; OTLP http/protobuf в Collector. Соответствие имён skeleton OTEL_* настройкам — .env.example, settings.md, REPORT.md.
  • Сигналы уровня 3 (contracts/observability.md): HTTP requests (method, route template, status class) и duration histogram в секундах с границами под ожидаемые задержки; jobs processed / failed и job duration (job type, outcome); структурные логи с trace_id / span_id, severity, service.name, event — stdout JSON остаётся; трассы — server spans API, consumer span worker, дочерние spans БД, S3 и процесса обработки.
  • Запреты: user_id, chat_id, message_id, attachment_id, request_id, raw URL, filename, текст — не labels метрик; Authorization, пароль, токен, Idempotency-Key, тела, байты, подписи S3 — нигде в telemetry (logging.md, «Чего в логах быть не должно»).
  • Dashboard уровня 3: RPS, ошибки и duration API, успешные и ошибочные jobs, duration worker; переход лог ↔ трасса по trace_id.
  • Проверка «свой запрос найден»: команда драйвера (рабочее имя telemetry-check) — запрос с известным X-Request-Id → лог в Loki → trace_id → трасса в Tempo; upload → trace и лог worker. Проба приватности: маркеры пароля, токена и текста теста в Loki и Tempo не находятся.
  • Исправление KNOWN_ISSUES.md «Первый старт RabbitMQ на пустом volume» и сценарий «стенд с нуля одной командой»: make run_docker на пустых volumes, дважды подряд, включая новые хранилища (у non-root образов на именованных volumes бывают те же права).
  • Override CI (.github/ci/compose.yml, stand-env.sh): новые bind mount → configs, без портов хоста.
  • Стенд bench/ и стенд отказов (failure_checks) не меняют прежних бюджетов: телеметрия там выключена по умолчанию (OTEL_SDK_DISABLED или свой выбор), а включается профилем. Иначе метки прежних профилей несравнимы, а сумма лимитов bench/ упрётся в ВМ. Выключатель SDK нужен и треку 1 (вариант off).
  • make test проходит при включённой телеметрии; назначение каждого хранилища и соответствие имён SDK ↔ Prometheus — в REPORT.md.

Не входит: перенос контекста через брокер, метрики очереди, пула и saturation, alerts, SLO, настройка backpressure сверх базовых memory_limiter и batch.

Развилки для design (решает propose, записывает в design):

  • путь логов: OTLP из SDK (мост structlog / stdlib → LoggingHandler) или filelog Collector по журналам Docker (на Docker Desktop журналы внутри ВМ); рекомендация — SDK;
  • путь метрик в Prometheus: OTLP receiver Prometheus, prometheusremotewrite или scrape prometheus exporter Collector — от него зависят имена, суффиксы единиц и какие resource attributes становятся labels;
  • дистрибутив Collector: tail_sampling трека 1 есть только в contrib; с выбранным треком 1 рекомендация — contrib с первого change, чтобы варианты трека отличались настройкой, а не сборкой Collector;
  • автоинструментирование (FastAPI/ASGI без заголовков и health, SQLAlchemy async, redis, aio-pika) или ручные spans; S3 — ручной span в ObjectStorage._call (единственная точка вызова);
  • relay и cleaner: SDK сразу или в change 2 (relay нужен там для publish span);
  • scripts/restart.sh: перезапускать ли хранилища телеметрии («все хранилища» restart hook — про бизнес-данные);
  • бюджет ВМ: Docker Desktop — 12 CPU, 7,75 GiB; лимиты стенда сейчас 9,0 CPU / 4992 МБ постоянных (docker.md); пять новых сервисов дадут ~11–12 CPU и ~7 ГБ — сумма и решение в REPORT.md.

Проверки: make lint, make service_test, make service_test_db, make test и make student_test на стенде с телеметрией, make test_isolated, make failure_checks, docker compose config --quiet, стенд с нуля, evidence telemetry-check и пробы приватности, provisioning без ручного импорта (Grafana API: datasources и dashboard на месте после старта).

2. job-trace-propagation (уровень 4, часть 1)

Входит:

  • W3C traceparent / tracestate: контекст span загрузки сохраняется вместе с намерением задания (attachment_jobs, миграция только расширяет схему, migrations.md), relay публикует с заголовками и publish span, worker извлекает контекст — consumer / process span с parent или link по выбранной semantic conventions messaging (выбор и почему — в design). Каждая попытка и replay видны; по одному upload — цепочка до записи S3 и фиксации в БД, включая retry (команда драйвера, рабочее имя trace-chain, с вынужденной повторной попыткой).
  • Метрики: end-to-end время до ready (от фиксации queued до фиксации ready, histogram); queue depth и возраст старейшей незавершённой job (секунды) из одного источника — не по разу на реплику API; DB pool used / waiting по процессам; worker busy / capacity; CPU и RAM процессов или контейнеров (если Collector читает docker.sock — это цена безопасности, назвать).
  • Dashboard уровня 4: p50 / p95 / p99 через histogram_quantile по сумме buckets всех реплик (не среднее p99), доля ошибок с заранее определёнными числителем и знаменателем (5xx / бизнес-запросы без health; 4xx клиента отдельно), очередь и возраст, пул, saturation; запросы и единицы — в REPORT.md.

Не входит: alerts, SLO, устойчивость телеметрии.

Развилки: parent или link у consumer (outbox разрывает синхронную цепочку: publish идёт в другом процессе и позже); источник очереди — relay (единственный, уже считает published_backlog), receiver Collector или метрики брокера; смесь версий при make rolling_update — строки задания без контекста у прежних реплик.

3. slo-alerts (уровень 4, часть 2)

Входит:

  • Проверяемый SLI/SLO и окно: API (доступность и latency) и время до ready, формула PromQL.
  • Alert rules в git — минимум высокий error rate и растущий queue lag: условие, окно, порог, for, описание, ссылка на локальный runbook. Проверка искусственным отказом: остановить worker → firing → запустить → resolved; медленная или недоступная БД → firing → resolved; состояние из API Prometheus / Grafana с временем — в evidence. Доставка наружу не нужна.
  • Collector: memory_limiter, batch, ограниченная sending_queue, retry_on_failure с пределом времени; SDK — ограниченные очереди и сроки экспорта. Остановка каждого хранилища телеметрии и самого Collector: API и worker работают (make test), память Collector и API ограничена (замер), потери посчитаны (собственные метрики Collector otelcol_exporter_send_failed_*, otelcol_exporter_enqueue_failed_*, отказы memory_limiter) и объяснены.
  • Два инцидента в REPORT.md с шагами диагностики только по сохранённым наблюдениям: (1) остановлен worker — растёт возраст задач; (2) медленная или недоступная БД отличается от медленного handler по трассам и метрикам. Третий — недоступность хранилища телеметрии.

Развилки: правила Prometheus или Grafana-managed alerts (рекомендация — правила Prometheus: файл в git, promtool test rules); нужен ли Alertmanager (доставка не нужна — состояние firing / resolved видно без него).

4. track1-telemetry-cost (уровень 5, решение 1)

Профиль telemetry стенда bench/: одинаковая открытая нагрузка (смесь API и загрузок ниже насыщения), варианты — телеметрия выключена, полная (100 % трасс), head sampling (parentbased_traceidratio), tail sampling в Collector (ошибки, медленные, доля остальных), вариант агрегации метрик (интервал экспорта, границы buckets, лишние инструменты). Меряется p50 / p95 / p99, CPU и RAM API, worker, Collector и хранилищ, объём ingest (метрики Collector, рост хранилищ), потери spans. Редкие ошибки и медленные запросы вносятся с известным числом — по ним видно, что теряет каждый вариант. Гипотезы закоммичены до метки, повторы, A/A, сбалансированная конфигурация предложена и проверена, ограничения названы (bench.md). Включение телеметрии на стенде mtusi-bench (SDK, Collector, хранилища) делается не только для профиля telemetry: им пользуются bench_uploads и bench_queue последнего шага (решение 5), бюджет ВМ — с ним.

Трек 2 «SLO и обнаружение инцидентов» не выбран (решение 1): burn-rate alerts с несколькими окнами в changes не входят, alerts уровня 4 — пороговые (change 3).

Последний шаг (без отдельного change)

  • Evidence исключений сверки покрытия на стенде лабы 6 и коде с телеметрией: 10 файлов из QUESTIONS.md (make test_isolated и driver.py cache-check --require-test-keys, auth-storage, make test-persistence, повтор после --force-recreate api, attachment-failover оба режима, attachment-storage, broker-check и --require-test-queue, make bench_uploads, make bench_queue — оба с включённой телеметрией, решение 5) и новые исключения changes лабы 6. Метка очереди: исключение называет baseline4 — новая метка с тем же именем или правка текста исключения на новую (решить там, назвать в QUESTIONS.md).
  • Полные make failure_checks, make test_isolated, make student_test через LB, make test-persistence, make test-failover (stop и kill), CI на Gitea, проверка из чистого clone, REPORT.md целиком (шаблон skeleton), секреты в evidence — проверка.
  • Push ветки решения — по разрешению; PR — только по отдельной просьбе.

Запуск

  • Каждый change — /openspec-cycle <change>: propose (max) → apply (high) → verify (xhigh) → правки → archive (high), обычно 4 шага; ветка feat/<change> от solution/bvt2301-safronov, ff-merge обратно.
  • В промпт propose — раздел change отсюда и ответы пользователя; развилки решает design, а не этот план.
  • В промпт apply и verify: test_exclusion_evidence_exists красный до последнего шага — известно; стенд проекта mtusi-lab6; рабочий стенд перед bench/ — make stop.