Files
mtusi2026lab6/PLAN.md
T

223 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План лабы 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`.