docs: archive job-trace-propagation and sync its specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 21:04:40 +03:00
co-authored by Claude Opus 5.5
parent c1055b4d6c
commit 5f562dc646
15 changed files with 334 additions and 51 deletions
+6 -4
View File
@@ -21,8 +21,10 @@ contrib, Prometheus, Loki, Tempo и Grafana в compose (`infra/otel/`, сеть
уровня 3, healthcheck брокера от его пользователя (стенд с нуля одной
командой), команды драйвера `telemetry-check`, `telemetry-outage`,
`stand-from-scratch` (правило `telemetry.md`). Второе изменение лабы, первая
часть уровня 4 — change `job-trace-propagation` (активный,
`openspec/changes/job-trace-propagation/`, capability `observability`):
часть уровня 4 — change `job-trace-propagation` (заархивирован 2026-11-11,
`openspec/changes/archive/2026-11-11-job-trace-propagation/`, capability
`observability`, изменены ещё `graceful-shutdown`, `service-configuration`,
`service-logging`):
контекст W3C загрузки в `attachment_jobs.traceparent` / `tracestate`
(ревизия `e4b8c2d17f90`), SDK в relay (`messenger-relay`), span producer
relay и consumer span worker (parent и link) — одна трасса на загрузку, с
@@ -122,8 +124,8 @@ max_objects_per_second` (2000 объектов S3/с), отказ по пред
`upload-consistency`, `upload-memory`, `track2-reconciler`,
`fix-upload-put-flake`, `track2-reconcile-cost` лабы 4, `async-attachments`,
`pipeline-reliability`, `unit-of-work` и `track1-queue-overload` лабы 5 и
`otel-telemetry` лабы 6 — в `openspec/changes/archive/`, активный —
`job-trace-propagation` (новые
`otel-telemetry` и `job-trace-propagation` лабы 6 — в
`openspec/changes/archive/`, активных нет (новые
capability: с `s3-storage` —
`object-storage`, с `attachments` — `attachments`, с
`upload-consistency` — `storage-consistency`, с `async-attachments` —
+1 -1
View File
@@ -199,7 +199,7 @@ Change `openspec/changes/archive/2026-11-11-otel-telemetry/` (propose и арх
## job-trace-propagation
Change `openspec/changes/job-trace-propagation/` (propose 2026-11-11). Номера — решения design.
Change `openspec/changes/archive/2026-11-11-job-trace-propagation/` (propose и архив 2026-11-11). Номера — решения design.
### Решения
+1 -1
View File
@@ -140,7 +140,7 @@ Tempo 253, Grafana 248 МиБ, правило выполнено и для на
### Сквозная трасса загрузки (уровень 4)
Change `job-trace-propagation` (design — `openspec/changes/job-trace-propagation/design.md`,
Change `job-trace-propagation` (design — `openspec/changes/archive/2026-11-11-job-trace-propagation/design.md`,
номера решений «JTP-n»). Одна загрузка — одна трасса: server span `POST
/api/v1/chats/{chat_id}/attachments` (`messenger-api`) → на каждую публикацию её задания span
`PRODUCER` `publish <очередь>` (`messenger-relay`) → под ним span `CONSUMER` `process <очередь>`
+12 -11
View File
@@ -306,28 +306,29 @@ least once»), а его процесс обработки SHALL быть уби
### Requirement: Остановка при недоступном Collector
С включённой телеметрией (capability `observability`) реплика API и worker SHALL останавливаться по SIGTERM в прежние сроки:
API — требования «Завершение за заявленный срок» и «Остановка видна в журнале», worker — «Остановка worker», в том числе
когда Collector остановлен или заморожен. Отправка накопленной телеметрии при остановке SHALL ограничиваться своим сроком
внутри этого бюджета; что не ушло за срок, теряется, а процесс MUST NOT ждать Collector дольше. Запись об остановке
процесса SHALL быть в stdout при любом состоянии 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 закрытие SDK SHALL идти внутри окна закрытия клиентов, и худший случай остаётся
прежним (требование «Остановка worker»).
телеметрии допустимы прежние 9 с. У worker и relay закрытие SDK SHALL идти внутри окна закрытия клиентов, и худший случай
остаётся прежним (требования «Остановка worker» и «Остановка relay»).
#### Scenario: docker stop при остановленном Collector
- **WHEN** Collector остановлен, реплика API только что обслуживала запросы, и выполняется `docker stop` этой реплики, а затем
`docker compose stop worker`
- **THEN** обе команды завершаются быстрее 10 с, коды выхода контейнеров 0, а в stdout есть «Stopped API» и «Stopped worker»
- **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 есть записи об остановке
- **THEN** все три команды завершаются быстрее 10 с, коды выхода 0, а в stdout есть записи об остановке
#### Scenario: Срок остановки API не оставляет места закрытию SDK
+274 -15
View File
@@ -109,8 +109,8 @@ Grafana SHALL быть доступна только на `127.0.0.1` хоста
- `service.instance.id` — то же значение, что `instance_id` журнала процесса и `X-Instance-Id` его ответов;
- `deployment.environment.name` — из настроек, по умолчанию `lab` (`service-configuration`, «Параметры телеметрии»).
Relay, уборщик, сервис миграций и процесс обработки изображения SDK MUST NOT запускать: их журнал — stdout контейнера, а
работа процесса обработки видна span в трассе worker.
Уборщик, сервис миграций, команда replay и процесс обработки изображения SDK MUST NOT запускать: их журнал — stdout
контейнера, а работа процесса обработки видна span в трассе worker. Relay запускает SDK по требованию «SDK в relay».
Телеметрия MUST NOT влиять на ответы API и обработку заданий: отправка идёт в фоне, очереди SDK ограничены, недоступный или
зависший Collector MUST NOT задерживать запросы и задания и приводить к ошибкам, и SDK SHALL продолжать отправку, когда
@@ -118,7 +118,8 @@ Collector вернулся, без перезапуска процесса. Те
отказе отправки SHALL идти только в stdout и не чаще одной записи в минуту от каждого модуля SDK.
API MUST NOT продолжать трассу клиента: входящие `traceparent` и `tracestate` игнорируются, каждый запрос начинает свою
трассу (публичная точка входа; перенос контекста внутри стенда — уровень 4).
трассу (публичная точка входа). Контекст внутри стенда переносит задание (требование «Сквозная трасса загрузки и
обработки»).
#### Scenario: Ресурс сигналов
@@ -289,11 +290,15 @@ stdout (`service-logging`, «Без содержимого сообщений и
### Requirement: Где телеметрия включена
Телеметрия SHALL быть включена на рабочем стенде compose у реплик API и worker. В консоли (`make run_dev`, `make
run_worker`), во временном прогоне `make test_isolated`, на стенде отказов `make failure_checks` и на стенде `bench/` она
SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние, а профиль, которому нужна телеметрия, включает её
явно. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей журнала, ни обращений к
Collector, ни полей трассы в журнале. Вариант «телеметрия выключена» трека 1 — та же одна настройка.
Телеметрия 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 в памяти процесса. Код
приложения MUST NOT загружать модули SDK трасс и журнала, экспортёра, protobuf и HTTP-клиента экспортёра ни при выключенной
телеметрии, ни в процессах, которые SDK не запускают: уборщик, сервис миграций, команда replay. Модулей SDK метрик в таком
процессе MUST NOT быть больше, чем загружает сама сторонняя библиотека, которую процесс импортирует (redis-py при импорте
проверяет, установлен ли SDK метрик). Вариант «телеметрия выключена» трека 1 — та же одна настройка.
#### Scenario: Консоль без телеметрии
@@ -303,8 +308,15 @@ Collector, ни полей трассы в журнале. Вариант «те
#### Scenario: Тестовые стенды без телеметрии
- **WHEN** выполняются `make test_isolated` и `make failure_checks`
- **THEN** записи о старте их API и worker говорят, что телеметрия выключена, Collector на этих стендах не запускается, а
результаты проверок прежние
- **THEN** записи о старте их API, worker и relay говорят, что телеметрия выключена, Collector на этих стендах не
запускается, а результаты проверок прежние
#### Scenario: Модули SDK без телеметрии не загружаются
- **WHEN** код процессов API, worker, relay и уборщика импортирован при выключенной телеметрии
- **THEN** в процессе нет ни провайдеров и модулей SDK трасс и журнала, ни экспортёра OpenTelemetry, ни protobuf, ни
HTTP-клиента экспортёра, а модулей SDK метрик не больше, чем после одного `import redis.asyncio` в отдельном
интерпретаторе
### Requirement: Наблюдаемость в отчёте
@@ -312,15 +324,262 @@ Collector, ни полей трассы в журнале. Вариант «те
- назначение Collector и каждого хранилища: на какой вопрос об инциденте отвечают метрика, лог и трасса;
- закреплённые версии SDK, semantic conventions, дистрибутива Collector, хранилищ и Grafana;
- таблицу «логический сигнал контракта → инструмент SDK → имя и метки в Prometheus или поля в Loki и Tempo → единица» и
запросы панелей dashboard;
запросы панелей dashboard — для сигналов уровней 3 и 4;
- определение доли ошибок HTTP и успешных и ошибочных заданий;
- перенос контекста: где он хранится, какие заголовки сообщения его несут и как они соответствуют полям `traceparent` и
`tracestate` `contracts/jobs.schema.json`, почему consumer span — дочерний с link, что с заданиями без контекста и со
смесью версий при замене;
- источник глубины и возраста очереди и почему CPU и память берутся из cgroup контейнера, а не через сокет Docker;
- соответствие атрибутов ресурса меткам хранилищ и имён `OTEL_*` skeleton настройкам;
- сумму лимитов стенда с телеметрией против ресурсов ВМ и замер простоя и пика сервисов телеметрии;
- сумму лимитов стенда с телеметрией против ресурсов ВМ и замер простоя и пика сервисов телеметрии и процессов с SDK;
- ограничения: что теряется при отказе Collector, ответы балансировщика вне метрик API, приём OTLP без аутентификации до
лабы 7.
лабы 7, мгновенные значения пула и насыщения раз в интервал отправки, устаревший снимок очереди, контейнеры без SDK вне
метрик, задания после replay вне времени до готовности.
#### Scenario: Отчёт по наблюдаемости
- **WHEN** проверяющий читает `REPORT.md`
- **THEN** для каждого сигнала уровня 3 есть имя, единица и запрос, для каждого хранилища — назначение и версия, а для суммы
лимитов — числа и замер
- **THEN** для каждого сигнала уровней 3 и 4 есть имя, единица и запрос, для каждого хранилища — назначение и версия, для
переноса контекста — отображение заголовков сообщения на поля схемы задания, а для суммы лимитов — числа и замер
### 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 с совпавшими значениями
+12 -6
View File
@@ -645,9 +645,9 @@ worker секцию не используют. Запись о старте rela
### Requirement: Параметры телеметрии
Телеметрию API и worker (capability `observability`) SHALL настраивать секция `[telemetry]`:
- `enabled` — включена ли телеметрия, по умолчанию выключена; рабочий стенд compose включает её в окружении реплик API и
worker;
Телеметрию 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`;
@@ -655,8 +655,8 @@ worker секцию не используют. Запись о старте rela
значениями по умолчанию; положительные числа, пакет не больше очереди.
Неверное значение MUST останавливать запуск с именем поля (требование «Некорректное значение останавливает запуск»).
Разовая подмена SHALL работать через окружение `TELEMETRY__*` без правки файлов. Секции читают только процессы API и
worker; relay, уборщик и миграции её не читают.
Разовая подмена SHALL работать через окружение `TELEMETRY__*` без правки файлов. Секцию применяют только процессы API,
worker и relay; уборщик, миграции и команда replay телеметрию не запускают при любом её значении.
Переменные `OTEL_*` стандарта OpenTelemetry настройками сервиса MUST NOT быть, как любые переменные без секции (требование
«Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни параметры очередей, а процесс с
@@ -664,7 +664,7 @@ worker; relay, уборщик и миграции её не читают.
значений. Имена skeleton (`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`,
`OTEL_RESOURCE_ATTRIBUTES`) сопоставлены настройкам и постоянным значениям кода в `.env.example` и `REPORT.md`.
Запись журнала о старте API и о старте worker SHALL называть, включена ли телеметрия, а при включённой — адрес Collector и
Запись журнала о старте API, worker и relay SHALL называть, включена ли телеметрия, а при включённой — адрес Collector и
окружение.
#### Scenario: Телеметрия по умолчанию выключена
@@ -678,6 +678,12 @@ worker; relay, уборщик и миграции её не читают.
менялись
- **THEN** запись о старте называет этот адрес, а трассы, метрики и логи worker приходят в хранилища
#### Scenario: Телеметрия relay
- **WHEN** relay запущен на рабочем стенде compose, а затем в консоли `make run_relay`
- **THEN** запись о старте relay стенда называет телеметрию включённой, адрес Collector и окружение, а консольного —
выключенной
#### Scenario: Неверный параметр телеметрии
- **WHEN** сервис запускается с `TELEMETRY__OTLP_ENDPOINT=collector:4318`, с отрицательным интервалом отправки метрик или с
+28 -13
View File
@@ -324,11 +324,13 @@ replay — те же поля и оператор, уровень `info`; отк
### Requirement: Связь записей с трассой
При включённой телеметрии (capability `observability`, «Где телеметрия включена») запись журнала API или worker, сделанная
при активном span, SHALL содержать `trace_id` (32 шестнадцатеричных символа) и `span_id` (16 символов) этого span — и в
stdout, и в записи, отправленной в хранилище логов. Это записи обработки запроса, кроме health, в том числе итоговая запись
о запросе, и записи обработки доставки worker. Записи вне span — старт, остановка, health, фоновые циклы — этих полей MUST NOT
содержать. `request_id` остаётся прежним: `trace_id` его не заменяет (`contracts/observability.md`).
При включённой телеметрии (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: Записи запроса ведут к трассе
@@ -340,7 +342,13 @@ stdout, и в записи, отправленной в хранилище ло
- **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: Без телеметрии полей нет
@@ -349,13 +357,14 @@ stdout, и в записи, отправленной в хранилище ло
### Requirement: Журнал в хранилище логов
При включённой телеметрии каждая запись журнала API и worker, которая пишется в stdout между запуском SDK и началом его
закрытия при остановке, SHALL ещё и отправляться в хранилище логов через Collector; записи до запуска SDK (записи uvicorn до lifespan,
остановка до старта, ошибки настроек) и после начала закрытия (запись «Stopped worker») идут только в stdout. Отправленная
запись: тело — `event`, уровень — из `level`, время — `timestamp`, остальные поля записи — атрибутами, ресурс —
`service.name` и остальные атрибуты процесса (capability `observability`, «SDK в API и worker»). Записи stdout при этом MUST
NOT меняться, кроме полей трассы (требование «Связь записей с трассой»). Записи самого SDK OpenTelemetry идут только в stdout.
Отказ отправки MUST NOT задерживать запись и обработку и MUST NOT терять записи stdout.
При включённой телеметрии каждая запись журнала 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`. Требование «Без содержимого сообщений и личных данных» действует на отправленные записи так же,
@@ -367,6 +376,12 @@ NOT меняться, кроме полей трассы (требование
- **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** обработка запроса падает с непредвиденным исключением