Files
mtusi2026lab6/openspec/changes/otel-telemetry/tasks.md
T
ricoromaandClaude Opus 5.5 68f1e9794e fix: address otel-telemetry verify findings
Shutdown budget leaves room for SDK shutdown, stand-from-scratch accepts only
its throwaway project, OTLP exporters ignore proxy environment, telemetry-check
covers log/trace links, health series and worker instance id; spec deltas
match what the parser and SDK lifetime allow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 10:54:14 +03:00

30 KiB
Raw Blame History

Tasks

Решения — design.md (номера в скобках), требования — specs/. Стенд — проект mtusi-lab6. Известно и не чинится здесь: до последнего шага лабы make student_test красный ровно одним test_exclusion_evidence_exists (10 файлов evidence, QUESTIONS.md). Замеры для отчёта — с закоммиченного кода, коммиты делает основная сессия.

1. Правило слоя, версии и зависимости

  • 1.1 Прочитать (Read) правила docker.md, infra.md, logging.md, settings.md, run-modes.md, worker.md, api-layer.md, service-layer.md, service-tests.md, bench.md, student-tests.md, balancer.md; создать .claude/rules/telemetry.md с paths: ["src/infra/telemetry/**", "infra/otel/**"] — решения 2–4, 8, 10–18 в форме правил (что легко нарушить: правило корня, OTEL_*, запреты атрибутов, срок закрытия, файлы вместо каталогов для CI) — и строку в таблице правил AGENTS.md. Проверка: файл есть, фронтматтер — как у соседних правил, строка в таблице.
  • 1.2 Перепроверить кандидатов (1): docker buildx imagetools inspect для otel/opentelemetry-collector-contrib:0.164.0, prom/prometheus:v3.15.1, grafana/loki:3.7.9, grafana/tempo:3.1.1, grafana/grafana:13.3.1; вышедшие позже патчи тех же линий — по правилу решения 1. Проверка: digest в docker-compose.yml равен строке Digest: вывода, выбор — в разделе «Уточнения apply» design.
  • 1.3 uv add opentelemetry-api, opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http с ограничением >=1.45.2,<1.46 и комментарием в pyproject.toml (API логов Python без стабильного имени, библиотек автоинструментирования нет — решение 4). Проверка: uv lock --check; uv run python -c "import opentelemetry.sdk._logs, opentelemetry.exporter.otlp.proto.http"; в uv.lock нет opentelemetry-instrumentation; образ собирается (docker compose build api).

2. Настройки и шаблоны

  • 2.1 Секция Telemetry в src/config/settings.py и поле telemetry (8): enabled, otlp_endpoint (валидатор схемы, хоста, порта, без пути и query), environment, metric_export_interval_seconds, export_timeout_seconds, max_queue_size, max_export_batch_size (не больше очереди), schedule_delay_seconds; float — allow_inf_nan=False. Константы в src/utils/constants.py: имена сервисов, SERVICE_VERSION = "1.6.0", имена метрик и атрибутов, границы buckets (10, 11), TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS, окно фильтра записей SDK. Проверка: uv run python -c "from src.config import settings; print(settings.telemetry.enabled, settings.telemetry.otlp_endpoint)"; запуск с TELEMETRY__OTLP_ENDPOINT=collector:4318, TELEMETRY__METRIC_EXPORT_INTERVAL_SECONDS=-1, пакетом больше очереди и inf — ошибка проверки с именем поля (сценарий «Неверный параметр телеметрии»).
  • 2.2 config_example.toml — секция [telemetry] с интервалами и очередями, без enabled и адреса; .env.example — GRAFANA_ADMIN_PASSWORD= и GRAFANA_OUT_PORT=3000 с комментариями, в шапке — соответствие имён OTEL_* (8); Makefile — GRAFANA_ADMIN_PASSWORD в ENV_SECRETS и ENV_FILLED (openssl rand -hex 16), в запросе wipe_data — «и хранилищ телеметрии». Проверка: make env_setup на временной копии .env без этих строк дописывает обе под комментарием и печатает только имена; повтор ничего не дописывает; git diff шаблона без значений секретов.

3. Пакет src/infra/telemetry/

  • 3.1 Запуск и закрытие (8, 9, 13): запуск по имени сервиса — при выключенной телеметрии ничего; при включённой — удаление OTEL_* из окружения с warning по именам, ресурс из четырёх атрибутов, провайдеры трасс, метрик и логов с явными параметрами (sampler ALWAYS_ON, лимиты span, очереди, сроки, headers={}, без сжатия, cumulative, View границ, без exemplars, shutdown_on_exit=False), хуки журнала. Закрытие — shutdown() провайдеров в daemon-потоке и ожидание не дольше срока. Проверка — тесты 8.1 (выключено, OTEL_*, ресурс, закрытие с блокирующим экспортёром не дольше срока).
  • 3.2 Дочерний span (4, 12): создаётся только под записывающим родителем, ошибка — статус ERROR и error.type без текста исключения. Проверка — тест 8.1 «правило корня».
  • 3.3 PostgreSQL (12): instrument_engine(engine) — слушатели before_cursor_execute, after_cursor_execute, handle_error с атрибутами решения 12; span COMMIT в SqlAlchemyUnitOfWork._commit; фабрика engine о телеметрии не знает. Проверка — тест 8.3 на временной базе.
  • 3.4 Журнал (2, 12): в src/infra/logger.py — хуки в processors и foreign_pre_chain (экспорт записи, затем trace_id и span_id активного span в stdout), без импорта SDK; экспорт — в пакете телеметрии (тело, уровень, время, атрибуты по типам, контекст; записи opentelemetry.* не экспортируются); фильтр частоты записей opentelemetry.* в stdout. Проверка — тесты 8.1 (разбор записи, поля трассы, traceback записи uvicorn.error, записи SDK); при выключенной телеметрии записи stdout побайтно прежние по полям (тест).

4. API

  • 4.1 RequestContextMiddleware (10): server span и histogram http.server.request.duration — не для health; имя после маршрутизации; метод со стандартным набором и _OTHER; http.route — тот же полный шаблон, что в итоговой записи; messenger.request_id; входящий traceparent не извлекается; 5xx и исключение — ERROR, error.type; итоговая запись — внутри span. Проверка — тесты 8.1 (атрибуты, _OTHER, health, 5xx, traceparent); make run_dev + make test — PASS.
  • 4.2 src/main.py (9, 13): FastAPI(version=SERVICE_VERSION); в lifespan после early_stop.disarm() — запуск телеметрии messenger-api и instrument_engine глобального engine; «Started API» — telemetry_enabled, telemetry_endpoint, telemetry_environment (сценарий «Включение окружением», запись о старте); после «Stopped API» — закрытие SDK со сроком TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS. Проверка: make run_dev — запись о старте «выключена»; на стенде — «включена» с адресом Collector; остановка — 11.2.
  • 4.3 Span клиентов (12): Cache.get / Cache.set (messenger.cache.result), ObjectStorage._call (S3.<Операция>, без ключа, StoredObjectMissing у HEAD — не ошибка). Проверка — тест 8.1 (фейковый клиент под родителем и без него); трасса запроса и задания в 11.1.

5. Worker

  • 5.1 Исход доставки (11): enum в src/schemas/enums/ (ready, failed, retry, skipped, requeued, dropped) с действием с сообщением; AttachmentProcessingService.handle и его ветки возвращают исход; быстрые тесты сервиса (test_attachment_processing.py) проверяют исход каждой ветки вместо ACK, а исход → действие, span и histogram — test_telemetry.py. Проверка: make service_test.
  • 5.2 src/worker/main.py (11, 13): запуск телеметрии messenger-worker после early_stop.disarm(), instrument_engine; в _handle после места конкуренции — span CONSUMER process <очередь> и histogram messenger.job.duration по исходу (error при исключении), подтверждение внутри span; «Started worker» — поля телеметрии; закрытие SDK в окне 0,5 с вместе с gather (худший случай — 9,5 с). Проверка — тест 8.2; остановка — 11.2.
  • 5.3 Span процесса обработки в ImageRenderer.render (12): размер входа, исход, код выхода, пик памяти; окружение процесса по-прежнему без OTEL_* и адреса Collector. Проверка: трасса задания в 11.1; driver.py --port <LB> worker-process — PASS.

6. Конфигурации наблюдаемости и стенд

  • 6.1 infra/otel/collector.yaml (14): только OTLP HTTP, memory_limiter, batch, prometheus, otlp_http/loki, otlp_http/tempo, внутренние метрики на :8888, без расширений. Проверка: подкоманда validate бинарника Collector на этом файле — без ошибок; в журнале старта нет deprecated.
  • 6.2 infra/otel/prometheus/prometheus.yml, infra/otel/loki/loki.yaml, infra/otel/tempo/tempo.yaml (15). Проверка: promtool check config в образе Prometheus; -verify-config Loki; Tempo стартует без ошибок; срок хранения 7 суток виден в /config Loki и /status/config Tempo, retention — во флагах Prometheus (/api/v1/status/flags).
  • 6.3 Grafana (16): infra/otel/grafana/datasources.yaml, dashboards.yaml, dashboards/messenger-overview.json — источники с uid prometheus, loki, tempo и ссылками лог ↔ трасса, папка Messenger, панели уровня 3 из решения 16. Проверка — шаги provisioning в 11.1 (источники, их проверка, dashboard provisioned, запросы панелей без ошибок и с данными).
  • 6.4 docker-compose.yml (7, 8, 14–18): сервисы otel-collector, prometheus, loki, tempo, grafana — образ с digest, команда, каждый конфиг — отдельный bind mount файла длинной записью (read_only, create_host_path: false), volumes prometheus_data, loki_data, tempo_data, tmpfs Grafana, GOMEMLIMIT, лимиты решения 7, healthcheck решения 18, restart: unless-stopped; сеть telemetry; порт Grafana 127.0.0.1:${GRAFANA_OUT_PORT:-3000}; GF_* решения 16; якорь x-telemetry-env у api и worker; сервисы приложения без depends_on на телеметрию. Проверка: docker compose --env-file .env config --quiet; сценарии container-run «Адрес публикации», «Секреты по сервисам», «Лимиты у всех контейнеров» — docker port, docker compose config, docker inspect по всем контейнерам.
  • 6.5 Healthcheck брокера через gosu rabbitmq (19). Проверка — 11.3 (RestartCount брокера 0 на пустом volume дважды).
  • 6.6 Override CI (20): .github/ci/compose.yml — configs для семи новых файлов; у Prometheus, Loki и Tempo — volumes: !override только с именованным volume (как у брокера), у Collector и Grafana — volumes: !reset [] (tmpfs Grafana остаётся); ports: !reset [] у Grafana; .github/ci/stand-env.sh — переменные CI_* этих файлов. Проверка: с COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml и . .github/ci/stand-env.sh — docker compose config --quiet, в полном config у сервисов телеметрии нет bind mount и опубликованных портов.
  • 6.7 Стенды без телеметрии (20): TELEMETRY__ENABLED: "false" у api и worker в bench/bench.compose.yml и student-tests/failures.compose.yml; GRAFANA_ADMIN_PASSWORD в compose_env bench/run.py; -e TELEMETRY__ENABLED=false у API и worker student-tests/run_isolated.py. Проверка: make bench_quick (рабочий стенд остановлен) проходит, в stand.app_env паспорта — TELEMETRY__ENABLED=false; стенды отказов и временной базы — 11.5.
  • 6.8 Поднять стенд: make run_docker; все сервисы работают, цели Prometheus up = 1, /api/health Grafana — 200, в журнале старта Grafana нет обращений к grafana.com, в журнале Collector, Loki и Tempo нет ошибок. Проверка: сценарий «Стенд с телеметрией» (observability).

7. Драйвер скилла run-mtusi-messenger

  • 7.1 driver.py --port <LB> telemetry-check (21): Grafana API с паролем из .env (вход: без учётных данных и с неверным паролем — 401, с верным — 200; источники по uid и их проверка; dashboard provisioned, сохранение изменённого отклоняется; запросы панелей без ошибок); свой запрос → Loki → Tempo, ресурс, совпадение записи Loki со stdout реплики; ответы 401 и 404 и запросы с BREW, путём с UUID и traceparent; загрузка → ready → лог и трасса worker; недекодируемый JPEG → исход failed; рост _count по обеим репликам; S3 заморожен → 503 и span с ошибкой (unpause в finally); трасс health и корней-span PostgreSQL нет; из контейнера API Loki, Tempo, Prometheus и Grafana недоступны, Collector доступен; разовый контейнер API с OTEL_SDK_DISABLED=true и чужим OTEL_EXPORTER_OTLP_ENDPOINT всё равно шлёт в Collector и пишет warning с именами; проба приватности (U, P, T, M, K, F, Bearer , Basic , запрещённые метки, UUID в значениях); docker compose restart Collector и хранилищ → те же наблюдения снова. Таблица «шаг → ожидаемо → получено», коды 0 / 1 / 2, секретов в выводе нет; раздел в SKILL.md. Проверка — 11.1.
  • 7.2 driver.py --port <LB> telemetry-outage (21): Collector stop → make test, загрузка до ready, записи SDK об отказе за минуту, docker stop одной реплики и docker compose stop worker (время, код, «Stopped API», «Stopped worker»), make replicas, docker compose start worker; то же при pause; все сервисы телеметрии остановлены → реплики и worker перезапущены → стартуют, make test — PASS; после возврата — сигналы приходят снова; восстановление в finally; раздел в SKILL.md. Проверка — 11.2.
  • 7.3 driver.py stand-from-scratch [--runs 2] (21): проект mtusi-lab6-scratch (mtusi-lab6 — код 2), свободные порты хоста для APP_OUT_PORT, POSTGRES_OUT_PORT, VALKEY_OUT_PORT, S3_OUT_PORT, RABBITMQ_OUT_PORT, GRAFANA_OUT_PORT, make run_docker с COMPOSE_PROJECT_NAME; код 0 с первой попытки, состояния сервисов, RestartCount брокера и хранилищ телеметрии 0, нет eacces и permission denied в журналах, provisioning Grafana, make test через свой LB; затем свой проект убирается вместе с volumes изнутри скрипта, в том числе при сбое и Ctrl+C; раздел в SKILL.md. Проверка — 11.3.

8. Быстрые тесты

  • 8.1 service-tests/unit/test_telemetry.py на in-memory экспортёрах SDK, без сети: выключенная телеметрия — ни провайдеров, ни хуков, записи stdout прежние; OTEL_* удалены и названы в warning без значений; ресурс; middleware — имя, атрибуты, _OTHER, health без span и метрики, 5xx — ERROR без текста исключения, traceparent не продолжен; запись журнала — тело, уровень, атрибуты, trace_id и span_id в stdout, traceback записи uvicorn.error в экспорте, записи opentelemetry.* не экспортируются и прорежены; правило корня; span Valkey и S3; закрытие с блокирующим экспортёром не дольше срока. Проверка: make service_test.
  • 8.2 Исход доставки → span CONSUMER и histogram с messenger.job.outcome для каждого исхода, включая error (test_worker_deliveries.py или новый модуль). Проверка: make service_test.
  • 8.3 service-tests/db/: span запросов и COMMIT под родителем в асинхронной сессии на временной базе, без родителя — ни одного span (проверка контекста greenlet). Проверка: make service_test_db.

9. Документы

  • 9.1 Правила: docker.md (сервисы, сеть, healthcheck, суммы, секреты, брокер), infra.md (пакет телеметрии, span в клиентах), api-layer.md (middleware), logging.md (экспорт и поля трассы, записи SDK), settings.md ([telemetry], OTEL_*), run-modes.md (консоль, остановка со сроком SDK), worker.md (consumer span, исход доставки), bench.md и student-tests.md (телеметрия выключена, GRAFANA_ADMIN_PASSWORD для разбора compose). Проверка: в каждом правиле — ссылка на design change и нет пересказа спека.
  • 9.2 AGENTS.md: абзац о состоянии лабы, таблица важных файлов (contracts/observability.md, infra/otel/), карта кода (src/infra/telemetry/, infra/otel/, evidence/telemetry/, evidence/stand/), команды драйвера, число записей KNOWN_ISSUES.md. Проверка: grep новых путей в AGENTS.md.
  • 9.3 REPORT.md по требованию «Наблюдаемость в отчёте» (observability): назначение Collector и хранилищ, версии, таблица сигналов «контракт → SDK → Prometheus / Loki / Tempo → единица», запросы панелей, доля ошибок и исходы заданий, соответствие ресурса меткам и OTEL_* настройкам, сумма лимитов и замер, ограничения; строки таблицы инфраструктуры для пяти сервисов. Проверка: сценарий «Отчёт по наблюдаемости».
  • 9.4 QUESTIONS.md, раздел ## otel-telemetry — решения и вопросы apply; design — «Уточнения apply» с отклонениями от решений. Проверка: каждое отклонение названо там.

10. Бюджет

  • 10.1 Замер (7): docker stats и memory.peak сервисов телеметрии, реплики API и worker в простое и под make test + make load с включённой телеметрией и с выключенной (TELEMETRY__ENABLED=false у тех же контейнеров); лимит каждого сервиса телеметрии — не меньше 1,5 × пика, иначе поднять и пересчитать суммы; реплика API в своём лимите. Проверка: evidence/telemetry/budget.md, суммы в docker.md и REPORT.md совпадают с docker inspect.

11. Проверки на стенде

  • 11.1 driver.py --port 8080 telemetry-check → код 0, вывод в evidence/telemetry/check.md. Проверка: сценарии observability (кроме отказов Collector), service-logging «Записи запроса ведут к трассе», «Записи задания ведут к трассе», «Запись в Loki совпадает со stdout», service-configuration «Переменные OTEL_* не действуют».
  • 11.2 driver.py --port 8080 telemetry-outage → код 0, вывод в evidence/telemetry/collector-outage.md. Проверка: сценарии «Collector остановлен», «Collector заморожен», «Отказ отправки журнала», container-run «Приложение без телеметрии», graceful-shutdown «docker stop при остановленном Collector» и «…при замороженном Collector».
  • 11.3 driver.py stand-from-scratch --runs 2 → код 0, вывод в evidence/stand/from-scratch.md; после него — удалить запись «Первый старт RabbitMQ…» из KNOWN_ISSUES.md. Проверка: сценарий «Стенд с нуля одной командой»; рабочий стенд — прежние ID контейнеров.
  • 11.4 Консоль: make run_dev и make test — PASS, запись о старте «телеметрия выключена», в записях нет trace_id, к 127.0.0.1:4318 обращений нет. Проверка: сценарии «Консоль без телеметрии», «Телеметрия по умолчанию выключена».
  • 11.5 Регрессия: make lint; make service_test; make service_test_db; make test и make student_test через LB (красный только test_exclusion_evidence_exists); make test-persistence ACTION_SCRIPT=scripts/restart.sh — PASS и прежнее StartedAt у сервисов телеметрии; make test_isolated и make failure_checks — прежние результаты, в «Started API» их API телеметрия выключена; docker compose config --quiet — рабочий стенд, CI, bench/, стенд отказов. Проверка: выводы команд; причины любых падений — в отчёте apply до правок.
  • 11.6 graphify update . после закрытия задач. Проверка: в графе есть узлы src/infra/telemetry.

12. Замечания проверки

Находки /opsx:verify (2026-11-11), которые решено исправить. Evidence переснимается отдельной стадией на коммите правок.

  • 12.1 W2. Дельта observability, сценарий «Необычный метод и неизвестный путь»: метод вне стандартного набора, который пропускает HTTP-парсер (PROPFIND), и явное ограничение для методов, которые парсер отклоняет до приложения (BREW, KNOWN_ISSUES.md); telemetry-check проверяет сценарий в новой формулировке — рост ряда _OTHER 404 без http_route и ряда GET 404 без http_route от своих запросов, ни PROPFIND, ни UUID в метках. Проверка: openspec validate otel-telemetry --strict; шаги telemetry-check — expected = got.
  • 12.2 W3. Проверка настроек: при включённой телеметрии [app] graceful_shutdown_seconds + TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS не больше бюджета остановки API (9 с: SIGKILL docker через 10 с), иначе запуск останавливается ошибкой с именем поля; у worker — тот же расчёт его окна (закрытие SDK внутри окна gather 0,5 с, сумма 9,5 с < 10 с). Дельта graceful-shutdown — требование и сценарий неверного сочетания; выбор — design, «Уточнения apply». Проверка: быстрый тест service-tests/unit/test_settings.py (9 + телеметрия — ошибка с полем, 9 без телеметрии и 8 с ней — допустимо, окно worker); make service_test.
  • 12.3 W4. driver.py stand-from-scratch --project: только имя ^mtusi-lab6-scratch(-[a-z0-9]+)?$, иначе код 2 до любых действий docker; строка в SKILL.md; вопрос пользователю о down -v своего проекта — QUESTIONS.md. Проверка: driver.py stand-from-scratch --project с mtusi-lab5, mtusi-lab6-failures, bp_proxies, mtusi-lab6 — код 2 и ни одного вызова docker (запуск с PATH без docker и DOCKER_HOST на несуществующий сокет).
  • 12.4 S1. telemetry-check, сценарий «От лога к трассе и обратно»: запрос к Loki через Grafana по подстановке tracesToLogsV2 источника Tempo (infra/otel/grafana/datasources.yaml) с реальным trace_id возвращает записи запроса; у источника Loki derived field trace_id ведёт в источник tempo. Проверка: шаги telemetry-check — expected = got.
  • 12.5 S2. telemetry-check: рядов Prometheus с http_route=~"/health.*" нет; service.instance.id ресурса трассы задания равен instance_id записи worker в stdout. Проверка: шаги telemetry-check — expected = got.
  • 12.6 S3. Дельта service-logging, «Журнал в хранилище логов»: отправляются записи между запуском и закрытием SDK; записи до запуска и после закрытия — только stdout. Проверка: openspec validate otel-telemetry --strict.
  • 12.7 S5. Экспортёры OTLP получают свою requests.Session с trust_env=False: HTTP(S)_PROXY и NO_PROXY окружения на отправку не влияют, данные идут только в Collector. Проверка: быстрый тест в service-tests/unit/test_telemetry.py test_exporters_ignore_proxy_environment: с HTTP(S)_PROXY в окружении отправка трёх экспортёров уходит на адрес Collector без прокси, requests.Session.send подменён — сети нет); make service_test.
  • 12.8 S6. Память ВМ в design (решение 7) — 7934 МиБ, как в docker.md и REPORT.md; ссылка задачи 5.1 — на фактические файлы тестов. Проверка: grep -n 7936 по change — пусто.
  • 12.9 Не исправлять, записать: QUESTIONS.md, ## otel-telemetry, «Предложения на потом» — evidence «Restart hook не трогает телеметрию» (S2) и загрузка SDK relay и уборщиком через SqlAlchemyUnitOfWork (S4). Проверка: подраздел есть.
  • 12.10 Регрессия: openspec validate otel-telemetry --strict, make lint, make service_test, make service_test_db, пересборка и docker compose up -d api и worker, make test, make student_test через LB (красный только test_exclusion_evidence_exists), driver.py --port 8080 telemetry-check — код 0 (вывод в scratchpad; evidence — следующая стадия на коммите).