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