From ff0073e8e39abb818a771ed8af33f2995a7feb97 Mon Sep 17 00:00:00 2001 From: roman Date: Wed, 11 Nov 2026 17:38:05 +0300 Subject: [PATCH] docs: propose job-trace-propagation Co-Authored-By: Claude Opus 5.5 --- QUESTIONS.md | 52 +++ .../job-trace-propagation/.openspec.yaml | 2 + .../changes/job-trace-propagation/design.md | 434 ++++++++++++++++++ .../changes/job-trace-propagation/proposal.md | 80 ++++ .../specs/graceful-shutdown/spec.md | 33 ++ .../specs/observability/spec.md | 340 ++++++++++++++ .../specs/service-configuration/spec.md | 55 +++ .../specs/service-logging/spec.md | 71 +++ .../changes/job-trace-propagation/tasks.md | 206 +++++++++ 9 files changed, 1273 insertions(+) create mode 100644 openspec/changes/job-trace-propagation/.openspec.yaml create mode 100644 openspec/changes/job-trace-propagation/design.md create mode 100644 openspec/changes/job-trace-propagation/proposal.md create mode 100644 openspec/changes/job-trace-propagation/specs/graceful-shutdown/spec.md create mode 100644 openspec/changes/job-trace-propagation/specs/observability/spec.md create mode 100644 openspec/changes/job-trace-propagation/specs/service-configuration/spec.md create mode 100644 openspec/changes/job-trace-propagation/specs/service-logging/spec.md create mode 100644 openspec/changes/job-trace-propagation/tasks.md diff --git a/QUESTIONS.md b/QUESTIONS.md index b5bdee7..4073115 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -187,3 +187,55 @@ Change `openspec/changes/archive/2026-11-11-otel-telemetry/` (propose и арх - S4: relay и уборщик SDK не запускают, но загружают его модули через `SqlAlchemyUnitOfWork` (`src/infra/db/uow.py` → `src/infra/telemetry`): 139 модулей, RSS уборщика ~100 МиБ при ~90 МиБ в `docker.md`. Предложение для change 2: ленивый импорт SDK в `src/infra/telemetry` (до `start`) или замер `memory.peak` relay и уборщика и правка `docker.md`. + Решено в change `job-trace-propagation` (design, решение 7): ленивый импорт. + +## job-trace-propagation + +Change `openspec/changes/job-trace-propagation/` (propose 2026-11-11). Номера — решения design. + +### Решения + +- Развилки `PLAN.md` (раздел «2. `job-trace-propagation`»): + - parent или link — consumer span дочерний к контексту сообщения и с link на него (2): обработка по одному сообщению без + объемлющего span, semantic conventions messaging это допускают и требуют link; одна трасса на загрузку и цельная выборка + цепочки при head sampling трека 1. Span producer — на каждую публикацию, в клиенте брокера, дочерний к контексту загрузки, + сохранённому в задании (3, 4); + - источник очереди — relay: снимок по PostgreSQL раз в 5 с одним запросом по частичным индексам (проба — 0,31 мс), стадии + `scheduled`, `outbox`, `published`, `processing`, возраст старейшего незавершённого от устойчивого приёма (9); не + приёмник Collector (пароль PostgreSQL у Collector) и не метрики брокера (нет outbox и возраста); + - смесь версий при `make rolling_update` — строки и сообщения без контекста: span producer нет, consumer span — корень, как + на уровне 3; ни одна комбинация версий не даёт ошибки (6); + - `docker.sock` у Collector отвергнут (доступ к API Docker — root на ВМ): CPU и память — из cgroup v2 изнутри контейнеров + API, worker и relay (12). +- Carrier — заголовки AMQP `traceparent` и `tracestate`, тело сообщения по `contracts/jobs.schema.json` не меняется (1): + неверное значение в теле сделало бы сообщение «не по схеме» (`dropped`), а заголовок просто игнорируется; + `contracts/attachment-states.md` native headers допускает, отображение полей — в `REPORT.md`. +- Контекст в задании — колонки `attachment_jobs.traceparent`, `tracestate` (`text NULL`, CHECK `NOT VALID`), пишет загрузка + через зависимость API; сервис телеметрию не импортирует (4). +- Sampler — `ParentBased(ALWAYS_ON)`: при 100 % то же, флаг выборки контекста задания соблюдается; baggage не переносится (5). +- SDK в relay (`messenger-relay`); у уборщика и команды replay SDK нет; модули SDK грузятся только при запуске телеметрии — + закрывает S4 change `otel-telemetry` (проба: −322 модуля и −10 МиБ RSS) (7). +- `handle()` worker возвращает DTO итога доставки (исход, попытка, причина, код ошибки, время до готовности); время до + готовности — от записи задания до фиксации `ready`, задания после replay не учитываются (8). +- Пул — `db.client.connection.*` semantic conventions; ожидающие и отказы по сроку считает пул `CountingQueuePool` (публичный + `Pool.connect()`), фабрика engine о телеметрии не знает (10). +- Насыщение worker — занятые места, ёмкость, ожидающие места доставки и среднее за окно по сумме длительностей (11). +- Без `messaging.message.id` и без span Create и Settle: `id` задания в span — против решения 12 change `otel-telemetry`, + подтверждение — внутри consumer span (13, Non-Goals). +- Новых параметров `[telemetry]` нет: интервал и срок свежести снимка очереди, границы времени до готовности — константы. +- Dashboard уровня 4 — тот же `messenger-overview.json` (без нового bind mount и `configs` CI) (14); проверка — одна команда + драйвера `trace-chain` (16). + +### Вопросы + +Не блокируют работу; ответ меняет только указанное место. + +1. Преподавателю: «End-to-end time to ready — от durable acceptance до публикации ready» измеряется от записи задания (та же + транзакция, что `queued`, до ответа 202) до фиксации `ready`, а задания после replay не учитываются: их приём — действие + оператора. Достаточно ли так? Иначе — время replay из аудита `attachment_job_replays` (worker, решение 8). +2. Преподавателю: «process/container CPU/RAM» — только у процессов с SDK (реплики API, worker вместе с процессами обработки, + relay), из их cgroup; PostgreSQL, S3, брокер, LB и уборщик не представлены, потому что сокет Docker у Collector — root на + ВМ. Достаточно ли? Иначе — `docker_stats` или cAdvisor с названной ценой (решение 12). +3. Преподавателю: «Queue depth» — логическая очередь заданий по стадиям из PostgreSQL (outbox, отложенные повторы, в брокере, + в обработке), а не счётчик очереди RabbitMQ: очередь брокера — стадия `published`. Достаточно ли? Иначе — плагин + `rabbitmq_prometheus` и доступ к брокеру из сети телеметрии (решение 9). diff --git a/openspec/changes/job-trace-propagation/.openspec.yaml b/openspec/changes/job-trace-propagation/.openspec.yaml new file mode 100644 index 0000000..2a7773d --- /dev/null +++ b/openspec/changes/job-trace-propagation/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-11 diff --git a/openspec/changes/job-trace-propagation/design.md b/openspec/changes/job-trace-propagation/design.md new file mode 100644 index 0000000..7aba8b2 --- /dev/null +++ b/openspec/changes/job-trace-propagation/design.md @@ -0,0 +1,434 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why; требования — `specs/`. Норматив — `README.md` лабы 6 (уровень «4»: контекст W3C +переносится API → broker → worker, видны producer и consumer span со связью parent или link, по одному upload найдена +цепочка до S3 и БД, включая retry; dashboard — p50 / p95 / p99, доля ошибок, глубина очереди и возраст старейшей job, пул БД +и насыщение worker, запросы и единицы), `contracts/observability.md` (строки уровня 4), `contracts/attachment-states.md` +(«Можно применять native headers брокера для trace context, но семантика carrier сохраняется; для проверки покажите +отображение полей»), `contracts/jobs.schema.json` (необязательные `traceparent` по шаблону W3C версии `00` и `tracestate` +до 512 символов). Решения пользователя — `QUESTIONS.md`, «Ответы пользователя перед прогоном (2026-11-11)», и `PLAN.md`, +«Что решает пользователь»: оценка 5, трек 1, Prometheus, Loki, Tempo и Grafana, уровень 4 — два change, этот первый. +Действуют решения change `otel-telemetry` (ниже — «OT-n» по его design): инструментирование вручную в единственных точках +вызова (OT-4), Collector contrib (OT-1), метрики — экспортёр `prometheus` и scrape (OT-3), `[telemetry]` без `OTEL_*` (OT-8), +исход доставки называет сервис, учёт — точка входа (OT-11), закрытие SDK со сроком (OT-13), стенды без телеметрии (OT-20). + +### Код (commit `6b1ad63`) + +- **Загрузка.** `AttachmentService._mark_queued` переводит вложение в `queued` и вставляет задание (`insert_job`) одной + транзакцией; всё это идёт в server span запроса — корне трассы с `Context()` (`RequestContextMiddleware`, OT-10). +- **Relay.** `AttachmentRelayService._publish`: `lock_due_jobs` (`FOR UPDATE SKIP LOCKED`), `publisher.publish_many([(id, + тело)])`, `mark_published` — одна транзакция. `JobPublisher._publish_one` — единственная точка публикации, + `aio_pika.Message` без заголовков. SDK у relay нет (OT-5), но `SqlAlchemyUnitOfWork` (`src/infra/db/uow.py`) импортирует + `src.infra.telemetry`, а `core.py` пакета — SDK и экспортёр на уровне модуля: relay и уборщик грузят модули SDK зря + (замечание S4 verify OT). +- **Worker.** `JobConsumer.deliveries()` отдаёт `JobDelivery(body, redelivered)`. `_handle` после места конкуренции + (`asyncio.Semaphore(concurrency)`) открывает `consumer_span` с `Context()`, вызывает `handle()` → `JobDeliveryOutcome`, + `JobObservation.finish` пишет `messenger.job.duration`, подтверждение — внутри span. +- **Сообщение.** `build_job_body` — семь полей схемы. `AttachmentJobMessage` принимает `traceparent` и `tracestate`, но не + использует их; модель `extra="forbid"` с `pattern` у `traceparent`: неверное значение в теле — сообщение не по схеме, + исход `dropped`. +- **Задания.** Строки `attachment_jobs` не удаляются; частичные индексы `ix_attachment_jobs_outbox` (`COALESCE(next_attempt_at, + created_at), id` при `queued` без отметки), `ix_attachment_jobs_published` (`published_at` при `queued` с отметкой), + `ix_attachment_jobs_lease` (`lease_expires_at` при `processing`). Незавершённых на рабочем стенде не больше `[uploads] + max_unfinished_jobs` (250) плюс загрузок в полёте. +- **Пул.** `create_async_engine` → `AsyncAdaptedQueuePool`: публично `size()`, `checkedin()`, `checkedout()`, + `overflow()`, числа ожидающих нет. `Engine.raw_connection()` → `pool.connect()`; `engine.dispose()` пересоздаёт пул через + `self.__class__(...)`. +- **Телеметрия.** Sampler `ALWAYS_ON`, провайдеры не глобальные, инструменты — две histogram. Dashboard + `messenger-overview.json` — 10 панелей уровня 3 в трёх строках (p50 и p95, доли 5xx и 4xx), один bind mount файла и одна + строка `configs` в CI; провайдер Grafana перечитывает файлы раз в 60 с. `telemetry-check` ищет трассу задания по корню (`root_span`) и ждёт у + корня consumer span `messenger-worker`. + +### Пробы (2026-11-11, рабочий стенд `mtusi-lab6`, только чтение) + +- **cgroup изнутри.** В контейнерах `api`, `worker`, `relay` от UID 10001 `/sys/fs/cgroup` — своя cgroup контейнера + (`cgroup2`, `ro`), `cpu.max`, `memory.max`, `memory.current`, `cpu.stat` (`usage_usec`, `nr_throttled`, `throttled_usec`) + читаются (`r--r--r--`). Значения — пределы compose: api `100000 100000` / 536870912, worker `100000 100000` / + 1073741824, relay `25000 100000` / 268435456; `memory.current` — 130, 113 и 99 МиБ. +- **Память.** VmRSS relay — 110 МиБ, уборщика — 122 МиБ (`docker.md`: «простой ~90 MiB»). Разовый процесс на образе: + `import src.infra.db.uow` поверх repo, `scope`, `engine` и брокера добавляет 322 модуля (279 — `opentelemetry`, protobuf, + `requests`, `urllib3`, `idna`, `certifi`, `charset_normalizer`) и 10,0 МиБ RSS (72,4 → 82,7 МиБ). +- **Снимок очереди** (решение 9) на рабочей базе (1 708 заданий, незавершённых 0): все семь подзапросов — по частичным + индексам (Index Scan по выражению outbox, Index Only Scan published и lease), 7 буферов, 0,31 мс. +- **Версии в `.venv`.** Semantic conventions 0.66b2: `db.client.connection.{count,max,pending_requests,timeouts}`, + `container.cpu.time` (counter, `s`), `container.memory.usage` (updowncounter, `By`), операции messaging `send`, `process`, + `settle`. API 1.45.2: `ParentBased`, `TraceContextTextMapPropagator`, `Link`, синхронный `create_gauge`. pamqp 4.0.1 + отдаёт строку заголовка как `str`, не UTF-8 — как `bytes`. SQLAlchemy 2.1.1. +- **Semantic conventions messaging** (opentelemetry.io, статус Development): links — способ связи по умолчанию; «Exclusively + for single messages scenarios, the "Process" span MAY use the message's creation context as its parent»; «For each message + it accounts for, the "Process" or "Receive" span SHOULD link to the message's creation context»; «Instrumentations SHOULD + document whether they use the message creation context as a parent»; без span Create в сообщение кладётся контекст span + Send, его вид — `PRODUCER`; имя — `{messaging.operation.name} {destination}`. + +## Goals / Non-Goals + +**Goals:** +- одна трасса на загрузку: каждая попытка, повтор и replay видны и связаны parent-child, а отсутствующий или сломанный + контекст ничего не ломает; +- у каждого сигнала уровня 4 один источник и запрос dashboard — опора `slo-alerts`: возраст очереди для инцидента 1, пул и + span БД для инцидента 2, время до `ready` и доля ошибок для SLO; +- выключенная телеметрия — ни модулей SDK, ни запросов; методика `bench/`, стенда отказов и `make test_isolated` прежняя; +- любая смесь версий при замене работает без ошибок. + +**Non-Goals:** +- span Create и Settle: подтверждение — внутри consumer span (OT-11); `messaging.message.id`; +- span операции replay, SDK у команды replay и у уборщика; +- метрики брокера, PostgreSQL, S3 и LB; cAdvisor, `docker_stats` и `hostmetrics` Collector; +- новые параметры `[telemetry]`, изменения Collector, Prometheus, Loki, Tempo; exemplars; recording rules и alerts. + +## Decisions + +### 1. Carrier — заголовки AMQP, а не поля тела (развилка «как везти контекст») + +Контекст едет в заголовках сообщения `traceparent` и `tracestate` (W3C Trace Context, propagator +`TraceContextTextMapPropagator` с carrier-словарём); поля тела `traceparent` и `tracestate` не заполняются. + +- Метаданные телеметрии не должны влиять на обработку (спек `observability`, «SDK в API и worker»). Тело проверяет + `AttachmentJobMessage` (`extra="forbid"`, `pattern`): неверное значение в теле делает сообщение «не по схеме» — `dropped`, + бизнес-сообщение потеряно из-за телеметрии. Неверный заголовок по W3C просто игнорируется: новая трасса. +- Consumer span открывается до `handle()`: из заголовков точка входа берёт контекст, не разбирая тело — разбор по схеме + остаётся в сервисе. +- Так переносят контекст инструментирования RabbitMQ OpenTelemetry; контракт это разрешает с тем же смыслом carrier. + Отображение в `REPORT.md`: заголовок `traceparent` = поле тела `traceparent` = колонка `attachment_jobs.traceparent` + (одно значение W3C), так же `tracestate`. +- Прежний worker заголовки не читает, тело прежнее — совместимость полная (решение 6). + +Отвергнуто: **поля тела** — второй разбор тела в точке входа или перенос разбора из сервиса, риск `dropped`; **и тело, и +заголовки** — два источника одного значения. + +### 2. Связь consumer — parent и link (развилка «parent или link») + +Consumer span доставки — дочерний к контексту создания сообщения (span producer relay из заголовков) и несёт link на тот же +контекст. По semantic conventions это допустимо «exclusively for single messages»: worker обрабатывает сообщение по одному, +объемлющего span у задачи доставки нет; link — их «SHOULD link to the message's creation context»; выбор документируется в +`REPORT.md` («SHOULD document»). + +Почему parent, а не только link, — по умолчанию semantic conventions выбирают link: +- одна трасса на загрузку: «по одному upload найдена цепочка до S3/DB, включая retry» и шаг 3 защиты — одна трасса по одному + id, без поиска по `link:traceID`; +- трек 1: head sampling (`ParentBased`, решение 5) решает судьбу всей цепочки на загрузке; при одних link трасса worker + выбиралась бы отдельно, и при 10 % целых цепочек было бы 1 %. Tail sampling Collector решает по trace-id — тоже вся цепочка + разом (поздние span следуют закэшированному решению; `decision_wait` и кэш — настройка трека 1). + +Цена — длинные трассы: повторы растягивают трассу на минуты, replay — на часы. Tempo по trace-id собирает span из разных +блоков; длительность трассы в поиске — вся цепочка (ограничение в `REPORT.md`, риск ниже). + +Отвергнуто: **только link** — две-три трассы на загрузку, выборка рвёт цепочки; **parent без link** — против «SHOULD link». + +### 3. Span producer — в клиенте брокера, на сообщение, под сохранённым контекстом + +`JobPublisher._publish_one` — единственная точка публикации, как `ObjectStorage._call` у S3 (OT-4): там на каждое сообщение +открывается span `PRODUCER` `publish <очередь>` с родителем — сохранённым контекстом задания (удалённый span из колонок), +его контекст уходит в заголовки сообщения, span заканчивается после подтверждения брокером (`publish` aio-pika с publisher +confirms ждёт ack). Отказ, возврат и отмена по общему сроку пакета — статус `ERROR` и класс ошибки. Relay-сервис передаёт в +`publish_many` элементы `JobPublicationDTO` (id, тело, номер попытки сообщения, признак replay, причина повтора — прежний +`last_error_code`, контекст задания). + +- Нет сохранённого контекста — ни span, ни заголовков: проходы relay трасс не начинают (правило корня, OT-4, OT-5). +- Телеметрия relay выключена — в заголовки кладётся сохранённый контекст как есть: цепочка API → worker не рвётся. +- Обращения relay к PostgreSQL идут вне span producer: span БД у relay нет. + +Отвергнуто: **один span Send на пакет с links** — пакет — деталь relay, а span прохода был бы корнем трассы; **span в +сервисе relay** — span хранилищ и брокера живут в клиентах; **сохранённый контекст загрузки как контекст создания, span Send +рядом** — пропадает связь «какая публикация доставила какую попытку». + +### 4. Контекст в задании: две колонки, пишет загрузка + +Ревизия alembic поверх `d3f9a6b2c1e7`: `attachment_jobs.traceparent text NULL`, `attachment_jobs.tracestate text NULL`, +CHECK `ck_attachment_jobs_traceparent` (`traceparent ~ '^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$'` — шаблон +`jobs.schema.json`) и `ck_attachment_jobs_tracestate` (1–512 символов и только вместе с `traceparent`), оба `NOT VALID`, +как `ck_attachment_jobs_attempt_base`: прежние строки — `NULL`. Первой строкой `SET LOCAL lock_timeout = '2s'`, `downgrade` — +зеркально (`migrations.md`). Только расширение: прежний код вставляет и читает свои колонки. + +Кто пишет: зависимость API `TraceContextDep` берёт `telemetry.current_trace_context()` — контекст текущего span (server span +загрузки) как `TraceContextDTO(traceparent, tracestate)`, `None` без телеметрии или без валидного span, — ручка загрузки +передаёт его `AttachmentService.upload(trace_context=…)`, сервис — в `AttachmentJobDTO.traceparent` / `tracestate` при +`insert_job`. Сервис телеметрию не импортирует: контекст — значение из слоя API, как `owner_id`. Невыбранный, но валидный +контекст сохраняется с флагом `00` (решение 5). Дальше контекст не меняется: повторы, возврат по аренде и replay — в той же +трассе загрузки. + +Отвергнуто: **`jsonb`** — проверка формата сложнее, полей два; **таблица `attachments`** — намерение (outbox) — это задание; +**сервис зовёт телеметрию** — ядро зависело бы от состояния SDK; **запись в repo** — скрытый побочный эффект; **контекст +попытки вместо загрузки** (повтор — дочерний к прошлому consumer span) — запись на каждую попытку, а команда replay без SDK +контекста не даст. + +### 5. Sampler `ParentBased(ALWAYS_ON)`, без baggage + +Корни (server span, consumer span без контекста) по-прежнему выбираются всегда; удалённый родитель из задания и сообщения +передаёт свой флаг выборки. При 100 % поведение то же, а head sampling трека 1 меняет только корневой sampler, и вся +цепочка выбирается одним решением на загрузке. Переносится только W3C Trace Context: глобальный составной propagator (с +baggage) не ставится, как и глобальные провайдеры (OT-8). + +### 6. Без контекста и смесь версий (развилка) + +Строки без контекста — от прежних реплик во время `make rolling_update` или от реплики с выключенной телеметрией: relay +публикует без заголовков и без span producer, consumer span — корень, как на уровне 3. Прежний relay колонок не знает — +публикует без заголовков; прежний worker заголовки игнорирует; сообщения, опубликованные до замены, — без заголовков. Ни +одна комбинация не даёт ошибки: рвутся только цепочки заданий, которых коснулся прежний код. Порядок обновления любой; +естественный — миграция и реплики (`make rolling_update`), затем relay и worker. Заголовок не по формату и `bytes` не в +ASCII клиент брокера отбрасывает при разборе доставки (`JobDelivery.trace_context` — `None`). + +### 7. SDK в relay; уборщик и replay без SDK; ленивый импорт SDK (S4) + +- **Relay:** `start_process_telemetry(TELEMETRY_SERVICE_RELAY)` (`messenger-relay`) после `early_stop.disarm()`, + `instrument_engine(engine)` (метрики пула; слушатели span без записывающего родителя ничего не делают), метрики очереди + (решение 9), закрытие SDK — в окне `gather` 0,5 с, как у worker; «Started relay» называет телеметрию. Окружение — якорь + `x-telemetry-env` в compose; `bench.compose.yml`, `failures.compose.yml` и `run_isolated.py` выключают её у relay (OT-20). +- **Replay** (`python -m src.relay replay`) SDK не запускает: разовая команда, а replay в трассе виден следующей парой + producer / consumer с признаком replay. Span операции оператора потребовал бы запуска и закрытия SDK в команде, а + оператор — свободный текст, ему в телеметрии не место. +- **Уборщик** — без SDK (OT-5): его проходы не путь SLO. +- **Ленивый импорт.** Модули пакета `src/infra/telemetry/` на уровне модуля импортируют только `opentelemetry-api`; SDK, + экспортёр и `requests` — новый модуль `sdk.py`, его импортирует `start()`. Тогда уборщик, команда replay и процессы с + выключенной телеметрией (консоль, `bench/`, стенд отказов, `make test_isolated`) не грузят 322 модуля и 10 МиБ (проба), и + память реплики в метках последнего шага (`bench_uploads`) сравнима с кодом лабы 5. Проверка — быстрый тест в отдельном + интерпретаторе: после импорта точек входа модулей SDK, экспортёра, protobuf и `requests` в `sys.modules` нет. + +Отвергнуто: **принять и переснять память** — +10 МиБ у уборщика и у реплик с выключенной телеметрией без пользы; **убрать +телеметрию из `SqlAlchemyUnitOfWork`** — span `COMMIT` нужен API и worker. + +### 8. Итог доставки — DTO; время до готовности + +`AttachmentProcessingService.handle()` возвращает `JobDeliveryResultDTO`: `outcome` (`JobDeliveryOutcome`), `attempt` +(взятая попытка, у `skipped` — `attempt` сообщения, у `dropped` — нет), `reason` (`AttachmentJobReason` у `retry` и +`failed`), `error_code` (у `failed`) и `time_to_ready_seconds` — только у `ready` задания без replay (`attempt_base == 0`): +время после фиксации `ready` минус `attachment_jobs.created_at` (тот же блок, что `queued`, до ответа 202). Точка входа +пишет атрибуты consumer span и histogram `messenger.job.time_to_ready`, как OT-11: сервис называет итог, наблюдение — у +точки входа. Границы buckets: 0,25; 0,5; 1; 2,5; 5; 10; 20; 30; 60; 120; 300; 600 с — путь без повторов 0,5–2 с (опрос relay +0,25 с, процесс обработки 0,2–1 с), бюджет smoke 60 с, четыре паузы повторов до 75 с, возврат по аренде 70 с, `[worker] +retry_max_delay_seconds` 300 с. + +Отвергнуто: **запись метрики в сервисе** — против OT-11; **`created_at` из тела в точке входа** — второй разбор тела; +**от `attachments.created_at`** — это строка `pending` до PUT в staging, а не устойчивый приём; **replay от исходного приёма** — часы, +SLO это не измеряет; **от времени replay** — его нет в строке задания (только в аудите), чтение аудита в worker ради метрики +— потом, если понадобится. + +### 9. Очередь — снимок relay по PostgreSQL (развилка «источник очереди») + +Relay с включённой телеметрией после успешного прохода, не чаще `QUEUE_SNAPSHOT_INTERVAL_SECONDS` (5 с), снимает снимок +`AttachmentRelayService.queue_snapshot()` — один блок, новый метод repo `queue_snapshot(now)` одним выражением: + +```sql +SELECT + (SELECT count(*) FROM attachment_jobs WHERE state = 'queued' AND published_at IS NULL + AND COALESCE(next_attempt_at, created_at) > :now) AS scheduled, + (SELECT count(*) FROM attachment_jobs WHERE state = 'queued' AND published_at IS NULL + AND COALESCE(next_attempt_at, created_at) <= :now) AS outbox, + (SELECT count(*) FROM attachment_jobs WHERE state = 'queued' AND published_at IS NOT NULL) AS published, + (SELECT count(*) FROM attachment_jobs WHERE state = 'processing') AS processing, + LEAST() AS oldest_created_at +``` + +Состояния — константы `literal_execute` (`repo-layer.md`): иначе общий план — Seq Scan. Каждый подзапрос совпадает с +условием своего частичного индекса (проба — 0,31 мс), незавершённых ограниченно, `LEAST` пропускает `NULL`. DTO +`QueueSnapshotDTO` (время снимка, четыре стадии, `oldest_created_at`) хранит точка входа relay; наблюдаемые gauge читают +последний снимок, возраст — время снимка минус `oldest_created_at` (нет — 0), снимок старше `QUEUE_SNAPSHOT_STALE_SECONDS` +(30 с) не отдаётся. Возраст — от устойчивого приёма, как время до `ready`: это «время до `ready` до сих пор» старейшего +незавершённого. Отказ PostgreSQL — снимок пропускается (запись о нём уже пишет `session_scope`). Два relay дают два ряда +(разные `instance`): панели берут `max` по экземплярам, а не сумму. + +Отвергнуто: **реплики API** — N копий одного числа (их `count_unfinished` — только предел приёма); **worker** — их может +быть два (`bench_queue`), outbox он не видит; **приёмник `sqlquery` / `postgresql` Collector** — пароль PostgreSQL у +Collector, у которого секретов нет, и SQL вне кода приложения, а `postgresql` своих запросов не делает; **метрики брокера** +(`rabbitmq_prometheus`, приёмник `rabbitmq`) — только очередь брокера: без outbox, обработки и возраста, Prometheus или +Collector в сети приложения, у приёмника — management-плагин с учётными данными; **синхронный gauge** — держит последнее +значение после отказа, устаревшее выглядит текущим; **запрос в callback** — поток экспорта метрик asyncpg не дождётся. + +### 10. Пул PostgreSQL — semantic conventions и пул со счётом ожидающих + +`CountingQueuePool(AsyncAdaptedQueuePool)` в `src/infra/db/engine.py`, `poolclass=` фабрики: переопределяет публичный +`Pool.connect()` — счётчик ожидающих вокруг `super().connect()` (ожидание места, открытие соединения и проверка при выдаче) и +счёт `sqlalchemy.exc.TimeoutError`; методы `pending()` и `timeouts()`. Фабрика о телеметрии по-прежнему не знает: счёт — +свойство пула. `instrument_engine(engine)` регистрирует наблюдаемые инструменты, которые на каждом сборе читают текущий +`engine.sync_engine.pool` (`dispose()` создаёт новый пул того же класса): `count{state=used}` — `checkedout()`, +`count{state=idle}` — `checkedin()`, `max` — `size()` + `[database] max_overflow`, `pending_requests`, `timeouts`; имя пула — +`server.address:server.port/db.namespace` (semantic conventions). Числа читает поток экспорта, пишет цикл событий: гонка +безвредна (целые, на сбор ± 1). + +Отвергнуто: **`pool._pool._queue._getters`** — внутренности `asyncio.Queue`; **события пула** — события «запрошено +соединение» нет; **подмена `pool.connect` у экземпляра** — пропадает после `dispose()`; **без ожидающих** — контракт просит +«waiting»; **histogram `db.client.connection.wait_time`** — пулу понадобился бы наблюдатель, а для инцидента 2 хватает +ожидающих, отказов по сроку и span БД (трек 1, если понадобится). + +### 11. Насыщение worker + +`_handle` ведёт два счётчика вокруг `async with slots`: «ждут места» — до входа, «заняты» — внутри (в том числе ветка «после +сигнала попытка не начинается»), `finally` их снимает. `telemetry.observe_worker(capacity=[worker] concurrency, load=…)` — +наблюдаемые `messenger.worker.busy`, `.capacity`, `.waiting`. Мгновенное значение раз в интервал отправки пропускает +короткие всплески, поэтому панель показывает и среднее за окно — `rate(messenger_job_duration_seconds_sum)` к ёмкости: +histogram длительности пишется ровно за время на месте (OT-11), и это занятые места по закону Литтла. Отвергнуто: +`Semaphore._value` — внутреннее имя; prefetch от брокера (`rabbitmqctl` — 0,5 с CPU брокера на вызов, `bench.md`). + +### 12. CPU и память — cgroup изнутри, без `docker.sock` (развилка) + +`start_process_telemetry` регистрирует наблюдаемые инструменты контейнера, если читаются `/sys/fs/cgroup/cpu.stat` и +`memory.current` (cgroup v2, проба): `container.cpu.time` — `usage_usec` / 10⁶, `container.memory.usage` — `memory.current`, +`messenger.container.cpu.limit` — квота / период `cpu.max`, `messenger.container.memory.limit` — `memory.max` (значение `max` +— точки нет). Иначе одна запись `warning` «Container metrics are unavailable». Файлы читает callback сбора (микросекунды). У +worker cgroup включает процессы обработки — ту работу, которую делают именно они. Корень cgroup — параметр со значением по +умолчанию из константы: быстрые тесты дают временный каталог, и на хосте разработчика (macOS, без cgroup) их записи журнала +прежние. + +Отвергнуто: **`docker.sock` у Collector** (`docker_stats`) — доступ к API Docker равен root на ВМ (привилегированный +контейнер с монтированием хоста; `:ro` у сокета API не ограничивает), а Collector принимает OTLP без аутентификации из сети +приложения (до лабы 7): взлом Collector — взлом хоста; **cAdvisor** — привилегированные монтирования `/`, `/sys`, +`/var/lib/docker`; **`hostmetrics`** с `/proc` хоста — ВМ целиком, а не контейнеры; **метрики процесса** (`psutil` или +`/proc/self`) — новая зависимость, а у worker мимо процессов обработки. Цена: PostgreSQL, S3, брокер, LB и уборщик в этих +метриках не представлены (`REPORT.md`); сервисы телеметрии отдают свои метрики процесса Go. Троттлинг (`nr_throttled`) — +сэмплер `bench/` и трек 1. + +### 13. Имена, атрибуты, единицы + +Имена и атрибуты — константы `src/utils/constants.py`; соответствие Prometheus проверяет apply на стенде, как OT-3. + +| Сигнал | Инструмент | Имя, единица | Атрибуты | Prometheus | +| --- | --- | --- | --- | --- | +| время до `ready` | Histogram | `messenger.job.time_to_ready`, `s` | `messenger.job.type` | `messenger_job_time_to_ready_seconds_{bucket,sum,count}` | +| глубина очереди | ObservableGauge | `messenger.queue.depth`, `{job}` | `messaging.destination.name`, `messenger.queue.stage` | `messenger_queue_depth` | +| возраст старейшего | ObservableGauge | `messenger.queue.oldest_age`, `s` | `messaging.destination.name` | `messenger_queue_oldest_age_seconds` | +| пул: соединения | ObservableUpDownCounter | `db.client.connection.count`, `{connection}` | `db.client.connection.pool.name`, `db.client.connection.state` | `db_client_connection_count` | +| пул: предел | ObservableUpDownCounter | `db.client.connection.max`, `{connection}` | `db.client.connection.pool.name` | `db_client_connection_max` | +| пул: ожидающие | ObservableUpDownCounter | `db.client.connection.pending_requests`, `{request}` | `db.client.connection.pool.name` | `db_client_connection_pending_requests` | +| пул: отказы по сроку | ObservableCounter | `db.client.connection.timeouts`, `{timeout}` | `db.client.connection.pool.name` | `db_client_connection_timeouts_total` | +| worker | ObservableUpDownCounter | `messenger.worker.busy`, `.capacity`, `.waiting`, `{delivery}` | — | `messenger_worker_busy`, `_capacity`, `_waiting` | +| CPU контейнера | ObservableCounter | `container.cpu.time`, `s` | — | `container_cpu_time_seconds_total` | +| память контейнера | ObservableUpDownCounter | `container.memory.usage`, `By` | — | `container_memory_usage_bytes` | +| пределы контейнера | ObservableUpDownCounter | `messenger.container.cpu.limit` (`{cpu}`), `messenger.container.memory.limit` (`By`) | — | `messenger_container_cpu_limit`, `messenger_container_memory_limit_bytes` | + +Стадии `messenger.queue.stage`: `scheduled`, `outbox`, `published`, `processing` (спек «Глубина и возраст очереди»). + +Span producer `publish <очередь>` (`PRODUCER`): `messaging.system` = `rabbitmq`, `messaging.operation.type` = `send`, +`messaging.operation.name` = `publish`, `messaging.destination.name`, `messenger.job.type`, `messenger.job.attempt`, +`messenger.job.replayed`, `messenger.job.retry_reason` (если есть). Consumer span `process <очередь>` — прежние атрибуты и +`messaging.operation.name` = `process`, `messenger.job.attempt`, `messenger.job.redelivered`, `messenger.job.reason`, +`messenger.job.error_code`; link — на контекст создания. Без `messaging.message.id`: `id` задания в span — против решения +OT-12, а цепочке он не нужен (отступление от semantic conventions — в `REPORT.md`). Атрибуты причин — значения enum, без +текста ошибок. + +### 14. Dashboard уровня 4 — тот же JSON + +`messenger-overview.json` получает строки «Pipeline» и «Saturation», панели p50 / p95 уровня 3 — ещё p99. Один файл — без +нового bind mount и строки `configs` CI (`telemetry.md`: новый файл — строка в обоих). Провайдер перечитывает файл раз в +60 с; bind mount одного файла после замены файла редактором может показывать прежний inode — после правки `docker compose +restart grafana` (проверяет apply). Запросы: + +- HTTP p50 / p95 / p99: `histogram_quantile(q, sum by (le) (rate(http_server_request_duration_seconds_bucket{job="messenger-api"}[5m])))`; + доля 5xx и доля 4xx — панели уровня 3 (определение — спек «Метрики HTTP API»); +- обработка p50 / p95 / p99 (`ready`): то же над `messenger_job_duration_seconds_bucket{job="messenger-worker",messenger_job_outcome="ready"}`; +- время до `ready` p50 / p95 / p99: `histogram_quantile(q, sum by (le) (rate(messenger_job_time_to_ready_seconds_bucket{job="messenger-worker"}[5m])))`; +- глубина по стадиям: `max by (messenger_queue_stage) (messenger_queue_depth{job="messenger-relay"})`; возраст: + `max(messenger_queue_oldest_age_seconds{job="messenger-relay"})`; +- пул: `sum by (job, instance) (db_client_connection_count{db_client_connection_state="used"}) / sum by (job, instance) + (db_client_connection_max)`, ожидающие — `sum by (job, instance) (db_client_connection_pending_requests)`, отказы — + `sum by (job) (rate(db_client_connection_timeouts_total[5m]))`; +- worker: `sum(messenger_worker_busy) / sum(messenger_worker_capacity)`, среднее — + `sum(rate(messenger_job_duration_seconds_sum{job="messenger-worker"}[5m])) / sum(messenger_worker_capacity)`, ожидающие + места — `sum(messenger_worker_waiting)`; +- контейнеры: `sum by (job, instance) (rate(container_cpu_time_seconds_total[5m])) / sum by (job, instance) + (messenger_container_cpu_limit)` и `sum by (job, instance) (container_memory_usage_bytes) / sum by (job, instance) + (messenger_container_memory_limit_bytes)` — у каждого процесса по одному ряду, деление один к одному по `job` и + `instance`. + +Единицы панелей: `s`, `percentunit`, `short`; таблица «сигнал → запрос → единица» — `REPORT.md`. + +### 15. Остановка, бюджет, лимиты + +Остановка relay — шаг ≤ 6 с и закрытие клиентов 0,5 с, закрытие SDK внутри того же окна: худший случай прежний (спек +`graceful-shutdown`), замер — `telemetry-outage`. Новых сервисов нет. Лимит relay (0,25 CPU / 256 МиБ) проверяется замером +`memory.peak` и CPU под `make test` + `make load` + `make student_test` + `trace-chain` по правилу «лимит не меньше 1,5 × +пика» (`telemetry.md`); не выполняется — лимит поднимается, суммы `docker.md` и `REPORT.md` пересчитываются (до ВМ 254 МиБ). +Память уборщика переснимается после ленивого импорта, число в `docker.md` исправляется. Соединений PostgreSQL не прибавляется. + +### 16. Проверки + +- **`driver.py --port trace-chain`** (рабочий стенд, ~5 мин, всё через HTTP API Grafana с паролем из `.env`): + 1. worker остановлен, K = 3 загрузки → сумма `outbox` и `published` = K, возраст растёт между двумя чтениями; worker + запущен → все `ready`, глубина и возраст 0; + 2. worker остановлен, загрузка F (`X-Request-Id` R) опубликована, S3 заморожен, worker запущен → в stdout worker «Retrying + job» по F → S3 разморожен → `ready`; Loki: запись API с `request_id` R → `trace_id` T, записи worker по F — с T; Tempo: + корень — server span `messenger-api`; два span producer `messenger-relay` — дети корня, попытки 1 и 2, у второго + причина `storage_unavailable`; два consumer span `messenger-worker` — дети своих producer, с link на них, исходы `retry` + (попытка 1, span S3 с ошибкой) и `ready` (попытка 2, `S3.PutObject` ≥ 4, процесс обработки, `COMMIT`); + 3. недекодируемый JPEG → `failed`, `docker compose run --rm --no-deps relay replay --attachment-id … --apply` → снова + `failed`; в его трассе второй span producer с `messenger.job.replayed` и второй consumer span; + 4. relay остановлен, загрузка, `UPDATE attachment_jobs SET traceparent = NULL, tracestate = NULL` по `attachment_id` этой + загрузки (одна строка своего синтетического вложения), relay запущен → `ready`, у записей worker другой `trace_id`, его + корень — consumer span, span producer нет; + 5. время до `ready` выросло ровно на число загрузок без replay, пулы (предел 10 у реплик, 2 у worker, 1 у relay, занятых + не больше), ёмкость worker 2, пределы контейнеров = `docker inspect` (`NanoCpus`, `Memory`), память меньше предела, нет + монтирования сокета Docker в `docker compose config`, панели уровня 4 с данными (общий обход панелей с `telemetry-check`). + + `finally`: `unpause s3`, `start worker relay`. Таблица «шаг → ожидаемо → получено», коды 0 / 1 / 2 (нет стенда) → + `evidence/telemetry/trace-chain.md`. +- **`telemetry-check`:** шаги задания — по consumer span трассы загрузки, а не по корню; шаг «трасса задания — трасса + загрузки» (`trace_id` «Uploaded attachment» = `trace_id` записей worker); relay — в списке контейнеров пробы сетей. +- **`telemetry-outage`:** relay — в остановках при остановленном и замороженном Collector (быстрее 10 с, код 0, «Stopped + relay») и в рестарте при остановленных сервисах телеметрии; сигналы relay снова приходят. +- **Быстрые тесты** (`service-tests/unit`, in-memory экспортёры): контекст загрузки (в span, вне span, выключено); span + producer (родитель, заголовки, ошибка, выключено — заголовки как есть, без контекста — ничего); consumer span (родитель и + link, без заголовков и с неверным — корень, флаг `00` — не записывается); время до `ready` (replay — нет наблюдения); + метрики пула, worker, очереди (свежий и устаревший снимок) и контейнера (каталог cgroup во временной папке, нет файлов — + одна запись); ленивый импорт в отдельном интерпретаторе; разбор заголовков доставки (`str`, `bytes`, мусор); сервисы + загрузки, relay и обработки (контекст в строке, элементы публикации, итог доставки); контракт repo (колонки, снимок + очереди по стадиям). `service-tests/db`: тот же контракт на SQL; пул из одного соединения — ожидающий и отказ по сроку; + `dispose()` сохраняет класс пула. +- **Регрессия:** `make lint`, `make service_test`, `make service_test_db`, `docker compose config --quiet` (рабочий, CI, + `bench/`, отказы), `make test`, `make student_test` через LB (красный — только `test_exclusion_evidence_exists`), `make + test_isolated`, `make failure_checks`, `make test-persistence`, `make test-failover` (stop и kill), `telemetry-check`, + `telemetry-outage`; миграция — с нуля, повтор, откат, `--sql`, `make rolling_update`; план снимка очереди — `EXPLAIN + (ANALYZE, BUFFERS)` на рабочей базе. +- Evidence снимается после коммита кода (`bench.md`, «Измеренное состояние — commit»). + +### 17. Документы + +Правила: `telemetry.md` (SDK в relay, ленивый импорт, `ParentBased`, carrier и правило корня, span producer и consumer, +метрики уровня 4, имена), `worker.md` (consumer span, итог доставки, счётчики мест, время до `ready`), `infra.md` (заголовки +брокера, `CountingQueuePool`, новые части пакета телеметрии), `logging.md` (записи relay в Loki, «Started relay»), +`settings.md` и `config_example.toml` (relay читает `[telemetry]`), `docker.md` (relay с телеметрией, память relay и +уборщика, суммы), `dto.md` (новые DTO), `repo-layer.md` (колонки, `queue_snapshot`), `migrations.md` (ревизия), `bench.md`, +`student-tests.md`, `run-modes.md` (relay без телеметрии в консоли и на тестовых стендах, остановка). `.env.example` — +`messenger-relay` в соответствии `OTEL_SERVICE_NAME`. `AGENTS.md` — состояние лабы, карта кода, команда `trace-chain`, +evidence. `REPORT.md` — «Наблюдаемость»: сквозная трасса и отображение carrier, сигналы уровня 4 (таблица, запросы, единицы, +источник очереди, отказ от `docker.sock`), ресурс `messenger-relay`, бюджет, ограничения, строки «Доказательства +критериев». `QUESTIONS.md` — раздел `## job-trace-propagation`. `SKILL.md` — `trace-chain` и правки двух команд. В конце — +`graphify update .`. + +## Risks / Trade-offs + +- [Tempo не соберёт трассу, span которой пришли с разницей в минуты и часы] → выборка по trace-id объединяет блоки; + `trace-chain` проверяет повтор (~10 с) и replay; если Tempo 3.1 трассу делит — решение 2 меняется на link, запись в + «Уточнения apply». +- [Корень трассы потерян — Collector был недоступен при загрузке] → span relay и worker в Tempo без корня («root span not + yet received»); ограничение в `REPORT.md`. +- [Длинные трассы искажают длительность трасс в поиске] → поиск по атрибутам span (`messenger.job.outcome`); ограничение. +- [CPU relay (0,25) на потоках SDK] → замер решения 15; в `bench/` у relay телеметрия выключена. +- [Мгновенные значения пула и насыщения раз в 15 с пропускают всплески] → отказы по сроку — счётчик, насыщение — ещё и + среднее по сумме длительностей; ограничение. +- [Устаревший снимок очереди: экспортёр Collector держит последнюю точку до `metric_expiration` (5 мин)] → relay через 30 с + перестаёт отдавать снимок; описание панели и ограничение. +- [`CountingQueuePool` опирается на `Pool.connect()` и `QueuePool`] → публичный метод, SQLAlchemy закреплён `<2.2`, тест на + временной базе ловит смену. +- [Смесь версий рвёт цепочки на время замены] → ожидаемо, без ошибок (решение 6). +- [cgroup v1 или не Linux] → метрик контейнера нет, одна запись `warning`. +- [Файл dashboard в bind mount не перечитан] → рестарт Grafana после правки. +- [Semantic conventions messaging, db и container — статус Development] → имена — константы, соответствие — таблица + `REPORT.md`; SDK и semconv закреплены lock-файлом. +- [Смена результата `handle()` задевает быстрые тесты] → тесты меняются вместе с DTO, это внутренний API. + +## Migration Plan + +1. Без простоя: `make rolling_update` — ревизия один раз, затем реплики (новые загрузки сохраняют контекст, прежние реплики + до замены — нет). +2. `docker compose up -d --no-deps relay worker cleaner`: relay с SDK и окружением телеметрии, worker с контекстом из + заголовков и новыми метриками, уборщик без модулей SDK. Порядок любой (решение 6). +3. `docker compose restart grafana` — dashboard уровня 4. + +С простоем — `make run_docker`. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0`, прежние образы relay, worker и +уборщика; колонки остаются, прежний код их не читает, сообщения с заголовками прежний worker обрабатывает как обычно. + +## Open Questions + +Блокирующих нет. Решения без пользователя и вопросы преподавателю, которые не меняют спеки и задачи, — `QUESTIONS.md`, +раздел `## job-trace-propagation`. diff --git a/openspec/changes/job-trace-propagation/proposal.md b/openspec/changes/job-trace-propagation/proposal.md new file mode 100644 index 0000000..672d00c --- /dev/null +++ b/openspec/changes/job-trace-propagation/proposal.md @@ -0,0 +1,80 @@ +# Proposal + +## Why + +Уровень «4» рубрики `README.md` лабы 6, первая из двух частей (`PLAN.md`, раздел «2. `job-trace-propagation`»; решение +пользователя 3). После change `otel-telemetry` загрузка и обработка её задания — две несвязанные трассы: outbox разрывает +синхронную цепочку (relay публикует позже и в другом процессе, SDK у него нет), а worker начинает каждую доставку новой +трассой. По одному upload нельзя пройти до записи S3 и фиксации в БД, включая повторную попытку. Сигналов уровня 4 +`contracts/observability.md` — глубины и возраста очереди, пула PostgreSQL, насыщения worker, CPU и памяти процессов, +времени до `ready`, p99 — нет совсем, а на них опирается следующий change `slo-alerts`: его SLO, alerts и два инцидента +(остановленный worker, медленная БД). + +## What Changes + +- **Сквозная трасса загрузки.** Контекст W3C (`traceparent`, `tracestate`) server span загрузки сохраняется в задании + вместе с намерением — две колонки `attachment_jobs`, миграция только расширяет схему. Relay получает SDK и на каждую + публикацию пишет producer span дочерним к сохранённому контексту, а контекст этого span кладёт в заголовки сообщения + AMQP. Worker делает consumer span дочерним к контексту сообщения и добавляет link на него (semantic conventions messaging, + обработка одного сообщения). Одна загрузка — одна трасса: каждая попытка, повтор после временной ошибки и replay — пара + producer / consumer в ней, с номером попытки и причиной. Без контекста (строка прежней версии, телеметрия API выключена) + — прежнее поведение: consumer span — корень трассы. Тело сообщения по `contracts/jobs.schema.json` не меняется. +- **Метрики уровня 4.** Время до `ready` — histogram от устойчивого приёма (`queued` и задание одной транзакцией) до + фиксации `ready`. Глубина очереди по стадиям (отложенные повторы, outbox, в брокере, в обработке) и возраст старейшего + незавершённого задания — из одного источника, relay. Пул PostgreSQL каждого процесса с SDK: занято, свободно, предел, + ожидающие, отказы по сроку (semantic conventions `db.client.connection.*`). Занятость worker: занятые места, ёмкость, + доставки в ожидании места. CPU и память контейнеров API, worker и relay — из их cgroup изнутри, без `docker.sock`. +- **Dashboard уровня 4** — в том же JSON из git: p50 / p95 / p99 из суммы buckets всех реплик, доля ошибок 5xx и 4xx + отдельно, очередь и возраст, время до `ready`, пул, насыщение worker и контейнеров. Запросы и единицы — в `REPORT.md`. +- **SDK без лишнего.** Модули SDK загружаются только при включённой телеметрии: уборщик, процессы с выключенной + телеметрией, стенды `bench/` и отказов их больше не грузят (замечание S4 verify change `otel-telemetry`, проба — +10 МиБ + RSS и 322 модуля). Sampler — `ParentBased(ALWAYS_ON)`: флаг выборки из контекста задания соблюдается, при 100 % трасс + ничего не меняется. +- **Проверки.** Команда драйвера `trace-chain`: очередь и её возраст при остановленном worker, цепочка одной загрузки с + вынужденной повторной попыткой при замороженном S3, replay в той же трассе, задание без контекста, метрики уровня 4 и + панели. Правки `telemetry-check` (трасса задания — это трасса загрузки) и `telemetry-outage` (relay). Быстрые тесты + `service-tests/`. Evidence — `evidence/telemetry/`, снимается после коммита кода. + +**Не входит:** SLO, alert rules, runbooks, recording rules под SLO, `sending_queue` и `retry_on_failure` Collector, отказ +хранилищ телеметрии и учёт потерь — change `slo-alerts`; sampling и цена телеметрии — `track1-telemetry-cost`; SDK у +уборщика и команды replay; метрики PostgreSQL, S3, брокера и LB как процессов; exemplars. + +Не меняются: бизнес-API и контракт (`contracts/`), `tests/`, `README.md`, `COURSE.md`, `lab.json`; тело сообщения брокера; +поведение API, worker, relay и уборщика вне телеметрии. + +## Capabilities + +### New Capabilities + +Нет: сигналы и трассы — capability `observability` (change `otel-telemetry`). + +### Modified Capabilities + +- `observability`: сквозная трасса загрузки и обработки (контекст в задании, producer span relay, consumer span worker, + попытки и replay, задания и сообщения без контекста), SDK в relay, время до `ready`, очередь и возраст, пул PostgreSQL, + насыщение worker, CPU и память контейнеров, панели уровня 4, проверка цепочки по сохранённым наблюдениям, где телеметрия + включена (relay), что описывает `REPORT.md`. +- `service-logging`: записи relay — тоже с полями трассы и в хранилище логов; записи задания — с `trace_id` трассы + загрузки. +- `service-configuration`: секцию `[telemetry]` читает и relay, запись о его старте называет телеметрию. +- `graceful-shutdown`: relay при остановленном и замороженном Collector останавливается в прежний срок. + +## Impact + +- **API и контракт:** не меняются; ответы, коды, заголовки и тело сообщения брокера прежние. +- **Схема:** ревизия alembic — `attachment_jobs.traceparent` и `attachment_jobs.tracestate` (`text NULL`, CHECK формата + `NOT VALID`); прежний код на расширенной схеме работает, откат кода схему не откатывает. +- **Код:** `src/infra/telemetry/` (ленивый SDK, контекст, producer и consumer span, метрики уровня 4), + `src/infra/db/engine.py` (пул со счётом ожидающих), `src/infra/broker/client.py` (заголовки контекста), + `src/core/services/attachment.py`, `attachment_relay.py`, `attachment_processing.py` (итог доставки — DTO), + `src/core/ports/` и `src/core/repos/attachment_job.py` (колонки и снимок очереди), `src/infra/db/models/attachment.py`, + `src/schemas/dataclasses/`, `src/api/routers/v1/attachment.py`, `src/relay/main.py`, `src/worker/main.py`, + `src/utils/constants.py`, `src/config/settings.py` (докстринг секции). +- **Стенд:** `docker-compose.yml` (`x-telemetry-env` у relay), `infra/otel/grafana/dashboards/messenger-overview.json`; + `bench/bench.compose.yml`, `student-tests/failures.compose.yml`, `student-tests/run_isolated.py` — relay без телеметрии. + Collector, Prometheus, Loki и Tempo — без изменений, новых сервисов и портов нет; лимит памяти relay — по замеру. +- **Тесты и инструменты:** `service-tests/` (unit и db), драйвер скилла `run-mtusi-messenger` (`trace-chain`, + `telemetry-check`, `telemetry-outage`). +- **Документы:** `.claude/rules/` (`telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, + `dto.md`, `repo-layer.md`, `migrations.md`, `bench.md`, `student-tests.md`, `run-modes.md`), `AGENTS.md`, `REPORT.md`, + `QUESTIONS.md`, `SKILL.md`, `config_example.toml`, `.env.example`. diff --git a/openspec/changes/job-trace-propagation/specs/graceful-shutdown/spec.md b/openspec/changes/job-trace-propagation/specs/graceful-shutdown/spec.md new file mode 100644 index 0000000..a5a14fb --- /dev/null +++ b/openspec/changes/job-trace-propagation/specs/graceful-shutdown/spec.md @@ -0,0 +1,33 @@ +## MODIFIED Requirements + +### Requirement: Остановка при недоступном Collector + +С включённой телеметрией (capability `observability`) реплика API, worker и relay SHALL останавливаться по SIGTERM в +прежние сроки: API — требования «Завершение за заявленный срок» и «Остановка видна в журнале», worker — «Остановка worker», +relay — «Остановка relay», в том числе когда Collector остановлен или заморожен. Отправка накопленной телеметрии при +остановке SHALL ограничиваться своим сроком внутри этого бюджета; что не ушло за срок, теряется, а процесс MUST NOT ждать +Collector дольше. Запись об остановке процесса SHALL быть в stdout при любом состоянии Collector. + +Срок отправки при остановке SHALL входить в тот же бюджет, а не прибавляться к нему: у API с включённой телеметрией +`[app] graceful_shutdown_seconds` вместе со сроком закрытия SDK MUST NOT превышать 9 с (требование «Завершение за заявленный +срок»), иначе запуск SHALL останавливаться ошибкой проверки настроек с именем поля `app.graceful_shutdown_seconds`; без +телеметрии допустимы прежние 9 с. У worker и relay закрытие SDK SHALL идти внутри окна закрытия клиентов, и худший случай +остаётся прежним (требования «Остановка worker» и «Остановка relay»). + +#### Scenario: docker stop при остановленном Collector + +- **WHEN** Collector остановлен, реплика API только что обслуживала запросы, relay только что опубликовал задание, и + выполняется `docker stop` этой реплики, а затем `docker compose stop worker` и `docker compose stop relay` +- **THEN** все три команды завершаются быстрее 10 с, коды выхода контейнеров 0, а в stdout есть «Stopped API», «Stopped + worker» и «Stopped relay» + +#### Scenario: docker stop при замороженном Collector + +- **WHEN** контейнер Collector заморожен (`docker pause`), и выполняются те же остановки +- **THEN** все три команды завершаются быстрее 10 с, коды выхода 0, а в stdout есть записи об остановке + +#### Scenario: Срок остановки API не оставляет места закрытию SDK + +- **WHEN** API запускается с включённой телеметрией и `APP__GRACEFUL_SHUTDOWN_SECONDS=9` +- **THEN** запуск останавливается ошибкой проверки настроек, которая называет поле `app.graceful_shutdown_seconds` и + допустимый предел, а с выключенной телеметрией то же значение принимается diff --git a/openspec/changes/job-trace-propagation/specs/observability/spec.md b/openspec/changes/job-trace-propagation/specs/observability/spec.md new file mode 100644 index 0000000..3497827 --- /dev/null +++ b/openspec/changes/job-trace-propagation/specs/observability/spec.md @@ -0,0 +1,340 @@ +## ADDED Requirements + +### Requirement: Сквозная трасса загрузки и обработки + +При включённой телеметрии реплика API SHALL сохранять контекст W3C Trace Context server span загрузки — `traceparent` и, +если он не пуст, `tracestate` — в задании вложения той же транзакцией, что переводит вложение в `queued` и записывает +задание (`attachment-processing`, «Задание в PostgreSQL»). Контекст — только идентификаторы трассы и span и флаги W3C; +baggage MUST NOT сохраняться и переноситься. + +Relay SHALL на каждую публикацию задания с сохранённым контекстом создавать span вида `PRODUCER` — дочерний к сохранённому +контексту, по semantic conventions messaging: имя `publish <очередь>`, операция `send`, система, очередь, тип задания, номер +попытки сообщения, признак replay и причина повтора, если она есть. Контекст этого span SHALL уходить в заголовки сообщения +AMQP `traceparent` и `tracestate`: carrier — заголовки брокера, а поля `traceparent` и `tracestate` тела по +`contracts/jobs.schema.json` не заполняются (`contracts/attachment-states.md` это допускает; соответствие полей — в +`REPORT.md`). Публикация без подтверждения брокером — span со статусом ошибки и классом ошибки. Relay с выключенной +телеметрией SHALL класть в заголовки сохранённый контекст как есть. Задание без сохранённого контекста relay публикует без +этих заголовков и без span: трасс relay не начинает. + +Worker SHALL делать consumer span доставки дочерним к контексту из заголовков сообщения и добавлять в него link на этот же +контекст: сообщение обрабатывается по одному и без объемлющего span, а semantic conventions messaging для этого случая +допускают контекст создания сообщения родителем и требуют link на него. Без заголовков или с значением не по формату W3C +consumer span — корень своей трассы, как раньше; заголовок контекста MUST NOT влиять на обработку задания и его исход. +Флаг выборки контекста SHALL соблюдаться на всём пути: span под невыбранным родителем не записываются. Consumer span SHALL +нести номер попытки, признак повторной доставки брокером, а у исходов `retry` и `failed` — причину. + +Так у одной загрузки одна трасса: server span API, под ним span producer каждой публикации её задания, под каждым — consumer +span этой доставки с дочерними span PostgreSQL, S3 и процесса обработки. Повторная попытка, повторная доставка брокером и +replay — новые span producer и consumer в той же трассе. Атрибуты span MUST NOT содержать `id` задания, вложения и чата +(требование «Без секретов и содержимого в телеметрии»). + +#### Scenario: Цепочка одной загрузки + +- **WHEN** участник загружает файл, получает 202 с `X-Request-Id` R, и вложение становится `ready` +- **THEN** трасса T записи API с `request_id` R содержит server span загрузки `messenger-api`, под ним — span producer + `messenger-relay` с номером попытки 1, под ним — consumer span `messenger-worker` исхода `ready` с link на этот span + producer, а под consumer span — span PostgreSQL, чтения staging и записи оригинала и трёх вариантов в S3, процесса + обработки и фиксации +- **AND** записи worker этого вложения содержат `trace_id` T + +#### Scenario: Повторная попытка в той же трассе + +- **WHEN** worker остановлен, участник загрузил файл, S3 заморожен, worker запущен, его первая попытка закончилась + временной ошибкой S3, после чего S3 разморожен и вложение стало `ready` +- **THEN** в трассе загрузки два span producer — попыток 1 и 2, у второго причина повтора — и два consumer span: исхода + `retry` с номером попытки 1 и дочерним span S3 со статусом ошибки и исхода `ready` с номером попытки 2 и записью + оригинала и вариантов + +#### Scenario: Replay в той же трассе + +- **WHEN** вложение стало `failed`, потому что JPEG проходит проверку структуры, но не декодируется, а затем оператор + выполнил replay этого вложения +- **THEN** в трассе загрузки после consumer span исхода `failed` есть span producer с признаком replay и следующий consumer + span доставки этой попытки + +#### Scenario: Задание без контекста + +- **WHEN** у задания нет сохранённого контекста — строку записала прежняя версия кода или реплика с выключенной телеметрией +- **THEN** сообщение опубликовано без заголовков контекста и без span producer, consumer span его доставки — корень своей + трассы, а вложение становится `ready`, как раньше + +#### Scenario: Неверный контекст в заголовке + +- **WHEN** worker получает сообщение по схеме, у которого заголовок `traceparent` не по формату W3C +- **THEN** consumer span — корень новой трассы, а исход и подтверждение сообщения те же, что без заголовка + +#### Scenario: Relay без телеметрии + +- **WHEN** телеметрия relay выключена, у API и worker включена, и участник загружает файл +- **THEN** consumer span доставки — дочерний к server span загрузки, span relay в трассе нет, а вложение становится `ready` + +#### Scenario: Невыбранный контекст + +- **WHEN** сохранённый в задании контекст несёт флаг «не выбрано» +- **THEN** span producer и consumer этой загрузки не записываются, а исход и метрики задания те же, что у выбранной трассы + +### Requirement: SDK в relay + +Relay SHALL отправлять трассы, метрики и логи через SDK OpenTelemetry по правилам требования «SDK в API и worker»: тот же +ресурс (`service.name` — `messenger-relay`, `service.version`, `service.instance.id` — `instance_id` журнала relay, +`deployment.environment.name`), отправка только в Collector в фоне, ограниченные очереди, недоступный или зависший +Collector MUST NOT задерживать проходы и публикацию и приводить к ошибкам. Трасс relay MUST NOT начинать: его проходы и их +обращения к PostgreSQL и брокеру span не создают, а span relay — только span producer публикаций под сохранённым контекстом +задания (требование «Сквозная трасса загрузки и обработки»). Команда replay SDK MUST NOT запускать. + +#### Scenario: Ресурс relay + +- **WHEN** relay опубликовал задание загрузки +- **THEN** у его span producer и рядов метрик relay `service.name` — `messenger-relay`, `service.instance.id` — + `instance_id` журнала relay, а в Tempo нет трасс, корень которых — span relay + +#### Scenario: Collector недоступен для relay + +- **WHEN** Collector остановлен, и участник загружает файл +- **THEN** вложение становится `ready`, у контейнера relay прежнее время старта и счётчик перезапусков 0, а после запуска + Collector span и метрики relay снова приходят в хранилища без перезапуска relay + +### Requirement: Время до готовности + +Каждое вложение, ставшее `ready` без replay, SHALL учитываться в histogram времени до готовности в секундах — +`messenger.job.time_to_ready` (в Prometheus — `messenger_job_time_to_ready_seconds`) с атрибутом типа задания. Начало — +устойчивый приём: запись задания вместе с переводом вложения в `queued`, до ответа 202; конец — фиксация `ready` worker. +Ожидание в очереди, повторные попытки с паузами и возврат по аренде в это время входят. Задание, возвращённое replay, MUST +NOT учитываться: его приём — действие оператора, а не загрузка (ограничение в `REPORT.md`). Повторная доставка готового +вложения нового наблюдения MUST NOT давать. Границы buckets SHALL покрывать задержки от долей секунды до десяти минут. + +#### Scenario: Время до готовности в метрике + +- **WHEN** worker остановлен, участник загрузил файл, через N секунд worker запущен, и вложение стало `ready` +- **THEN** счёт `messenger_job_time_to_ready_seconds_count` worker вырос на 1, а сумма — не меньше чем на N + +#### Scenario: Replay не учитывается + +- **WHEN** вложение, возвращённое replay, становится `ready` +- **THEN** счёт времени до готовности не меняется, а исход `ready` в метрике заданий учтён + +### Requirement: Глубина и возраст очереди + +Глубину очереди заданий и возраст старейшего незавершённого задания SHALL измерять один процесс — relay — по PostgreSQL, где +истина о заданиях, а не каждая реплика API и не брокер. Relay с включённой телеметрией SHALL обновлять снимок каждые 5 с, +пока его проходы успешны, одним запросом по частичным индексам заданий, без просмотра всей таблицы. + +- `messenger.queue.depth` (в Prometheus — `messenger_queue_depth`), единица — задания; атрибуты — очередь + `messaging.destination.name` и стадия `messenger.queue.stage`: `scheduled` — ждёт срока следующей попытки, `outbox` — срок + наступил, relay ещё не опубликовал, `published` — опубликовано, worker не взял, `processing` — идёт попытка. Сумма стадий + — все незавершённые задания (`queued` и `processing`). +- `messenger.queue.oldest_age` (в Prometheus — `messenger_queue_oldest_age_seconds`), секунды — возраст старейшего + незавершённого задания от его устойчивого приёма; незавершённых нет — 0. Это накопление, а не время обработки. + +Снимок, который relay не смог обновить дольше 30 с, relay MUST NOT отдавать как текущий. Атрибутов с `id` нет. + +#### Scenario: Очередь при остановленном worker + +- **WHEN** worker остановлен, и участник загружает K файлов +- **THEN** через интервал отправки и сбора метрик сумма стадий `outbox` и `published` — K, а возраст не меньше времени с + первой загрузки за вычетом интервала и растёт +- **AND** после запуска worker и `ready` всех вложений глубина всех стадий и возраст — 0 + +#### Scenario: Один источник очереди + +- **WHEN** стенд работает +- **THEN** ряды `messenger_queue_depth` и `messenger_queue_oldest_age_seconds` есть только у `job="messenger-relay"` + +#### Scenario: Ожидание следующей попытки + +- **WHEN** попытка задания закончилась временной ошибкой, и срок следующей попытки ещё не наступил +- **THEN** задание учтено в стадии `scheduled`, а когда срок наступил и relay его не опубликовал — в стадии `outbox` + +#### Scenario: Снимок устарел + +- **WHEN** relay не может прочитать PostgreSQL дольше 30 с +- **THEN** relay не отдаёт значений глубины и возраста, пока снимок не обновится, а после возврата PostgreSQL отдаёт снова + +### Requirement: Пул соединений PostgreSQL + +Каждый процесс с SDK — реплика API, worker и relay — SHALL отдавать состояние своего пула соединений PostgreSQL по +semantic conventions: `db.client.connection.count` с `db.client.connection.state` — `used` или `idle`, +`db.client.connection.max` — предел пула, `db.client.connection.pending_requests` — запросы соединения, которые сейчас ждут +свободного или его открытия, `db.client.connection.timeouts` — отказы по сроку ожидания пула; атрибут — имя пула. В +Prometheus — `db_client_connection_*` с `job` и `instance` процесса. Предел — размер пула процесса вместе с переполнением. + +#### Scenario: Пулы процессов стенда + +- **WHEN** стенд работает под `make load` +- **THEN** у каждой реплики API предел пула 10, у worker 2, у relay 1, занятых не больше предела, и ряды есть у каждого + процесса с SDK + +#### Scenario: Пул исчерпан + +- **WHEN** все соединения пула процесса заняты, и ещё один блок ждёт соединения дольше срока ожидания пула +- **THEN** пока он ждёт, `pending_requests` больше 0, а его отказ по сроку увеличивает `timeouts` на 1 + +### Requirement: Насыщение worker + +Worker SHALL отдавать: `messenger.worker.busy` — сколько доставок сейчас занимают место конкуренции, +`messenger.worker.capacity` — сколько мест (`[worker] concurrency`), `messenger.worker.waiting` — сколько полученных от +брокера доставок ждут места. Насыщение — отношение занятых мест к ёмкости по всем worker; среднее за окно — сумма +длительностей обработки доставок (`messenger_job_duration_seconds_sum`) за секунду к ёмкости. + +#### Scenario: Ёмкость и занятость + +- **WHEN** worker с конкуренцией 2 обрабатывает две доставки, а третья полученная доставка ждёт места +- **THEN** ёмкость — 2, занятых мест — 2, ожидающих — 1, а после обработки всех трёх занятых и ожидающих — 0 + +### Requirement: CPU и память контейнеров приложения + +Реплика API, worker и relay SHALL отдавать CPU и память своего контейнера по его cgroup изнутри контейнера: +`container.cpu.time` — CPU в секундах, счётчик (в Prometheus — `container_cpu_time_seconds_total`), `container.memory.usage` +— память в байтах (`container_memory_usage_bytes`), а также предел CPU в ядрах и предел памяти в байтах; у worker — вместе с +процессами обработки. Collector и сервисы приложения MUST NOT получать доступ к сокету Docker. Процесс без файлов cgroup v2 +этих метрик не отдаёт и пишет об этом одну запись при старте. Контейнеры без SDK — PostgreSQL, S3, брокер, LB, уборщик — в +этих метриках не представлены (ограничение в `REPORT.md`). + +#### Scenario: Пределы как в compose + +- **WHEN** стенд работает +- **THEN** у каждой реплики API, worker и relay предел CPU и предел памяти совпадают с `deploy.resources.limits` их сервиса, + память меньше предела, а CPU растёт под нагрузкой + +#### Scenario: Без сокета Docker + +- **WHEN** проверяющий смотрит `docker compose config` +- **THEN** ни у одного сервиса нет монтирования сокета Docker + +### Requirement: Панели уровня 4 + +Dashboard из git SHALL показывать сверх панелей уровня 3 (требование «Grafana из provisioning»): +- квантили p50, p95 и p99 длительности HTTP и обработки заданий — `histogram_quantile` по сумме buckets всех реплик и + worker, а не среднее квантилей; +- долю ошибок по определению требования «Метрики HTTP API»: 5xx к учтённым запросам, 4xx отдельно; +- глубину очереди по стадиям и возраст старейшего задания; +- квантили времени до готовности; +- пул каждого процесса: занятые к пределу, ожидающие, отказы по сроку; +- насыщение worker: занятые места к ёмкости и среднее за окно; +- CPU и память контейнеров приложения к их пределам. + +Запросы панелей SHALL ссылаться на имена и метки, которые есть в Prometheus, а запросы и единицы — быть в `REPORT.md`. + +#### Scenario: Панели уровня 4 после трафика + +- **WHEN** стенд поднят, выполнены `make test` и загрузка файла до `ready` +- **THEN** каждый запрос панелей уровня 4 к Prometheus выполняется без ошибки и возвращает данные, а квантили считаются из + `sum by (le)` buckets + +### Requirement: Цепочка и сигналы уровня 4 находятся + +Проверка стенда (команда драйвера скилла `run-mtusi-messenger`) SHALL находить только по сохранённым наблюдениям, через +источники Grafana: +- при остановленном worker — рост глубины очереди и возраста старейшего задания, а после запуска worker — их спад до 0; +- по одной загрузке с вынужденной повторной попыткой — трассу требования «Сквозная трасса загрузки и обработки» со связями + parent и link, span S3 с ошибкой в первой попытке и записью оригинала и вариантов во второй, и записи worker с тем же + `trace_id`; +- replay в той же трассе и задание без контекста — корень трассы в worker; +- рост времени до готовности, пулы, насыщение worker, CPU и память контейнеров и данные панелей уровня 4. + +Проверка SHALL печатать таблицу «шаг → ожидаемо → получено», завершаться ненулевым кодом при расхождении, MUST NOT печатать +секреты и SHALL возвращать стенд при любом исходе: S3 разморожен, worker и relay запущены. Её вывод SHALL быть сохранён в +`evidence/telemetry/`. + +#### Scenario: Проверка цепочки + +- **WHEN** проверка выполняется на рабочем стенде с телеметрией +- **THEN** она завершается с кодом 0, а таблица содержит шаги очереди, цепочки с повторной попыткой, replay, задания без + контекста и сигналов уровня 4 с совпавшими значениями + +## MODIFIED Requirements + +### Requirement: SDK в API и worker + +Процессы API (каждая реплика) и worker SHALL отправлять трассы, метрики и логи через SDK OpenTelemetry. Ресурс всех трёх +сигналов SHALL содержать: +- `service.name` — `messenger-api` у реплик API, `messenger-worker` у worker; +- `service.version` — версию контракта API, которую реализует код (`info.version` в `contracts/openapi.json`); +- `service.instance.id` — то же значение, что `instance_id` журнала процесса и `X-Instance-Id` его ответов; +- `deployment.environment.name` — из настроек, по умолчанию `lab` (`service-configuration`, «Параметры телеметрии»). + +Уборщик, сервис миграций, команда replay и процесс обработки изображения SDK MUST NOT запускать: их журнал — stdout +контейнера, а работа процесса обработки видна span в трассе worker. Relay запускает SDK по требованию «SDK в relay». + +Телеметрия MUST NOT влиять на ответы API и обработку заданий: отправка идёт в фоне, очереди SDK ограничены, недоступный или +зависший Collector MUST NOT задерживать запросы и задания и приводить к ошибкам, и SDK SHALL продолжать отправку, когда +Collector вернулся, без перезапуска процесса. Телеметрия, которую не удалось отправить, теряется. Записи самого SDK об +отказе отправки SHALL идти только в stdout и не чаще одной записи в минуту от каждого модуля SDK. + +API MUST NOT продолжать трассу клиента: входящие `traceparent` и `tracestate` игнорируются, каждый запрос начинает свою +трассу (публичная точка входа). Контекст внутри стенда переносит задание (требование «Сквозная трасса загрузки и +обработки»). + +#### Scenario: Ресурс сигналов + +- **WHEN** клиент получил ответ API с `X-Instance-Id` I, а worker обработал задание +- **THEN** у трассы, записей лога и рядов метрики этого ответа `service.name` — `messenger-api`, `service.instance.id` — I, + `service.version` — версия контракта, `deployment.environment.name` — `lab`; у сигналов задания `service.name` — + `messenger-worker` и `service.instance.id` — `instance_id` из журнала worker + +#### Scenario: Collector остановлен + +- **WHEN** Collector остановлен, выполняется `make test` и участник загружает файл +- **THEN** `make test` печатает `PASS`, `/health/ready` отвечает 200, вложение становится `ready`, журнал stdout пишется без + потерь и без потока записей об отказе отправки, а после запуска Collector новые трассы, логи и метрики API и worker + приходят в хранилища без перезапуска процессов + +#### Scenario: Collector заморожен + +- **WHEN** контейнер Collector заморожен (`docker pause`), и выполняется `make test` +- **THEN** `make test` печатает `PASS`, а после разморозки сигналы приходят снова + +#### Scenario: Чужой traceparent + +- **WHEN** клиент присылает запрос с `traceparent`, в котором trace-id X +- **THEN** трасса этого запроса в Tempo имеет другой trace-id, у server span нет родителя, и X нет ни в Tempo, ни в Loki + +### Requirement: Где телеметрия включена + +Телеметрия SHALL быть включена на рабочем стенде compose у реплик API, worker и relay. В консоли (`make run_dev`, `make +run_worker`, `make run_relay`), во временном прогоне `make test_isolated`, на стенде отказов `make failure_checks` и на +стенде `bench/` она SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние, а профиль, которому нужна +телеметрия, включает её явно. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей +журнала, ни обращений к Collector, ни полей трассы в журнале, ни модулей SDK и экспортёра в памяти процесса. Модулей SDK +MUST NOT загружать и процессы, которые SDK не запускают: уборщик, сервис миграций, команда replay. Вариант «телеметрия +выключена» трека 1 — та же одна настройка. + +#### Scenario: Консоль без телеметрии + +- **WHEN** сервис запущен `make run_dev` без настроек телеметрии +- **THEN** запись о старте говорит, что телеметрия выключена, попыток отправки нет, а в записях журнала нет `trace_id` + +#### Scenario: Тестовые стенды без телеметрии + +- **WHEN** выполняются `make test_isolated` и `make failure_checks` +- **THEN** записи о старте их API, worker и relay говорят, что телеметрия выключена, Collector на этих стендах не + запускается, а результаты проверок прежние + +#### Scenario: Модули SDK без телеметрии не загружаются + +- **WHEN** код процессов API, worker, relay и уборщика импортирован при выключенной телеметрии +- **THEN** ни одного модуля SDK и экспортёра OpenTelemetry, protobuf и HTTP-клиента экспортёра в процессе нет + +### Requirement: Наблюдаемость в отчёте + +`REPORT.md` SHALL описывать: +- назначение Collector и каждого хранилища: на какой вопрос об инциденте отвечают метрика, лог и трасса; +- закреплённые версии SDK, semantic conventions, дистрибутива Collector, хранилищ и Grafana; +- таблицу «логический сигнал контракта → инструмент SDK → имя и метки в Prometheus или поля в Loki и Tempo → единица» и + запросы панелей dashboard — для сигналов уровней 3 и 4; +- определение доли ошибок HTTP и успешных и ошибочных заданий; +- перенос контекста: где он хранится, какие заголовки сообщения его несут и как они соответствуют полям `traceparent` и + `tracestate` `contracts/jobs.schema.json`, почему consumer span — дочерний с link, что с заданиями без контекста и со + смесью версий при замене; +- источник глубины и возраста очереди и почему CPU и память берутся из cgroup контейнера, а не через сокет Docker; +- соответствие атрибутов ресурса меткам хранилищ и имён `OTEL_*` skeleton настройкам; +- сумму лимитов стенда с телеметрией против ресурсов ВМ и замер простоя и пика сервисов телеметрии и процессов с SDK; +- ограничения: что теряется при отказе Collector, ответы балансировщика вне метрик API, приём OTLP без аутентификации до + лабы 7, мгновенные значения пула и насыщения раз в интервал отправки, устаревший снимок очереди, контейнеры без SDK вне + метрик, задания после replay вне времени до готовности. + +#### Scenario: Отчёт по наблюдаемости + +- **WHEN** проверяющий читает `REPORT.md` +- **THEN** для каждого сигнала уровней 3 и 4 есть имя, единица и запрос, для каждого хранилища — назначение и версия, для + переноса контекста — отображение заголовков сообщения на поля схемы задания, а для суммы лимитов — числа и замер diff --git a/openspec/changes/job-trace-propagation/specs/service-configuration/spec.md b/openspec/changes/job-trace-propagation/specs/service-configuration/spec.md new file mode 100644 index 0000000..d1a9c7d --- /dev/null +++ b/openspec/changes/job-trace-propagation/specs/service-configuration/spec.md @@ -0,0 +1,55 @@ +## MODIFIED Requirements + +### Requirement: Параметры телеметрии + +Телеметрию API, worker и relay (capability `observability`) SHALL настраивать секция `[telemetry]`: +- `enabled` — включена ли телеметрия, по умолчанию выключена; рабочий стенд compose включает её в окружении реплик API, + worker и relay; +- `otlp_endpoint` — адрес OTLP/HTTP Collector (схема `http` или `https`, хост и порт, без пути и query), по умолчанию + `http://127.0.0.1:4318`; на стенде — Collector в сети compose; +- `environment` — значение `deployment.environment.name`, по умолчанию `lab`; +- интервал отправки метрик, срок одной отправки, размер очереди и пакета SDK и пауза между пакетами — с безопасными + значениями по умолчанию; положительные числа, пакет не больше очереди. + +Неверное значение MUST останавливать запуск с именем поля (требование «Некорректное значение останавливает запуск»). +Разовая подмена SHALL работать через окружение `TELEMETRY__*` без правки файлов. Секцию применяют только процессы API, +worker и relay; уборщик, миграции и команда replay телеметрию не запускают при любом её значении. + +Переменные `OTEL_*` стандарта OpenTelemetry настройками сервиса MUST NOT быть, как любые переменные без секции (требование +«Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни параметры очередей, а процесс с +включённой телеметрией, у которого такие переменные есть в окружении, SHALL писать запись `warning` с их именами, без +значений. Имена skeleton (`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, +`OTEL_RESOURCE_ATTRIBUTES`) сопоставлены настройкам и постоянным значениям кода в `.env.example` и `REPORT.md`. + +Запись журнала о старте API, worker и relay SHALL называть, включена ли телеметрия, а при включённой — адрес Collector и +окружение. + +#### Scenario: Телеметрия по умолчанию выключена + +- **WHEN** сервис запущен без секции `[telemetry]` и без переменных `TELEMETRY__*` +- **THEN** запись о старте говорит, что телеметрия выключена, и сервис не обращается к адресу Collector + +#### Scenario: Включение окружением + +- **WHEN** worker запущен с `TELEMETRY__ENABLED=true` и `TELEMETRY__OTLP_ENDPOINT`, указывающим на Collector, а файлы не + менялись +- **THEN** запись о старте называет этот адрес, а трассы, метрики и логи worker приходят в хранилища + +#### Scenario: Телеметрия relay + +- **WHEN** relay запущен на рабочем стенде compose, а затем в консоли `make run_relay` +- **THEN** запись о старте relay стенда называет телеметрию включённой, адрес Collector и окружение, а консольного — + выключенной + +#### Scenario: Неверный параметр телеметрии + +- **WHEN** сервис запускается с `TELEMETRY__OTLP_ENDPOINT=collector:4318`, с отрицательным интервалом отправки метрик или с + пакетом больше очереди +- **THEN** сервис не стартует, в журнале — ошибка проверки настроек с именем поля + +#### Scenario: Переменные OTEL_* не действуют + +- **WHEN** процесс с включённой телеметрией запущен с `OTEL_SDK_DISABLED=true` и `OTEL_EXPORTER_OTLP_ENDPOINT`, указывающим в + другое место +- **THEN** сигналы по-прежнему приходят в Collector из `[telemetry]`, а в журнале есть запись `warning` с именами этих + переменных без значений diff --git a/openspec/changes/job-trace-propagation/specs/service-logging/spec.md b/openspec/changes/job-trace-propagation/specs/service-logging/spec.md new file mode 100644 index 0000000..8bdf241 --- /dev/null +++ b/openspec/changes/job-trace-propagation/specs/service-logging/spec.md @@ -0,0 +1,71 @@ +## MODIFIED Requirements + +### Requirement: Связь записей с трассой + +При включённой телеметрии (capability `observability`, «Где телеметрия включена») запись журнала API, worker или relay, +сделанная при активном span, SHALL содержать `trace_id` (32 шестнадцатеричных символа) и `span_id` (16 символов) этого span +— и в stdout, и в записи, отправленной в хранилище логов. Это записи обработки запроса, кроме health, в том числе итоговая +запись о запросе, и записи обработки доставки worker. У задания с сохранённым контекстом доставка идёт в трассе загрузки +(capability `observability`, «Сквозная трасса загрузки и обработки»): её записи содержат `trace_id` трассы загрузки этого +вложения. Записи вне span — старт, остановка, health, фоновые циклы, проходы relay — этих полей MUST NOT содержать. +`request_id` остаётся прежним: `trace_id` его не заменяет (`contracts/observability.md`). + +#### Scenario: Записи запроса ведут к трассе + +- **WHEN** клиент получил ответ с `X-Request-Id` R, а телеметрия включена +- **THEN** все записи stdout с `request_id` R, включая итоговую запись о запросе, содержат один и тот же `trace_id` T и + `span_id`, а трасса T в Tempo — трасса этого запроса + +#### Scenario: Записи задания ведут к трассе + +- **WHEN** worker довёл вложение до `ready` +- **THEN** записи этого задания («Started job attempt», «Attachment became ready») содержат `trace_id` трассы обработки + задания — того же значения, что у записи «Uploaded attachment» его загрузки, если у задания был сохранённый контекст + +#### Scenario: Проход relay без полей трассы + +- **WHEN** relay публикует задание загрузки +- **THEN** его запись о проходе не содержит `trace_id` и `span_id`, хотя span producer этой публикации есть в трассе + загрузки + +#### Scenario: Без телеметрии полей нет + +- **WHEN** телеметрия выключена, и клиент выполняет запрос +- **THEN** записи журнала не содержат `trace_id` и `span_id`, а остальные поля прежние + +### Requirement: Журнал в хранилище логов + +При включённой телеметрии каждая запись журнала API, worker и relay, которая пишется в stdout между запуском SDK и началом +его закрытия при остановке, SHALL ещё и отправляться в хранилище логов через Collector; записи до запуска SDK (записи uvicorn +до lifespan, остановка до старта, ошибки настроек) и после начала закрытия (записи «Stopped worker» и «Stopped relay») идут +только в stdout. Отправленная запись: тело — `event`, уровень — из `level`, время — `timestamp`, остальные поля записи — +атрибутами, ресурс — `service.name` и остальные атрибуты процесса (capability `observability`, «SDK в API и worker» и «SDK в +relay»). Записи stdout при этом MUST NOT меняться, кроме полей трассы (требование «Связь записей с трассой»). Записи самого +SDK OpenTelemetry идут только в stdout. Отказ отправки MUST NOT задерживать запись и обработку и MUST NOT терять записи +stdout. + +В хранилище записи SHALL искаться по сервису и экземпляру (метки потока) и по полям записи, в том числе `request_id`, +`attachment_id`, `trace_id`. Требование «Без содержимого сообщений и личных данных» действует на отправленные записи так же, +как на stdout. + +#### Scenario: Запись в Loki совпадает со stdout + +- **WHEN** клиент получил ответ с `X-Request-Id` R и `X-Instance-Id` I +- **THEN** в Loki есть итоговая запись о запросе с `service_name` = `messenger-api`, `request_id` R, `instance_id` I, тем же + `event`, методом, шаблоном пути, статусом и длительностью, что в stdout реплики, и с тем же `trace_id` + +#### Scenario: Записи relay в Loki + +- **WHEN** relay публикует задание загрузки +- **THEN** в Loki есть его запись о проходе с `service_name` = `messenger-relay`, тем же `event` и числом опубликованных, + что в stdout relay + +#### Scenario: Ошибка с traceback в Loki + +- **WHEN** обработка запроса падает с непредвиденным исключением +- **THEN** запись `error` с traceback и `request_id` ответа 500 есть и в stdout, и в Loki + +#### Scenario: Отказ отправки журнала + +- **WHEN** Collector остановлен, и клиент выполняет запросы +- **THEN** все записи этих запросов есть в stdout, ответы прежние, а в stdout нет потока записей об отказе отправки diff --git a/openspec/changes/job-trace-propagation/tasks.md b/openspec/changes/job-trace-propagation/tasks.md new file mode 100644 index 0000000..4ae335b --- /dev/null +++ b/openspec/changes/job-trace-propagation/tasks.md @@ -0,0 +1,206 @@ +# Tasks + +Решения — `design.md` (номера в скобках), требования — `specs/`. Стенд — проект `mtusi-lab6`; `make wipe_data`, `down -v` и +`docker volume rm` агенту запрещены. Известно и не чинится здесь: до последнего шага лабы `make student_test` красный ровно +одним `test_exclusion_evidence_exists` (10 файлов evidence, `QUESTIONS.md`). Evidence — только с закоммиченного кода: +коммит делает основная сессия между стадиями, поэтому раздел 12 выполняется после коммита кода (apply доводит разделы +1–11, оставляет 12 неотмеченным и называет это в отчёте). Пробные прогоны команд до коммита — в scratchpad, не в `evidence/`. + +## 1. Правила, константы, DTO + +- [ ] 1.1 Прочитать (Read) правила `telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, + `dto.md`, `repo-layer.md`, `migrations.md`, `service-layer.md`, `api-layer.md`, `service-tests.md`, `bench.md`, + `student-tests.md`, `run-modes.md` — до правок файлов их слоёв. Проверка: каждое прочитано через Read в этой сессии. +- [ ] 1.2 Константы `src/utils/constants.py` (13): `TELEMETRY_SERVICE_RELAY = "messenger-relay"`, имена метрик уровня 4, + атрибуты (`messaging.*`, `messenger.job.attempt`, `.replayed`, `.retry_reason`, `.redelivered`, `.reason`, `.error_code`, + `messenger.queue.stage`, `db.client.connection.*`), значения стадий, границы `TIME_TO_READY_BUCKETS` (8), + `QUEUE_SNAPSHOT_INTERVAL_SECONDS = 5`, `QUEUE_SNAPSHOT_STALE_SECONDS = 30`, путь cgroup, `TRACEPARENT_PATTERN` и + `TRACESTATE_MAX_LENGTH` — им же пользуется `src/schemas/jobs/attachment.py` вместо своих литералов. Проверка: `make lint`; + `uv run python -c "import src.schemas.jobs"`. +- [ ] 1.3 DTO `src/schemas/dataclasses/` (`dto.md`): `TraceContextDTO(traceparent, tracestate=None)`, + `JobPublicationDTO` (id, тело, номер попытки, признак replay, причина повтора, контекст), `JobDeliveryResultDTO` (исход, + попытка, причина, код ошибки, время до готовности), `QueueSnapshotDTO` (время снимка, четыре стадии, `oldest_created_at`); + `AttachmentJobDTO` — поля `traceparent`, `tracestate` последними со значением `None`; экспорт в `__init__.py` по алфавиту. + Проверка: `make service_test` (`test_architecture` и прежние тесты зелёные). + +## 2. Схема и repo + +- [ ] 2.1 Модель `AttachmentJob` и ревизия alembic поверх `d3f9a6b2c1e7` (4): `traceparent`, `tracestate` (`text NULL`), + CHECK `ck_attachment_jobs_traceparent` и `ck_attachment_jobs_tracestate` `NOT VALID`, первой строкой `SET LOCAL + lock_timeout = '2s'`, `downgrade` зеркально; имя файла по `file_template`, литералы вместо констант. Проверка на временной + базе: `upgrade` с нуля, повтор, `downgrade -1`, снова `upgrade`; `alembic upgrade --sql` содержит `lock_timeout` и `NOT + VALID`; autogenerate после ревизии изменений не находит. +- [ ] 2.2 Repo заданий (4, 9): `insert_job` пишет `traceparent` и `tracestate`, `_JOB_COLUMNS` их читает; новый метод + `queue_snapshot(*, now)` — порт с докстрингом-контрактом, SQL одним выражением по частичным индексам, состояния — + `literal_execute`; фейк `FakeAttachmentJobRepository` (вставка с контекстом, снимок по стадиям); строки + `service-tests/repo_contract.py` — контекст после вставки и после `lock_due_jobs`, стадии `scheduled` / `outbox` / + `published` / `processing`, `oldest_created_at` и пустая очередь. Проверка: `make service_test` (контракт на фейке) и `make + service_test_db` (контракт на SQL). + +## 3. Пакет телеметрии + +- [ ] 3.1 Ленивый импорт (7): SDK, экспортёр и `requests` — новый модуль `src/infra/telemetry/sdk.py`, его импортирует + `start()`; остальные модули пакета — только `opentelemetry-api` (типы SDK — под `TYPE_CHECKING`). Проверка: тест 8.1 + «модули SDK без телеметрии» (отдельный интерпретатор: после импорта `src.main`, `src.worker.main`, `src.relay.main`, + `src.cleaner.main` нет `opentelemetry.sdk`, `opentelemetry.exporter`, `google.protobuf`, `requests`); прежние тесты + `test_telemetry.py` зелёные. +- [ ] 3.2 Sampler `ParentBased(ALWAYS_ON)` (5), propagator `TraceContextTextMapPropagator` без глобального propagator и + baggage; `current_trace_context()` — `TraceContextDTO` текущего валидного span (невыбранный — с флагом `00`), иначе `None`. + Проверка: тесты 8.1 (в server span — его `traceparent`, вне span и без телеметрии — `None`, удалённый родитель с флагом + `00` — span не записывается). +- [ ] 3.3 Span producer (3): контекстный менеджер с родителем — сохранённым контекстом, `PRODUCER` `publish <очередь>`, + атрибуты решения 13, ошибка и отмена — `ERROR` и класс; отдаёт заголовки для сообщения (контекст span; без телеметрии — + сохранённый контекст как есть; без контекста — пусто и без span). Проверка: тесты 8.1. +- [ ] 3.4 Consumer span (2): родитель — контекст из доставки и link на него, без контекста — корень `Context()`, как раньше; + `messaging.operation.name`, повторная доставка; `JobObservation.finish(result=…)` — атрибуты попытки, причины, кода ошибки + и запись `messenger.job.time_to_ready` (View с границами решения 8), если в итоге есть время. Проверка: тесты 8.1 и прежний + `test_delivery_outcome_span_and_histogram` (без контекста у span нет родителя). +- [ ] 3.5 Пул (10): `CountingQueuePool(AsyncAdaptedQueuePool)` в `src/infra/db/engine.py` (`connect()` со счётом ожидающих и + отказов по сроку, методы `pending()`, `timeouts()`), `poolclass=` в `create_engine`; `instrument_engine` регистрирует + `db.client.connection.*` с чтением текущего пула engine и именем `server.address:server.port/db.namespace`. Проверка: тесты + 8.1 и 8.4. +- [ ] 3.6 Насыщение worker и очередь (9, 11): регистрация наблюдаемых `messenger.worker.busy` / `.capacity` / `.waiting` по + переданным счётчикам и gauge очереди по последнему снимку (стадии, возраст, снимок старше 30 с не отдаётся). Проверка: + тесты 8.1. +- [ ] 3.7 Контейнер (12): модуль чтения cgroup v2 (`cpu.stat`, `memory.current`, `cpu.max`, `memory.max`, `max` — без + точки), регистрация в `start_process_telemetry` с корнем cgroup — параметром (по умолчанию константа), без файлов — одна + запись `warning` «Container metrics are unavailable». Проверка: тест 8.1 на временном каталоге; прежние тесты журнала + `test_telemetry.py` на macOS не получают лишних записей; на стенде после 10.3 — пределы совпадают с `docker inspect`. + +## 4. Загрузка в API + +- [ ] 4.1 Зависимость `TraceContextDep` в `src/api/dependencies.py` (4), ручка загрузки передаёт `trace_context=` в + `AttachmentService.upload` (докстринг ручки — без «брокер подтвердил сообщение»), сервис — до `_mark_queued` и в + `AttachmentJobDTO`. Сервис телеметрию не импортирует. Проверка: тесты 8.2 (контекст в строке задания, без него — `None`); + `make test` на стенде после 10.3. + +## 5. Relay + +- [ ] 5.1 `AttachmentRelayService` (3, 9): элементы публикации `JobPublicationDTO` из строк задания (номер попытки, признак + replay `attempt_base > 0`, причина повтора — `last_error_code`, контекст из колонок); метод `queue_snapshot()` — один блок. + Проверка: тесты 8.2 (`test_attachment_relay.py`). +- [ ] 5.2 `JobPublisher` (3): `publish_many(items)` принимает `JobPublicationDTO`, `_publish_one` открывает span producer и + кладёт его заголовки в `aio_pika.Message(headers=…)`; срок пакета и сброс соединения прежние; `FakeJobPublisher` хранит + элементы с контекстом. Проверка: тест 8.1 на фейковом канале (заголовки сообщения, span на каждое), `test_architecture` + (сигнатуры клиента и фейка). +- [ ] 5.3 `src/relay/main.py` (7, 9, 15): запуск телеметрии после `early_stop.disarm()`, `instrument_engine`, gauge + очереди; в `_serve` после успешного прохода — снимок не чаще 5 с только при включённой телеметрии, отказ PostgreSQL — + пропуск; закрытие SDK в окне `gather` 0,5 с, «Stopped relay» после него; «Started relay» — `telemetry_enabled`, + `telemetry_endpoint`, `telemetry_environment`. Команда replay SDK не запускает. Проверка: тест 8.2 (цикл со снимком на + фейках); на стенде — запись о старте и `driver.py --port 8080 relay-process` с кодом 0; в консоли `make run_relay` — + `telemetry_enabled: false` (сценарий «Телеметрия relay»). +- [ ] 5.4 Окружение: у `relay` в `docker-compose.yml` — `*telemetry-env`; `TELEMETRY__ENABLED: "false"` у relay в + `bench/bench.compose.yml` и `student-tests/failures.compose.yml`, `-e TELEMETRY__ENABLED=false` у контейнера relay в + `student-tests/run_isolated.py`. Проверка: `docker compose config --quiet` рабочего стенда, CI (`-f .github/ci/compose.yml`), + `bench/` и стенда отказов; в `docker compose config` у relay рабочего стенда `TELEMETRY__ENABLED: "true"`, у остальных — + `"false"`; ни у одного сервиса нет монтирования сокета Docker. + +## 6. Worker + +- [ ] 6.1 `JobConsumer.deliveries()` (1, 6): `JobDelivery.trace_context` из заголовков `traceparent` и `tracestate` (`str` + или ASCII `bytes`, шаблон W3C, длина `tracestate`), иначе `None`; разбор тела не меняется. Проверка: тест 8.1 (верный, + `bytes`, не по шаблону, длинный `tracestate`, нет заголовков). +- [ ] 6.2 `AttachmentProcessingService.handle()` → `JobDeliveryResultDTO` (8): попытка, причина у `retry` и `failed`, код + ошибки у `failed`, время до готовности у `ready` без replay — после фиксации `ready` от `job.created_at`. Быстрые тесты + сервиса — через `.outcome` и новые поля. Проверка: `make service_test` (`test_attachment_processing.py`). +- [ ] 6.3 `src/worker/main.py` (2, 8, 11): `consumer_span(parent=delivery.trace_context, redelivered=…)`, счётчики «ждут + места» и «заняты» вокруг `async with slots` (снимаются в `finally`), регистрация насыщения, `observation.finish(result=…)`, + действие с сообщением — из `result.outcome`. Проверка: тесты 8.1 и `test_worker_deliveries.py`. + +## 7. Dashboard уровня 4 + +- [ ] 7.1 `infra/otel/grafana/dashboards/messenger-overview.json` (14): p99 в панелях длительности HTTP и обработки, строки + «Pipeline» (глубина по стадиям, возраст, время до `ready` p50 / p95 / p99) и «Saturation» (пул, ожидающие и отказы, worker, + CPU и память контейнеров к пределам) с запросами и единицами решения 14; uid источников прежние. Проверка: `python3 -m + json.tool` без ошибок; после 10.3 и `docker compose restart grafana` — dashboard provisioned, каждый запрос новых панелей к + Prometheus через Grafana выполняется и возвращает данные (обход панелей `telemetry-check`). + +## 8. Быстрые тесты + +- [ ] 8.1 `service-tests/unit/test_telemetry.py` на in-memory экспортёрах: контекст загрузки; span producer (родитель и trace + id из сохранённого контекста, заголовки — его контекст, атрибуты, ошибка и отмена; без телеметрии — заголовки как есть; без + контекста — ни span, ни заголовков); `JobPublisher._publish_one` на фейковом канале; consumer span (родитель и link, + корень без контекста и с неверным, флаг `00` — не записан); время до готовности (replay — нет точки); пул на фейковом пуле; + насыщение worker в `_handle` при занятом месте; gauge очереди (свежий и устаревший снимок); контейнер на временном каталоге + cgroup и без него; ресурс relay; разбор заголовков доставки; модули SDK без телеметрии — в отдельном интерпретаторе. + Проверка: `make service_test`. +- [ ] 8.2 Тесты сервисов: `test_attachment_service.py` (контекст в задании и `None`), `test_attachment_relay.py` (элементы + публикации: контекст, номер попытки, replay, причина; снимок очереди), `test_attachment_processing.py` (поля итога по + исходам, время до готовности и его отсутствие после replay), `test_worker_deliveries.py` (контекст доставки доходит до span). + Проверка: `make service_test`. +- [ ] 8.3 Контракт repo (2.2) на фейке и на SQL — одни условия. Проверка: `make service_test` и `make service_test_db`. +- [ ] 8.4 `service-tests/db/`: настоящий engine с пулом 1 и коротким сроком ожидания — второй блок ждёт (`pending()` 1), + отказ по сроку увеличивает `timeouts()`; после `engine.dispose()` пул того же класса. Проверка: `make service_test_db`. + +## 9. Драйвер скилла `run-mtusi-messenger` + +- [ ] 9.1 Команда `driver.py --port trace-chain` (16, спек «Цепочка и сигналы уровня 4 находятся»): пять частей решения + 16, таблица «шаг → ожидаемо → получено», коды 0 / 1 / 2, в `finally` — `unpause s3`, `start worker relay`; секреты и токены + не печатаются; только stdlib и синтаксис 3.9. Проверка: `python3 -m py_compile` системным `python3`; `--help` называет + команду; пробный прогон после 10.3 — код 0 (вывод в scratchpad). +- [ ] 9.2 `telemetry-check` (16): шаги задания — по consumer span трассы загрузки, шаг «трасса задания — трасса загрузки», + relay в пробе сетей; ресурс span producer — `messenger-relay` и `service.instance.id` = `instance_id` журнала relay, + корней-span relay нет; запись relay о проходе в Loki совпадает со stdout и не содержит `trace_id`. Проверка: пробный прогон + после 10.3 — код 0. +- [ ] 9.3 `telemetry-outage` (16): остановки relay при остановленном и замороженном Collector (< 10 с, код 0, «Stopped + relay»), relay в рестарте при остановленных сервисах телеметрии, сигналы relay снова приходят. Проверка: пробный прогон + после 10.3 — код 0. +- [ ] 9.4 `SKILL.md` — `trace-chain` и изменения двух команд. Проверка: `grep -n trace-chain` по `SKILL.md`. + +## 10. Стенд и регрессия (до коммита) + +- [ ] 10.1 `make lint`, `make service_test`, `make service_test_db`. Проверка: зелёные; причины падений — в отчёте apply до + правок. +- [ ] 10.2 Сборка и проверка образа: `docker compose build api`; `docker compose config --quiet` (рабочий, CI, `bench/`, + отказы). Проверка: коды 0. +- [ ] 10.3 Развёртывание без простоя (Migration Plan): `make rolling_update` — ревизия один раз; `docker compose up -d + --no-deps relay worker cleaner`; `docker compose restart grafana`. Проверка: «Started relay» — `telemetry_enabled: true`; + `alembic_version` — новая ревизия; у уборщика в `/proc/1/maps` и списке модулей нет SDK (проба в контейнере); `make lb_stats` + — обе реплики `UP`. +- [ ] 10.4 Имена в Prometheus: каждый ряд таблицы решения 13 есть с ожидаемыми метками у ожидаемых `job`; расхождение + экспортёра Collector — правка запросов панелей и таблицы, запись в «Уточнения apply». Проверка: запросы через API Grafana. +- [ ] 10.5 Регрессия на стенде: `make test`; `make student_test` через LB (красный только `test_exclusion_evidence_exists`); + `make test_isolated` и `make failure_checks` — прежние результаты, «Started relay» их relay — телеметрия выключена; `make + test-persistence ACTION_SCRIPT=scripts/restart.sh`; `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` с `STOP_MODE` + `stop` и `kill`. Проверка: выводы команд; причины падений — до правок. +- [ ] 10.6 Пробные прогоны `trace-chain`, `telemetry-check`, `telemetry-outage` на рабочем дереве (scratchpad). Проверка: + коды 0; если Tempo делит трассу повтора — решение 2 пересматривается (Risks), запись в «Уточнения apply». +- [ ] 10.7 Бюджет (15): `memory.peak` и CPU relay и уборщика (и сервисов телеметрии — проверка, что пики прежние) под `make + test` + `make load` + `make student_test` + `trace-chain`; лимит relay — не меньше 1,5 × пика, иначе поднять и пересчитать + суммы `docker.md` и `REPORT.md`. Проверка: числа в scratchpad для 12.4; `docker inspect` совпадает с суммами. + +## 11. Документы + +- [ ] 11.1 Правила (17): `telemetry.md`, `worker.md`, `infra.md`, `logging.md`, `settings.md`, `docker.md`, `dto.md`, + `repo-layer.md`, `migrations.md`, `bench.md`, `student-tests.md`, `run-modes.md`. Проверка: в каждом — ссылка на design + change `job-trace-propagation` и нет пересказа спека; `telemetry.md` больше не говорит «только API и worker» и «sampler + `ALWAYS_ON`». +- [ ] 11.2 `config_example.toml` (секция `[telemetry]` — и relay), `.env.example` (`messenger-relay` в соответствии + `OTEL_SERVICE_NAME`). Проверка: `git diff` без значений секретов. +- [ ] 11.3 `AGENTS.md`: состояние лабы (второй change), таблица важных файлов, карта кода (`src/infra/telemetry/`, `relay`, + `worker`, `engine.py`, миграция, `evidence/telemetry/`), команда `trace-chain`. Проверка: `grep` новых путей и команды. +- [ ] 11.4 `REPORT.md`, раздел «Наблюдаемость», по требованию «Наблюдаемость в отчёте»: сквозная трасса (carrier и + отображение заголовков на поля `jobs.schema.json`, parent и link и почему, без контекста и смесь версий), таблица и запросы + сигналов уровня 4 с единицами, источник очереди, отказ от `docker.sock`, ресурс `messenger-relay`, бюджет, ограничения + (решения 9–12, Risks); строки «Доказательства критериев» уровня 4. Проверка: сценарий «Отчёт по наблюдаемости». +- [ ] 11.5 `QUESTIONS.md`, раздел `## job-trace-propagation` (создан на propose) — дополнить решениями и вопросами apply; + design — «Уточнения apply» с отклонениями от решений. Проверка: каждое отклонение названо там. + +## 12. Evidence (после коммита кода основной сессией) + +- [ ] 12.1 `driver.py --port 8080 trace-chain` → код 0, `evidence/telemetry/trace-chain.md` с commit в шапке. Проверка: + сценарии `observability` «Цепочка одной загрузки», «Повторная попытка в той же трассе», «Replay в той же трассе», + «Задание без контекста», «Очередь при остановленном worker», «Один источник очереди», «Время до готовности в метрике», + «Пулы процессов стенда», «Пределы как в compose», «Без сокета Docker», «Панели уровня 4 после трафика», «Проверка + цепочки»; `service-logging` «Записи задания ведут к трассе». +- [ ] 12.2 `driver.py --port 8080 telemetry-check` → `evidence/telemetry/check.md`; `driver.py --port 8080 telemetry-outage` + → `evidence/telemetry/collector-outage.md`. Проверка: коды 0; сценарии «Ресурс relay», «Collector недоступен для relay», + `service-logging` «Записи relay в Loki» и «Проход relay без полей трассы», `graceful-shutdown` «docker stop при + остановленном Collector» и «…при замороженном Collector». +- [ ] 12.3 Миграция — `evidence/migrations/job-trace-context.md` (с нуля, повтор, откат, `--sql` с `lock_timeout`, `make + rolling_update` с ревизией до и после); план снимка очереди — `EXPLAIN (ANALYZE, BUFFERS)` на рабочей базе → + `evidence/telemetry/queue-snapshot.md`. Проверка: в плане нет Seq Scan по `attachment_jobs`. +- [ ] 12.4 Бюджет — раздел change в `evidence/telemetry/budget.md` (relay с SDK, уборщик после ленивого импорта). Проверка: + лимиты ≥ 1,5 × пика, суммы `docker.md` и `REPORT.md` совпадают. +- [ ] 12.5 Ссылки `REPORT.md` и `AGENTS.md` на новые файлы evidence и их commit; `graphify update .`. Проверка: файлы, + названные в `REPORT.md`, существуют; в графе есть новые модули пакета телеметрии.