docs: propose job-trace-propagation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 17:38:05 +03:00
co-authored by Claude Opus 5.5
parent 6b1ad631e9
commit ff0073e8e3
9 changed files with 1273 additions and 0 deletions
+52
View File
@@ -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).
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-11
@@ -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(<min(created_at) по тем же трём условиям частичных индексов>) 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 <LB> 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`.
@@ -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`.
@@ -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` и
допустимый предел, а с выключенной телеметрией то же значение принимается
@@ -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 есть имя, единица и запрос, для каждого хранилища — назначение и версия, для
переноса контекста — отображение заголовков сообщения на поля схемы задания, а для суммы лимитов — числа и замер
@@ -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` с именами этих
переменных без значений
@@ -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 нет потока записей об отказе отправки
@@ -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 <LB> 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`, существуют; в графе есть новые модули пакета телеметрии.