54 KiB
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_idT - THEN по ссылке открывается трасса T в Tempo, а из её span — записи логов с
trace_idT
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-IdI, а 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_countworker с исходом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-IdR - 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 проверка регистрирует пользователя с уникальными
usernameU и паролем 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-IdR — запись лога API сrequest_idR в 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-IdR иX-Instance-IdI - THEN она находит в Loki запись с
request_idR иtrace_idT, а в Tempo — трассу T с server span этого запроса иservice.instance.idI
Scenario: Задание найдено
- WHEN проверка загружает файл с
idвложения A и дожидаетсяready - THEN она находит в Loki запись worker с
attachment_idA иtrace_idT, а в 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иtracestatecontracts/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-IdR, и вложение становитсяready - THEN трасса T записи API с
request_idR содержит server span загрузкиmessenger-api, под ним — span producermessenger-relayс номером попытки 1, под ним — consumer spanmessenger-workerисходаreadyс link на этот span producer, а под consumer span — span PostgreSQL, чтения staging и записи оригинала и трёх вариантов в S3, процесса обработки и фиксации - AND записи worker этого вложения содержат
trace_idT
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_countworker вырос на 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 с совпавшими значениями