223 lines
20 KiB
Markdown
223 lines
20 KiB
Markdown
# План лабы 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`.
|