@@ -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 с совпавшими значениями