Files
mtusi2026lab6/openspec/specs/observability/spec.md
T
2026-11-11 21:04:40 +03:00

54 KiB
Raw Blame History

observability Specification

Purpose

Наблюдаемость стенда с лабы 6: SDK OpenTelemetry в API и worker, отдельный OTel Collector, хранилища метрик, логов и трасс с историей, Grafana с provisioning из git, сигналы уровня 3 contracts/observability.md, запреты на содержимое телеметрии и проверка, что свой запрос и своё задание находятся по сохранённым наблюдениям.

Requirements

Requirement: Конвейер телеметрии в стенде

Рабочий стенд compose SHALL включать отдельный OTel Collector и хранилища трёх сигналов: Prometheus — метрики, Loki — логи, Tempo — трассы; интерфейс — Grafana (contracts/infrastructure.json, роли otel_collector, telemetry_storage, grafana). Collector — получатель, обработчик и экспортёр, а не хранилище; Grafana сигналы не хранит, а запрашивает у хранилищ.

  • API и worker SHALL отправлять трассы, метрики и логи только в Collector, по OTLP поверх HTTP (protobuf).
  • Collector SHALL принимать OTLP только из сетей стенда, ограничивать свою память (memory limiter) и отправлять данные пакетами (batch). Каждый сигнал SHALL иметь свой pipeline до развёрнутого хранилища; экспортёр, который только печатает данные, хранилище MUST NOT заменять.
  • Метрики приложения Prometheus SHALL забирать у Collector (scrape); собственные метрики Collector, Loki, Tempo и Prometheus SHALL быть в Prometheus тоже: по ним видно, жив ли конвейер.
  • Хранилища и Grafana SHALL быть в отдельной сети стенда: контейнеры приложения до них не достают, связь — только через Collector.
  • Конфигурации Collector, хранилищ и Grafana SHALL лежать в git и подключаться к контейнерам только на чтение. Образы SHALL быть закреплены тегом с версией и digest индекса.

Scenario: Стенд с телеметрией

  • WHEN выполнен make run_docker
  • THEN Collector, Prometheus, Loki, Tempo и Grafana работают, в Prometheus цели Collector, Loki, Tempo и самого Prometheus — up = 1, а проверка источников в Grafana для Prometheus, Loki и Tempo проходит

Scenario: Хранилища недоступны приложению

  • WHEN из контейнера реплики API или worker выполняется обращение к Prometheus, Loki, Tempo или Grafana по имени сервиса
  • THEN имя не разрешается или соединение не устанавливается, а OTLP-приёмник Collector из этого контейнера доступен

Requirement: Хранилища сигналов сохраняют историю

Prometheus, Loki и Tempo SHALL хранить данные в именованных volumes проекта стенда. Срок хранения SHALL быть задан явно — 7 суток у всех трёх, у Prometheus ещё и предел объёма; данные старше срока хранилища удаляют сами. Перезапуск хранилища, Collector или всего стенда без удаления volumes MUST NOT терять сохранённое. make stop и make down MUST NOT удалять эти volumes; make wipe_data удаляет их вместе с остальными данными стенда и называет в запросе подтверждения. Первый старт на пустых volumes SHALL проходить без ручных действий.

Restart hook scripts/restart.sh сервисы телеметрии MUST NOT перезапускать: он про хранилища бизнес-данных (container-run, «Данные переживают рестарт стенда»), а история телеметрии проверяется отдельно.

Scenario: История после рестарта хранилищ

  • WHEN свой запрос найден в Loki, Tempo и Prometheus, после чего Collector, Prometheus, Loki и Tempo перезапущены (docker compose restart) без удаления volumes
  • THEN после готовности та же запись лога, та же трасса и тот же ряд метрики находятся снова

Scenario: Restart hook не трогает телеметрию

  • WHEN выполняется scripts/restart.sh
  • THEN у контейнеров Collector, Prometheus, Loki, Tempo и Grafana прежнее время старта

Requirement: Grafana из provisioning

Grafana SHALL при каждом старте получать источники данных Prometheus, Loki и Tempo и dashboard из файлов provisioning в git, без ручного импорта и настройки в интерфейсе. Dashboard SHALL быть импортируемым JSON в git, а не снимком экрана; его запросы SHALL ссылаться на имена метрик и меток, которые реально есть в Prometheus. Источники SHALL иметь постоянные идентификаторы, на которые ссылается dashboard. Изменения, сделанные в интерфейсе, MUST NOT переживать перезапуск Grafana: источник правды — git.

Dashboard уровня 3 SHALL показывать:

  • API — запросы в секунду по маршрутам и классам статуса, долю ошибок (требование «Метрики HTTP API»), длительность — квантили из buckets всех реплик;
  • worker — успешные и ошибочные задания в секунду и длительность обработки (требование «Метрики заданий worker»);
  • журналы API и worker и переход к их трассам.

Из записи лога SHALL открываться трасса по trace_id, из span — записи логов этой трассы.

Grafana SHALL быть доступна только на 127.0.0.1 хоста и только по паролю администратора из .env (GRAFANA_ADMIN_PASSWORD, его создаёт make env_setup случайным); анонимного доступа и регистрации MUST NOT быть. При старте Grafana MUST NOT устанавливать и обновлять плагины из сети и отправлять отчёты об использовании: стенд работает без интернета.

Scenario: Provisioning после старта

  • WHEN стенд поднят с нуля, и проверка обращается к HTTP API Grafana с паролем из .env
  • THEN есть три источника с ожидаемыми идентификаторами, проверка каждого проходит, dashboard из git на месте и помечен как provisioned, а каждый запрос его панелей к Prometheus выполняется без ошибки и после трафика возвращает данные

Scenario: Источник правды — git

  • WHEN dashboard изменён через интерфейс или API Grafana, а затем Grafana перезапущена
  • THEN изменение не сохранено или отклонено, и dashboard совпадает с файлом в git

Scenario: Вход в Grafana

  • WHEN к API Grafana обращаются без учётных данных, с неверным паролем и с паролем из .env
  • THEN первые два запроса получают 401, третий — 200, а порт Grafana опубликован только на 127.0.0.1

Scenario: От лога к трассе и обратно

  • WHEN в Grafana открыта запись лога запроса API с trace_id T
  • THEN по ссылке открывается трасса T в Tempo, а из её span — записи логов с trace_id T

Requirement: SDK в API и worker

Процессы API (каждая реплика) и worker SHALL отправлять трассы, метрики и логи через SDK OpenTelemetry. Ресурс всех трёх сигналов SHALL содержать:

  • service.name — messenger-api у реплик API, messenger-worker у worker;
  • service.version — версию контракта API, которую реализует код (info.version в contracts/openapi.json);
  • service.instance.id — то же значение, что instance_id журнала процесса и X-Instance-Id его ответов;
  • deployment.environment.name — из настроек, по умолчанию lab (service-configuration, «Параметры телеметрии»).

Уборщик, сервис миграций, команда replay и процесс обработки изображения SDK MUST NOT запускать: их журнал — stdout контейнера, а работа процесса обработки видна span в трассе worker. Relay запускает SDK по требованию «SDK в relay».

Телеметрия MUST NOT влиять на ответы API и обработку заданий: отправка идёт в фоне, очереди SDK ограничены, недоступный или зависший Collector MUST NOT задерживать запросы и задания и приводить к ошибкам, и SDK SHALL продолжать отправку, когда Collector вернулся, без перезапуска процесса. Телеметрия, которую не удалось отправить, теряется. Записи самого SDK об отказе отправки SHALL идти только в stdout и не чаще одной записи в минуту от каждого модуля SDK.

API MUST NOT продолжать трассу клиента: входящие traceparent и tracestate игнорируются, каждый запрос начинает свою трассу (публичная точка входа). Контекст внутри стенда переносит задание (требование «Сквозная трасса загрузки и обработки»).

Scenario: Ресурс сигналов

  • WHEN клиент получил ответ API с X-Instance-Id I, а worker обработал задание
  • THEN у трассы, записей лога и рядов метрики этого ответа service.name — messenger-api, service.instance.id — I, service.version — версия контракта, deployment.environment.name — lab; у сигналов задания service.name — messenger-worker и service.instance.id — instance_id из журнала worker

Scenario: Collector остановлен

  • WHEN Collector остановлен, выполняется make test и участник загружает файл
  • THEN make test печатает PASS, /health/ready отвечает 200, вложение становится ready, журнал stdout пишется без потерь и без потока записей об отказе отправки, а после запуска Collector новые трассы, логи и метрики API и worker приходят в хранилища без перезапуска процессов

Scenario: Collector заморожен

  • WHEN контейнер Collector заморожен (docker pause), и выполняется make test
  • THEN make test печатает PASS, а после разморозки сигналы приходят снова

Scenario: Чужой traceparent

  • WHEN клиент присылает запрос с traceparent, в котором trace-id X
  • THEN трасса этого запроса в Tempo имеет другой trace-id, у server span нет родителя, и X нет ни в Tempo, ни в Loki

Requirement: Метрики HTTP API

Каждый запрос к API, кроме health, SHALL учитываться в histogram длительности обработки в секундах — http.server.request.duration (в Prometheus — http_server_request_duration_seconds). Атрибуты:

  • метод — http.request.method: один из стандартных методов HTTP, иначе _OTHER;
  • шаблон маршрута — http.route: полный, с префиксом версии (/api/v1/chats/{chat_id}/messages); у запроса без маршрута атрибута нет;
  • код статуса ответа — http.response.status_code; класс статуса в запросах — первая цифра кода.

Счётчик запросов — число наблюдений той же histogram: второй инструмент для того же сигнала MUST NOT заводиться. Границы buckets SHALL покрывать ожидаемые задержки API — от единиц миллисекунд до срока пути загрузки в балансировщике (30 с).

Доля ошибок SHALL быть определена заранее: числитель — ответы 5xx API, знаменатель — все учтённые запросы; 4xx (неверный пароль, чужой чат) в долю ошибок не входят и показываются отдельно. Ответы, которые сгенерировал сам балансировщик, в метрики API не попадают — ограничение в REPORT.md. Так же вне метрик, трасс и журнала API — запрос с методом, который HTTP-парсер сервера отклоняет до приложения (BREW: его нет в списке методов парсера uvicorn): ответ ему даёт парсер — ограничение, KNOWN_ISSUES.md («Нестандартный метод HTTP»).

Scenario: Запросы в метрике

  • WHEN клиент выполняет N запросов GET /api/v1/chats/{id} через балансировщик к двум репликам
  • THEN сумма http_server_request_duration_seconds_count с http_route = /api/v1/chats/{chat_id}, методом GET и кодом 200 по всем instance за это время выросла на N, а в метках нет ни одного UUID

Scenario: Health не учитывается

  • WHEN балансировщик и healthcheck вызывают /health/ready и /health/live
  • THEN рядов с маршрутами health в Prometheus нет

Scenario: Необычный метод и неизвестный путь

  • WHEN клиент шлёт к несуществующему пути с UUID внутри запрос с методом вне стандартного набора, который HTTP-парсер сервера передаёт приложению (PROPFIND), и запрос GET
  • THEN первый учтён в ряду с методом _OTHER, второй — в ряду с методом GET, оба ряда без http_route, а ни метода PROPFIND, ни этого UUID в метках нет

Requirement: Метрики заданий worker

Каждая доставка, которую worker начал обрабатывать (после места конкуренции), SHALL учитываться в histogram длительности обработки в секундах — messenger.job.duration (в Prometheus — messenger_job_duration_seconds). Атрибуты: тип задания messenger.job.type — значение type схемы сообщения (attachment.process.v1) и исход messenger.job.outcome:

  • ready — вложение стало ready;
  • failed — вложение стало failed: постоянная ошибка или исчерпан бюджет попыток;
  • retry — попытка не удалась, назначена следующая;
  • skipped — сообщение подтверждено без попытки: задание завершено или неизвестно, идёт живая попытка, срок не наступил, задание ведёт другая попытка;
  • requeued — PostgreSQL недоступен, сообщение возвращено в очередь;
  • dropped — сообщение не по схеме;
  • error — непредвиденная ошибка до итога.

Счётчик заданий — число наблюдений той же histogram по исходу. Успешные — ready; ошибочные — failed, retry, requeued, dropped и error; skipped — ни то, ни другое. Границы buckets SHALL покрывать задержки от десятков миллисекунд до срока попытки ([worker] job_timeout_seconds). Атрибутов с id задания, вложения и чата MUST NOT быть.

Scenario: Готовое вложение в метриках

  • WHEN участник загружает файл, и вложение становится ready
  • THEN у messenger_job_duration_seconds_count worker с исходом ready и типом attachment.process.v1 счёт вырос на 1

Scenario: Неудачное вложение в метриках

  • WHEN участник загружает JPEG, который проходит проверку структуры, но не декодируется, и вложение становится failed
  • THEN счёт исхода failed вырос на 1, а счёт ready — нет

Requirement: Трассы API и worker

Каждый запрос к API, кроме health, SHALL давать server span реального выполнения: имя — метод и шаблон маршрута, длительность — время обработки запроса, атрибуты — метод, маршрут, код статуса и id запроса (то же значение, что X-Request-Id). Ответ 5xx и непредвиденное исключение SHALL давать статус ошибки span с классом ошибки.

Каждая доставка, которую worker начал обрабатывать, SHALL давать consumer span с очередью, типом задания и исходом (требование «Метрики заданий worker»).

Дочерними span запроса и задания SHALL быть обращения к PostgreSQL (каждый запрос и фиксация транзакции), Valkey, S3 и процесс обработки изображения — со временем и исходом; отказ — статус ошибки с классом ошибки. Обращения к хранилищам вне обработки запроса или задания (проверка готовности, фоновые циклы) MUST NOT создавать трасс. Трассы — только реальная работа процесса, искусственных и статических нет.

Scenario: Трасса запроса

  • WHEN участник отправляет сообщение через балансировщик и получает 201 с X-Request-Id R
  • THEN в Tempo есть трасса с server span POST /api/v1/chats/{chat_id}/messages, кодом 201 и id запроса R, а под ним — span запросов к PostgreSQL и фиксации транзакции

Scenario: Трасса задания

  • WHEN вложение становится ready
  • THEN в Tempo есть трасса messenger-worker с consumer span исхода ready, а под ним — span PostgreSQL, span S3 (чтение staging, запись оригинала и вариантов) и span процесса обработки

Scenario: Отказ S3 в трассе

  • WHEN контейнер S3 заморожен, и участник загружает файл
  • THEN ответ 503, его server span — со статусом ошибки, а дочерний span S3 — с ошибкой и длительностью около срока вызова S3

Scenario: Health и фоновые циклы без трасс

  • WHEN стенд простаивает, а балансировщик проверяет /health/ready раз в секунду
  • THEN в Tempo нет трасс health и трасс из одного span PostgreSQL

Requirement: Без секретов и содержимого в телеметрии

Метки метрик MUST NOT содержать user_id, chat_id, message_id, attachment_id, request_id, сырой URL и query, filename и текст; значения меток метрик API и worker MUST NOT быть UUID (contracts/observability.md).

Записи логов, атрибуты span и ресурса MUST NOT содержать пароли, токены сессий и их хэши, значения Authorization и Idempotency-Key, тела запросов и ответов, текст сообщений, username, display_name, названия чатов, filename, байты изображений, ключи и секреты S3, подписи запросов, пароли хранилищ и брокера. В span допускается id запроса; текст исключения в span MUST NOT попадать — только класс ошибки, traceback пишет журнал. Записи лога в хранилище — те же, что в stdout (service-logging, «Без содержимого сообщений и личных данных»).

Scenario: Проба приватности

  • WHEN проверка регистрирует пользователя с уникальными username U и паролем P, входит и получает токен T, отправляет сообщение с текстом M и ключом K, загружает файл с именем F, а затем просматривает все записи Loki, трассы Tempo и метки Prometheus за это время
  • THEN ни U, P, T, M, K и F, ни строк Bearer и Basic в них нет, а у метрик API и worker нет меток с запрещёнными именами и значений UUID

Requirement: Свой запрос и своё задание находятся

Проверка стенда (команда драйвера скилла run-mtusi-messenger) SHALL находить только по сохранённым наблюдениям:

  • запрос с X-Request-Id R — запись лога API с request_id R в Loki, её trace_id, трассу в Tempo с server span этого запроса и service.instance.id, равным X-Instance-Id ответа;
  • загрузку — запись лога worker с id вложения в Loki, её trace_id и трассу обработки задания в Tempo;
  • рост метрик API и worker в Prometheus за время проверки.

Проверка SHALL идти через источники Grafana (provisioning проверяется заодно), печатать таблицу «шаг → ожидаемо → получено», завершаться ненулевым кодом при расхождении и MUST NOT печатать секреты. Её вывод SHALL быть сохранён в evidence/telemetry/.

Scenario: Запрос найден

  • WHEN проверка отправляет запрос через балансировщик и получает X-Request-Id R и X-Instance-Id I
  • THEN она находит в Loki запись с request_id R и trace_id T, а в Tempo — трассу T с server span этого запроса и service.instance.id I

Scenario: Задание найдено

  • WHEN проверка загружает файл с id вложения A и дожидается ready
  • THEN она находит в Loki запись worker с attachment_id A и trace_id T, а в Tempo — трассу T с consumer span исхода ready

Requirement: Где телеметрия включена

Телеметрия SHALL быть включена на рабочем стенде compose у реплик API, worker и relay. В консоли (make run_dev, make run_worker, make run_relay), во временном прогоне make test_isolated, на стенде отказов make failure_checks и на стенде bench/ она SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние, а профиль, которому нужна телеметрия, включает её явно. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей журнала, ни обращений к Collector, ни полей трассы в журнале, ни провайдеров и экспортёра SDK в памяти процесса. Код приложения MUST NOT загружать модули SDK трасс и журнала, экспортёра, protobuf и HTTP-клиента экспортёра ни при выключенной телеметрии, ни в процессах, которые SDK не запускают: уборщик, сервис миграций, команда replay. Модулей SDK метрик в таком процессе MUST NOT быть больше, чем загружает сама сторонняя библиотека, которую процесс импортирует (redis-py при импорте проверяет, установлен ли SDK метрик). Вариант «телеметрия выключена» трека 1 — та же одна настройка.

Scenario: Консоль без телеметрии

  • WHEN сервис запущен make run_dev без настроек телеметрии
  • THEN запись о старте говорит, что телеметрия выключена, попыток отправки нет, а в записях журнала нет trace_id

Scenario: Тестовые стенды без телеметрии

  • WHEN выполняются make test_isolated и make failure_checks
  • THEN записи о старте их API, worker и relay говорят, что телеметрия выключена, Collector на этих стендах не запускается, а результаты проверок прежние

Scenario: Модули SDK без телеметрии не загружаются

  • WHEN код процессов API, worker, relay и уборщика импортирован при выключенной телеметрии
  • THEN в процессе нет ни провайдеров и модулей SDK трасс и журнала, ни экспортёра OpenTelemetry, ни protobuf, ни HTTP-клиента экспортёра, а модулей SDK метрик не больше, чем после одного import redis.asyncio в отдельном интерпретаторе

Requirement: Наблюдаемость в отчёте

REPORT.md SHALL описывать:

  • назначение Collector и каждого хранилища: на какой вопрос об инциденте отвечают метрика, лог и трасса;
  • закреплённые версии SDK, semantic conventions, дистрибутива Collector, хранилищ и Grafana;
  • таблицу «логический сигнал контракта → инструмент SDK → имя и метки в Prometheus или поля в Loki и Tempo → единица» и запросы панелей dashboard — для сигналов уровней 3 и 4;
  • определение доли ошибок HTTP и успешных и ошибочных заданий;
  • перенос контекста: где он хранится, какие заголовки сообщения его несут и как они соответствуют полям traceparent и tracestate contracts/jobs.schema.json, почему consumer span — дочерний с link, что с заданиями без контекста и со смесью версий при замене;
  • источник глубины и возраста очереди и почему CPU и память берутся из cgroup контейнера, а не через сокет Docker;
  • соответствие атрибутов ресурса меткам хранилищ и имён OTEL_* skeleton настройкам;
  • сумму лимитов стенда с телеметрией против ресурсов ВМ и замер простоя и пика сервисов телеметрии и процессов с SDK;
  • ограничения: что теряется при отказе Collector, ответы балансировщика вне метрик API, приём OTLP без аутентификации до лабы 7, мгновенные значения пула и насыщения раз в интервал отправки, устаревший снимок очереди, контейнеры без SDK вне метрик, задания после replay вне времени до готовности.

Scenario: Отчёт по наблюдаемости

  • WHEN проверяющий читает REPORT.md
  • THEN для каждого сигнала уровней 3 и 4 есть имя, единица и запрос, для каждого хранилища — назначение и версия, для переноса контекста — отображение заголовков сообщения на поля схемы задания, а для суммы лимитов — числа и замер

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