20 KiB
План лабы 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)
- Сделано 2026-11-11: ветка
solution/bvt2301-safronovотmain, commit переноса9cc6c0c(источник —mtusi2026lab5-safronov,046ec9e). - Сделано: commit «до» профилей
bench/(rollout_from,uploads_before,reconcile_before) →9cc6c0c, код успеха «до» уuploads— 202 (QUESTIONS.md). graphify update .(граф локальный, в git не идёт).- 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; OTLPhttp/protobufв Collector. Соответствие имён skeletonOTEL_*настройкам —.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) илиfilelogCollector по журналам Docker (на Docker Desktop журналы внутри ВМ); рекомендация — SDK; - путь метрик в Prometheus: OTLP receiver Prometheus,
prometheusremotewriteили scrapeprometheusexporter 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 ограничена (замер), потери посчитаны (собственные метрики Collectorotelcol_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.