10 KiB
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]; имена skeletonOTEL_*сопоставляются ей, а не читаются 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-http1.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.