Files
mtusi2026lab6/openspec/changes/otel-telemetry/proposal.md
T
2026-11-11 05:51:59 +03:00

10 KiB
Raw Blame History

Proposal

Why

Лаба 6, уровень «3» рубрики README.md: найти причину деградации можно только по наблюдениям, а их у стенда нет — есть JSON-журнал в stdout каждого контейнера, и всё. Нужны отдельный OTel Collector, хранилища трёх сигналов с историей, Grafana с provisioning из git и SDK в API и worker с сигналами contracts/observability.md уровня 3: метрики HTTP и заданий, логи с trace_id / span_id, реальные трассы. Это первое из четырёх изменений пути к оценке 5 (PLAN.md); уровень 4 (перенос контекста через брокер, насыщение, SLO и alerts) и трек 1 «Цена наблюдаемости» опираются на него. Попутно закрывается дефект переноса: стенд из чистого clone не поднимается одной командой (KNOWN_ISSUES.md, «Первый старт RabbitMQ»), а это шаг 1 сценария защиты.

What Changes

  • Стенд наблюдаемости в рабочем compose: OTel Collector (дистрибутив contrib), Prometheus (метрики), Loki (логи), Tempo (трассы) — отдельными сервисами с именованными volumes и сроком хранения 7 суток, Grafana — интерфейс без собственного состояния. Хранилища и Grafana — в своей сети, недоступной контейнерам приложения; наружу — только Grafana на 127.0.0.1 с паролем администратора из make env_setup. Образы — тег и digest индекса, лимиты CPU и памяти у всех. Конфигурации — в git (infra/otel/), provisioning источников и dashboard — без ручного импорта.
  • SDK OpenTelemetry в API и worker: OTLP (HTTP, protobuf) только в Collector, ресурс service.name (messenger-api, messenger-worker), service.version, service.instance.id (= X-Instance-Id), deployment.environment.name=lab. Настройки — новая секция [telemetry]; имена skeleton OTEL_* сопоставляются ей, а не читаются SDK. Экспорт в фоне, очереди ограничены: без Collector, при его зависании и при остановке процесса запросы, задания и сроки остановки прежние.
  • Сигналы уровня 3: histogram длительности HTTP (метод, шаблон маршрута, код статуса; без health) и обработки заданий (тип, исход); server span запроса и consumer span задания с дочерними span PostgreSQL, Valkey, S3 и процесса обработки; логи API и worker — те же записи, что в stdout, ещё и в Loki, с trace_id и span_id; переход лог ↔ трасса в Grafana.
  • Запреты в телеметрии: id сущностей, сырой путь и filename — не метки метрик; пароли, токены, Authorization, Idempotency-Key, тела, текст, байты и секреты — нигде; в span — без текста исключений.
  • Dashboard уровня 3 в git: RPS, ошибки и длительность API, успешные и ошибочные задания, длительность worker, логи и трассы.
  • Проверки: команда драйвера telemetry-check (свой запрос: X-Request-Id → лог в Loki → трасса в Tempo; загрузка → лог и трасса worker; метрики; provisioning; проба приватности; история после рестарта хранилищ), telemetry-outage (make test и остановка API и worker при остановленном и замороженном Collector), stand-from-scratch (make run_docker на пустых volumes дважды, своим проектом compose). Evidence — evidence/telemetry/, evidence/stand/.
  • Стенд с нуля одной командой: healthcheck брокера — от пользователя брокера, а не root (KNOWN_ISSUES.md); запись дефекта закрывается.
  • Стенды без телеметрии по умолчанию: консоль, make test_isolated, стенд отказов и bench/ — SDK выключен, их методика и бюджеты прежние; выключатель — одна настройка (вариант «off» трека 1). Override CI — новые конфиги через configs, без портов хоста.

Не входит: перенос контекста через outbox и брокер, publish span, SDK у relay и уборщика; метрики очереди, пула, насыщения и CPU/RAM процессов; время до ready; p99 и доля ошибок как панели уровня 4; SLO, alerts и runbooks; настройка ограниченных очередей и повторов Collector сверх memory_limiter и batch; потери телеметрии при отказе хранилища; sampling и профиль трека 1; TLS и аутентификация OTLP (лаба 7); длинные замеры исключений сверки (последний шаг лабы).

Не меняются: бизнес-API и контракт (contracts/), tests/, README.md, COURSE.md, lab.json, CONTRIBUTING.md, MAINTAINERS.md.

Шаг оператора: make env_setup (его зовёт make run_docker) дописывает в существующий .env GRAFANA_ADMIN_PASSWORD (случайный) и GRAFANA_OUT_PORT; config.toml остаётся рабочим — секция [telemetry] берёт значения по умолчанию.

Capabilities

New Capabilities

  • observability: конвейер телеметрии стенда (Collector, хранилища метрик, логов и трасс, Grafana с provisioning), SDK и ресурс API и worker, сигналы уровня 3 (метрики HTTP и заданий, трассы), запреты в телеметрии, проверка «свой запрос найден», где телеметрия включена, что описывает REPORT.md.

Modified Capabilities

  • container-run: состав стенда и независимость приложения от сервисов телеметрии, первый запуск на пустых volumes с первой попытки, порт Grafana только на 127.0.0.1, лимиты и секреты новых сервисов, volumes проекта.
  • service-logging: связь записи журнала с трассой (trace_id, span_id) и отправка тех же записей в хранилище логов.
  • service-configuration: секция [telemetry], запись о старте, соответствие имён OTEL_* skeleton.
  • graceful-shutdown: остановка API и worker в прежний срок при недоступном или замороженном Collector.

Impact

  • API и контракт: не меняются; ответы, коды и заголовки прежние. Входящий traceparent клиента API игнорирует.
  • Код: новый пакет src/infra/telemetry/; src/infra/logger.py (экспорт записей и поля трассы), src/main.py (запуск и остановка SDK, service.version), src/api/middlewares/request_context.py (server span и метрика HTTP), src/infra/db/ (span запросов и фиксации), src/infra/cache/client.py, src/infra/s3/client.py, src/infra/render/client.py (дочерние span), src/worker/main.py (consumer span, метрика, остановка), src/core/services/attachment_processing.py и src/schemas/enums/ (исход доставки для метрик), src/config/settings.py, src/utils/constants.py. Миграций нет.
  • Зависимости: opentelemetry-api, opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http 1.45.x (с ними protobuf, requests); библиотек автоинструментирования нет.
  • Стенд: docker-compose.yml (пять сервисов, сеть telemetry, три volume, healthcheck брокера), infra/otel/, .env.example, Makefile (env_setup, wipe_data), .github/ci/, bench/bench.compose.yml и bench/run.py, student-tests/failures.compose.yml и student-tests/run_isolated.py, config_example.toml.
  • Тесты и инструменты: service-tests/ (модуль телеметрии на in-memory экспортёрах, span БД на временной базе, исход доставки worker), драйвер скилла run-mtusi-messenger (три команды).
  • Документы: .claude/rules/ (новое telemetry.md; docker.md, infra.md, logging.md, settings.md, run-modes.md, worker.md, bench.md, student-tests.md), AGENTS.md, REPORT.md (разделы наблюдаемости), QUESTIONS.md, KNOWN_ISSUES.md.
  • Ресурсы: начальные лимиты новых сервисов — 2,5 CPU и 2048 МиБ; постоянные лимиты стенда — 11,5 CPU и 7040 МиБ при ВМ 12 CPU и 7,75 ГиБ (лимиты, не резерв: простой стека телеметрии на пробе — ~0,5 ГиБ); пики под нагрузкой и итоговые лимиты — замер в apply. Цена SDK в репликах и worker — замер в apply, её исследование — трек 1.