From 5f562dc646b3ea3eb863c9acad255e020c243d24 Mon Sep 17 00:00:00 2001 From: roman Date: Wed, 11 Nov 2026 21:04:40 +0300 Subject: [PATCH] docs: archive job-trace-propagation and sync its specs Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 10 +- QUESTIONS.md | 2 +- REPORT.md | 2 +- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/graceful-shutdown/spec.md | 0 .../specs/observability/spec.md | 0 .../specs/service-configuration/spec.md | 0 .../specs/service-logging/spec.md | 0 .../tasks.md | 0 openspec/specs/graceful-shutdown/spec.md | 23 +- openspec/specs/observability/spec.md | 289 +++++++++++++++++- openspec/specs/service-configuration/spec.md | 18 +- openspec/specs/service-logging/spec.md | 41 ++- 15 files changed, 334 insertions(+), 51 deletions(-) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/.openspec.yaml (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/design.md (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/proposal.md (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/specs/graceful-shutdown/spec.md (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/specs/observability/spec.md (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/specs/service-configuration/spec.md (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/specs/service-logging/spec.md (100%) rename openspec/changes/{job-trace-propagation => archive/2026-11-11-job-trace-propagation}/tasks.md (100%) diff --git a/AGENTS.md b/AGENTS.md index 5a2de73..2682b84 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` — diff --git a/QUESTIONS.md b/QUESTIONS.md index b173563..5e3900e 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -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. ### Решения diff --git a/REPORT.md b/REPORT.md index a50fdb5..8018617 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 <очередь>` diff --git a/openspec/changes/job-trace-propagation/.openspec.yaml b/openspec/changes/archive/2026-11-11-job-trace-propagation/.openspec.yaml similarity index 100% rename from openspec/changes/job-trace-propagation/.openspec.yaml rename to openspec/changes/archive/2026-11-11-job-trace-propagation/.openspec.yaml diff --git a/openspec/changes/job-trace-propagation/design.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/design.md similarity index 100% rename from openspec/changes/job-trace-propagation/design.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/design.md diff --git a/openspec/changes/job-trace-propagation/proposal.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/proposal.md similarity index 100% rename from openspec/changes/job-trace-propagation/proposal.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/proposal.md diff --git a/openspec/changes/job-trace-propagation/specs/graceful-shutdown/spec.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/specs/graceful-shutdown/spec.md similarity index 100% rename from openspec/changes/job-trace-propagation/specs/graceful-shutdown/spec.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/specs/graceful-shutdown/spec.md diff --git a/openspec/changes/job-trace-propagation/specs/observability/spec.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/specs/observability/spec.md similarity index 100% rename from openspec/changes/job-trace-propagation/specs/observability/spec.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/specs/observability/spec.md diff --git a/openspec/changes/job-trace-propagation/specs/service-configuration/spec.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/specs/service-configuration/spec.md similarity index 100% rename from openspec/changes/job-trace-propagation/specs/service-configuration/spec.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/specs/service-configuration/spec.md diff --git a/openspec/changes/job-trace-propagation/specs/service-logging/spec.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/specs/service-logging/spec.md similarity index 100% rename from openspec/changes/job-trace-propagation/specs/service-logging/spec.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/specs/service-logging/spec.md diff --git a/openspec/changes/job-trace-propagation/tasks.md b/openspec/changes/archive/2026-11-11-job-trace-propagation/tasks.md similarity index 100% rename from openspec/changes/job-trace-propagation/tasks.md rename to openspec/changes/archive/2026-11-11-job-trace-propagation/tasks.md diff --git a/openspec/specs/graceful-shutdown/spec.md b/openspec/specs/graceful-shutdown/spec.md index 931e7d8..72c2b61 100644 --- a/openspec/specs/graceful-shutdown/spec.md +++ b/openspec/specs/graceful-shutdown/spec.md @@ -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 diff --git a/openspec/specs/observability/spec.md b/openspec/specs/observability/spec.md index 67f56ca..41ca833 100644 --- a/openspec/specs/observability/spec.md +++ b/openspec/specs/observability/spec.md @@ -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 с совпавшими значениями diff --git a/openspec/specs/service-configuration/spec.md b/openspec/specs/service-configuration/spec.md index 25fda65..f56bbbb 100644 --- a/openspec/specs/service-configuration/spec.md +++ b/openspec/specs/service-configuration/spec.md @@ -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`, с отрицательным интервалом отправки метрик или с diff --git a/openspec/specs/service-logging/spec.md b/openspec/specs/service-logging/spec.md index 7b3397d..7f2f6c1 100644 --- a/openspec/specs/service-logging/spec.md +++ b/openspec/specs/service-logging/spec.md @@ -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** обработка запроса падает с непредвиденным исключением