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>
30 KiB
30 KiB
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 addopentelemetry-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по именам, ресурс из четырёх атрибутов, провайдеры трасс, метрик и логов с явными параметрами (samplerALWAYS_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; spanCOMMITв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 и histogramhttp.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после места конкуренции — spanCONSUMERprocess <очередь>и histogrammessenger.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-configLoki; Tempo стартует без ошибок; срок хранения 7 суток виден в/configLoki и/status/configTempo,retention— во флагах Prometheus (/api/v1/status/flags). - 6.3 Grafana (16):
infra/otel/grafana/datasources.yaml,dashboards.yaml,dashboards/messenger-overview.json— источники с uidprometheus,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), volumesprometheus_data,loki_data,tempo_data, tmpfs Grafana,GOMEMLIMIT, лимиты решения 7, healthcheck решения 18,restart: unless-stopped; сетьtelemetry; порт Grafana127.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_envbench/run.py;-e TELEMETRY__ENABLED=falseу API и workerstudent-tests/run_isolated.py. Проверка:make bench_quick(рабочий стенд остановлен) проходит, вstand.app_envпаспорта —TELEMETRY__ENABLED=false; стенды отказов и временной базы — 11.5. - 6.8 Поднять стенд:
make run_docker; все сервисы работают, цели Prometheusup= 1,/api/healthGrafana — 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 restartCollector и хранилищ → те же наблюдения снова. Таблица «шаг → ожидаемо → получено», коды 0 / 1 / 2, секретов в выводе нет; раздел вSKILL.md. Проверка — 11.1. - 7.2
driver.py --port <LB> telemetry-outage(21): Collectorstop→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проверяет сценарий в новой формулировке — рост ряда_OTHER404 безhttp_routeи рядаGET404 без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 внутри окнаgather0,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 fieldtrace_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.pytest_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 -dapi и worker,make test,make student_testчерез LB (красный толькоtest_exclusion_evidence_exists),driver.py --port 8080 telemetry-check— код 0 (вывод в scratchpad; evidence — следующая стадия на коммите).