Files
mtusi2026lab6/openspec/specs/observability/spec.md
T
2026-11-15 06:17:06 +03:00

96 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 не попадают: их учитывают метрики балансировщика (требование «Ответы балансировщика в метриках»), а долю 5xx, которую видит клиент, — SLI доступности (требование «SLI и SLO»); в длительность и SLI задержки они не входят — ограничение в 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 быть выключена по умолчанию: методика и бюджеты этих стендов прежние. На стенде bench/ её включают только вариант профиля цены телеметрии и выключатель профилей загрузок и очереди (load-benchmark, «Профиль цены телеметрии», «Выключатель телеметрии стенда»): у реплик, worker и relay — с настройками варианта, а Collector и хранилища работают на том же стенде. Выключенная телеметрия 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 в отдельном интерпретаторе

Scenario: Стенд bench по выключателю

  • WHEN быстрый профиль очереди запущен без выключателя телеметрии, а затем с TELEMETRY=on
  • THEN в первом прогоне записи о старте реплик, worker и relay говорят, что телеметрия выключена, и Collector на стенде не запущен; во втором — телеметрия включена с адресом Collector этого стенда, а трассы, записи журнала и метрики реплик, worker и relay приходят в его хранилища

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

Requirement: Ответы балансировщика в метриках

Метрики балансировщика (LB) SHALL попадать в Prometheus вместе с метриками приложения: их забирает Collector с внутреннего порта статистики LB (load-balancing, «Статистика балансировщика внутри сети»), а Prometheus — у Collector. Prometheus и хранилища MUST NOT обращаться к LB напрямую, а LB MUST NOT входить в сеть хранилищ (требование «Конвейер телеметрии в стенде»). Ряды SHALL нести job = haproxy и instance — адрес порта статистики LB; сбор — не реже раза в 15 с.

SHALL быть по меньшей мере:

  • ответы публичного frontend LB клиентам по классу статуса — в том числе ответы, которые сгенерировал сам LB (502, 503, 504), — и запросы к нему;
  • ответы backend реплик по классу статуса;
  • число реплик, готовых по проверке LB.

Только уровни frontend и backend, без рядов по слотам реплик: метки MUST NOT содержать адресов реплик и id. Если LB недоступен, ряд up его цели SHALL быть 0, а его метрики пропадают.

Scenario: Ответы самого балансировщика

  • WHEN PostgreSQL остановлен, реплики не проходят проверку готовности, и клиент шлёт через LB N запросов, на которые получает 503 от LB (формат ошибки контракта, без X-Instance-Id)
  • THEN счёт ответов 5xx публичного frontend вырос не меньше чем на N, число готовых реплик — 0, а в метриках API этих запросов нет

Scenario: Метрики балансировщика без доступа к сети хранилищ

  • WHEN стенд работает, и проверяющий смотрит docker compose config и цели сбора Prometheus
  • THEN LB только в сети приложения, у Prometheus нет цели LB, порт статистики LB на хосте не опубликован, а ряды haproxy_* с job="haproxy" и up{job="haproxy"} = 1 в Prometheus есть

Requirement: SLI и SLO

Стенд SHALL иметь три SLI, определённых заранее, и SLO на скользящем окне 7 суток (срок хранения Prometheus):

SLI Хорошее событие Все события SLO
доступность ответ клиенту не 5xx ответы публичного frontend LB 99,5 %
задержка запрос «лёгкой» ручки API с ответом не 5xx обработан не дольше 0,25 с запросы «лёгких» ручек с ответом не 5xx 99 %
время до ready вложение стало ready не позже 30 с от устойчивого приёма вложения, ставшие ready без replay 99 %
  • Доступность считается там, где её видит клиент, — на LB: в неё входят ответы 5xx API и ответы, которые сгенерировал сам LB; 4xx — ошибки клиента, а не плохие события. Health через LB — тоже ответы клиенту.
  • «Лёгкие» ручки — все пути API, кроме тех, чья длительность задана работой, а не сервисом: регистрация и вход (KDF пароля), загрузка и скачивание байтов вложения. Health метрики API не учитывают (требование «Метрики HTTP API»).
  • Время до ready — histogram требования «Время до готовности»; застрявшие и failed вложения в этот SLI не входят, их видят оповещения об очереди и метрики заданий.

Правила записи (recording rules) в файле правил Prometheus в git SHALL считать приращения хороших, плохих и всех событий каждого SLI за 5 минут; SLI окна — отношение их сумм за окно, соблюдение — SLI не ниже SLO, остаток бюджета — (SLI − SLO) / (1 − SLO). То же SLI SHALL считаться за любое окно и прямо по исходным счётчикам; формулы PromQL, значения и ограничения — в REPORT.md.

Scenario: SLO считается

  • WHEN стенд работает с трафиком не меньше 15 минут, и проверка читает SLI через источник Prometheus в Grafana
  • THEN каждое из трёх SLI за 7 суток — число от 0 до 1 по рядам правил записи, за последний час SLI по рядам правил отличается от SLI по исходным счётчикам в тех же 5-минутных окнах (сумма их increase(…[5m]) на время каждой точки правил) не больше чем на 1 процентный пункт, у доступности и задержки — и от increase исходных счётчиков одним окном того же интервала, а dashboard показывает SLI, SLO и остаток бюджета

Scenario: Отказ БД виден в SLI доступности

  • WHEN под клиентской нагрузкой PostgreSQL остановлен на несколько минут
  • THEN SLI доступности за окно отказа падает на долю 5xx, которую получил клиент, хотя метрики API за время отказа почти не учли запросов

Scenario: Тяжёлая ручка вне SLI задержки

  • WHEN участники параллельно входят по Basic (KDF пароля), и вход медленнее 0,25 с
  • THEN SLI задержки этих запросов не учитывает, а длительность входа видна на панели квантилей по маршрутам

Requirement: Правила оповещений

Правила оповещений SHALL лежать в git в файле правил Prometheus рядом с правилами записи, подключаться к Prometheus только на чтение и вычисляться Prometheus. Доставки наружу (почта, мессенджер, Alertmanager) MUST NOT быть: состояние firing и resolved — локальное: API правил и оповещений Prometheus, ряды ALERTS с историей за срок хранения и Grafana — правила источника Prometheus только для чтения и панель истории состояний.

У каждого оповещения SHALL быть условие PromQL, окно, порог, for, если нужен, важность (severity), краткое и полное описание с текущим значением и ссылка на локальный runbook — файл infra/otel/runbooks/<имя оповещения>.md в git: что значит оповещение и на что влияет, шаги диагностики только по сохранённым наблюдениям (панели, запросы к Prometheus, Loki и Tempo), действия и как убедиться в восстановлении. Набор — не меньше:

Оповещение Условие Окно Порог for
MessengerHighErrorRate доля 5xx ответов клиентам на LB при трафике больше 0,1 запроса в секунду 2 мин 5 % 1 мин
MessengerSlowRequests доля «лёгких» запросов дольше 0,25 с при трафике больше 0,1 запроса в секунду 2 мин 10 % 1 мин
MessengerNoReadyReplicas реплик, готовых по проверке LB, нет — меньше 1 30 с
MessengerQueueLagHigh возраст старейшего незавершённого задания (растущий queue lag) — 60 с 1 мин
MessengerQueueMetricsMissing снимка очереди relay нет, а экспортёр Collector доступен — — 2 мин
TelemetryTargetDown цель сбора метрик Collector, Loki, Tempo или LB недоступна — up = 0 1 мин
TelemetryDataLoss учтённые потери телеметрии выросли (требование «Учёт потерь телеметрии») 2 мин больше 0 —

Модульные тесты правил SHALL лежать в git рядом с правилами и проходить одной командой make alerts_test без стенда и без сети: каждое оповещение срабатывает на синтетических рядах после for, не срабатывает ниже порога и без трафика и снимается после восстановления; правила записи дают ожидаемые значения.

Scenario: Правила загружены

  • WHEN стенд поднят, и проверка читает правила Prometheus через Grafana
  • THEN все оповещения и группы правил записи из git загружены без ошибок вычисления, в Grafana видны правила источника Prometheus, а в конфигурации Prometheus нет адресов доставки оповещений

Scenario: Runbook и описание у каждого оповещения

  • WHEN проверяющий читает файл правил
  • THEN у каждого оповещения есть условие, severity, краткое и полное описание и runbook_url, а каждый названный runbook есть в git

Scenario: Тесты правил

  • WHEN выполняется make alerts_test
  • THEN проверка синтаксиса и модульные тесты правил проходят с кодом 0

Requirement: Проверка оповещений отказами

Проверка стенда (команда драйвера скилла run-mtusi-messenger) SHALL на рабочем стенде под своей постоянной клиентской нагрузкой через LB вносить отказы и по API Prometheus через Grafana проверять, что оповещения переходят в firing, после восстановления снимаются (resolved), а лишних firing нет:

  • worker остановлен, участник загрузил файлы — MessengerQueueLagHigh; worker запущен — снято, все вложения ready;
  • relay остановлен — MessengerQueueMetricsMissing; запущен — снято;
  • БД медленная: запись сообщений ждёт блокировку таблицы в PostgreSQL — MessengerSlowRequests; блокировка снята — снято;
  • медленный handler для сравнения: параллельные входы с KDF пароля — MessengerSlowRequests не срабатывает;
  • БД недоступна: PostgreSQL остановлен — MessengerHighErrorRate и MessengerNoReadyReplicas; запущен — сняты.

На каждом шаге проверка SHALL сохранять наблюдения, по которым разбирается инцидент: моменты отказа, pending, firing, восстановления и снятия; глубину и возраст очереди; квантили по маршрутам; доли окон оповещений; долю времени span PostgreSQL в медленных трассах; занятость пула; CPU реплик; ответы LB и API по классам; записи журнала с причиной. Она SHALL печатать таблицу «шаг → ожидаемо → получено», завершаться ненулевым кодом при расхождении, MUST NOT печатать секреты и SHALL возвращать стенд при любом исходе: worker, relay и PostgreSQL запущены, блокировка снята, нагрузка остановлена. Её вывод SHALL быть сохранён в evidence/alerts/.

Scenario: Остановленный worker

  • WHEN worker остановлен, и участник загружает файлы
  • THEN MessengerQueueLagHigh в firing не позже чем через 4 минуты после первой загрузки, глубина стадий outbox и published выросла на число загрузок, а после запуска worker оповещение снято не позже чем через 2 минуты, и все вложения ready

Scenario: Остановленный relay

  • WHEN relay остановлен
  • THEN MessengerQueueMetricsMissing в firing не позже чем через 5 минут, а после запуска relay оповещение снято не позже чем через 2 минуты

Scenario: Медленная БД

  • WHEN под нагрузкой запись сообщений ждёт блокировку таблицы в PostgreSQL
  • THEN MessengerSlowRequests в firing не позже чем через 4 минуты, в медленных трассах отправки больше половины времени server span занимают span PostgreSQL, занятость пула выше, чем до отказа, CPU реплик ниже половины предела, MessengerHighErrorRate не срабатывает, а после снятия блокировки оповещение снято не позже чем через 4 минуты

Scenario: Медленный handler не путается с БД

  • WHEN участники параллельно входят по Basic, и вход медленнее 0,25 с
  • THEN в трассах входа span PostgreSQL занимают меньше пятой части времени server span, пул ни одной реплики не занят целиком и отказов по сроку ожидания пула нет (pending_requests — наблюдение), а MessengerSlowRequests остаётся неактивным

Scenario: Недоступная БД

  • WHEN под нагрузкой PostgreSQL остановлен
  • THEN MessengerNoReadyReplicas и MessengerHighErrorRate в firing не позже чем через 3 минуты, ответов 5xx на LB больше, чем 5xx в метриках API, а после запуска PostgreSQL оба оповещения сняты не позже чем через 4 минуты

Requirement: Буферизация Collector и отказ хранилищ телеметрии

Collector SHALL отправлять в Loki и Tempo через очередь в памяти с пределом в байтах и повторять неудачную отправку с пределом общего времени; полная очередь SHALL отклонять новые данные, а не задерживать приём, а пакет с истёкшими повторами — отбрасываться. Предел памяти Collector (memory limiter) остаётся. Каждое отклонение и отброс учитываются (требование «Учёт потерь телеметрии»). Метрики Prometheus забирает сам: очереди для них в Collector нет, при недоступном Prometheus теряется только разрешение по времени — накопленные счётчики после его возврата прежние, а правила оповещений на это время не вычисляются (ограничение в REPORT.md).

Остановка любого хранилища телеметрии — Loki, Tempo, Prometheus — и самого Collector MUST NOT мешать API и worker: make test проходит, вложения становятся ready, 5xx из-за телеметрии нет. Память Collector SHALL оставаться ниже его лимита и не расти сверх пределов очередей; память реплик API при недоступном Collector — в пределах очередей SDK, без роста. Короткий отказ хранилища — короче срока повторов и при неполной очереди — потерь не даёт: отправленное во время отказа приходит в хранилище после его возврата. Долгий отказ даёт ограниченные и учтённые потери.

Проверка (команда драйвера скилла run-mtusi-messenger) SHALL под своей нагрузкой останавливать по очереди Loki и Tempo (коротко и долго), Prometheus и Collector, сверять это поведение, память по cgroup и по собственным метрикам Collector, учёт потерь и оповещения TelemetryTargetDown и TelemetryDataLoss (firing, затем снятие), возвращать стенд при любом исходе, завершаться ненулевым кодом при расхождении и сохранять вывод в evidence/telemetry/.

Scenario: Короткий отказ хранилища

  • WHEN Loki или Tempo остановлен на 10 секунд, за это время отправлен запрос с известным X-Request-Id, после чего хранилище запущено
  • THEN запись лога или трасса этого запроса находится после возврата хранилища, а счётчики потерь Collector для этого хранилища не выросли

Scenario: Долгий отказ хранилища

  • WHEN Loki или Tempo остановлен под нагрузкой дольше срока повторов Collector
  • THEN make test печатает PASS, очередь экспорта не больше своей ёмкости, память Collector ниже лимита, потери учтены его счётчиками, TelemetryTargetDown и TelemetryDataLoss в firing, а после запуска хранилища новые сигналы приходят, и оповещения сняты

Scenario: Отказ Prometheus

  • WHEN Prometheus остановлен на минуту под нагрузкой и снова запущен
  • THEN API работает, а приращение счётчика запросов API за время отказа, посчитанное после возврата, не меньше числа запросов нагрузки за то же время

Scenario: Отказ Collector под нагрузкой

  • WHEN Collector остановлен под нагрузкой на две минуты и снова запущен
  • THEN make test печатает PASS, память каждой реплики API после заполнения очередей SDK не растёт и ниже её лимита, TelemetryTargetDown в firing, MessengerQueueMetricsMissing не срабатывает, а после возврата Collector счётчики потерь SDK у реплик выросли, и оповещение снято

Requirement: Учёт потерь телеметрии

Каждое место, где телеметрия может потеряться, SHALL иметь счётчик, который доходит до Prometheus:

  • SDK API, worker и relay — отброшенное из-за полной очереди и неудачные отправки по сигналу (трассы, логи), а также заполнение и ёмкость очередей: собственные метрики SDK по semantic conventions (otel.sdk.*); счёт копится в процессе и приходит в Prometheus после возврата Collector;
  • Collector — отклонённое приёмником (предел памяти), не поставленное в очередь (очередь полна) и не отправленное после повторов, по сигналу и экспортёру; заполнение и ёмкость очередей экспорта.

Метки — компонент, сигнал и класс ошибки, без id. Гистограммы длительности самого SDK MUST NOT отдаваться: для учёта они не нужны и множат ряды. Правило записи SHALL суммировать потери по процессу так, чтобы учитывалась и первая потеря нового ряда; по нему работают панель потерь и TelemetryDataLoss. Переменные OTEL_* окружения на учёт не влияют (service-configuration, «Параметры телеметрии»).

Scenario: Потери SDK при недоступном Collector

  • WHEN Collector остановлен под нагрузкой дольше, чем нужно для заполнения очередей SDK, а затем запущен
  • THEN после возврата у реплик API выросли счётчики отброшенного из-за полной очереди или неудачных отправок SDK, ёмкость очередей SDK — как в [telemetry], а записей Loki из окна отказа меньше, чем записей stdout за то же время, и эти потери SDK видно на панели потерь

Scenario: Потери Collector при недоступном хранилище

  • WHEN Tempo остановлен под нагрузкой дольше срока повторов Collector
  • THEN счётчики Collector «не поставлено в очередь» или «не отправлено» экспортёра Tempo выросли, и это видно на панели потерь и в TelemetryDataLoss

Scenario: Без потерь

  • WHEN стенд работает без отказов
  • THEN панель потерь показывает ноль, а TelemetryDataLoss неактивно

Requirement: Счётчики после перезапуска процесса

Prometheus SHALL принимать от экспортёра Collector время начала накопительных рядов (created timestamp) и записывать ноль в момент начала ряда нового процесса, а экспортёр Collector SHALL перестать отдавать ряд, который не обновлялся минуту. Тогда приращение (increase()) учитывает и первые события нового процесса, и сброс счётчика процесса, перезапущенного не раньше чем через полторы минуты после остановки, или нового контейнера. Перезапуск того же процесса быстрее может занизить приращение на прежнее значение, если новый процесс догнал его до первого сбора, — ограничение в REPORT.md. Ряды остановленного процесса, в том числе снимок очереди relay, MUST NOT показываться текущими дольше двух минут.

Scenario: Перезапуск worker

  • WHEN worker остановлен больше чем на две минуты, участник загрузил K файлов, и worker запущен
  • THEN счёт времени до готовности worker по рядам Prometheus за это время вырос ровно на K

Scenario: Остановленный relay уходит из рядов

  • WHEN relay остановлен
  • THEN не позже чем через две минуты рядов глубины и возраста очереди в Prometheus нет

Requirement: Панели SLO, оповещений и конвейера

Dashboard из git SHALL показывать сверх панелей уровней 3 и 4:

  • SLI за 7 суток и за выбранный интервал с SLO и остатком бюджета;
  • доли окон оповещений (ошибки на LB, медленные запросы) с порогами;
  • историю состояний оповещений (pending и firing по оповещениям);
  • ответы LB по классам, разницу 5xx LB и 5xx API (ответы самого LB) и число готовых реплик;
  • конвейер телеметрии: заполнение очередей экспорта Collector и очередей SDK, потери в секунду по месту, память Collector, доступность целей сбора.

Запросы SHALL ссылаться на имена и метки, которые есть в Prometheus; ряд, которого по смыслу может не быть (оповещения, потери), SHALL давать ноль, а не пустой ответ.

Scenario: Новые панели после трафика

  • WHEN стенд поднят, выполнены make test и загрузка файла до ready
  • THEN каждый запрос новых панелей к Prometheus выполняется без ошибки и возвращает данные, в том числе на стенде без оповещений и потерь

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

  • WHEN оповещение было в firing и снято
  • THEN панель истории состояний показывает интервал firing этого оповещения

Requirement: SLO, оповещения и инциденты в отчёте

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

  • три SLI: числитель, знаменатель, формулы PromQL, почему доступность считается на LB, SLO, окно и значения на момент отчёта;
  • таблицу оповещений (условие, окно, порог, for, severity, runbook), почему правила Prometheus, а не Grafana, и почему без Alertmanager;
  • буферизацию Collector и очереди SDK с числами, где считаются потери, результаты отказа каждого хранилища и Collector (память, потери) и счётчики после перезапуска процесса;
  • два инцидента — остановленный worker; медленная или недоступная БД против медленного handler — и третий — недоступное хранилище телеметрии: хронология, оповещение, шаги диагностики только по сохранённым наблюдениям (панель, запрос и его значение, трасса, запись лога из evidence), причина, восстановление и что стало с SLI;
  • сумму лимитов стенда против ресурсов ВМ и сколько CPU и памяти нужно ВМ.

Scenario: Отчёт по SLO и инцидентам

  • WHEN проверяющий читает REPORT.md
  • THEN для каждого SLI есть формула и SLO, для каждого оповещения — строка таблицы и runbook, для каждого из трёх инцидентов — шаги диагностики со ссылками на сохранённые наблюдения, а для бюджета — числа и требуемые ресурсы ВМ

Requirement: Выбор трасс в голове

Долю трасс, которые выбираются при создании корня, SHALL задавать настройка (service-configuration, «Параметры телеметрии»), по умолчанию — все трассы, как раньше. Корень трассы — server span запроса и consumer span доставки без контекста — SHALL выбираться по идентификатору трассы с этой долей; span с родителем — локальным или удалённым из задания — SHALL следовать флагу выборки родителя: у одной загрузки выбрана либо вся цепочка API → relay → worker, либо ни один её span.

Невыбранный запрос и невыбранная доставка MUST NOT записывать span, в том числе дочерние span хранилищ и процесса обработки. Метрики (счёт и длительность) и записи журнала у них SHALL быть те же, что у выбранных: выборка касается только трасс, а журнал и метрики остаются полным счётом событий. Запись журнала невыбранного запроса в хранилище логов SHALL нести его идентификаторы трассы и span с флагом «не выбрано» — по ним связаны записи одной загрузки, хотя трассы нет; запись stdout — без полей трассы, как вне span (service-logging, «Связь записей с трассой»).

SDK SHALL считать начатые span по решению выборки (выбран, отброшен) и происхождению родителя во внутренних метриках, и этот счёт SHALL доходить до Prometheus: отброшенное выборкой отличается от потерь. Отброшенное выборкой MUST NOT считаться потерей телеметрии: правило потерь (требование «Учёт потерь телеметрии») его не включает, панель потерь и TelemetryDataLoss на выборку не реагируют. Счётчик живых span MUST NOT отдаваться: для учёта он не нужен.

Scenario: Доля по умолчанию

  • WHEN телеметрия включена без настройки доли, и клиент выполняет N запросов к API
  • THEN у каждого запроса есть трасса, как раньше, а счёт начатых span не содержит отброшенных выборкой

Scenario: Выборка десяти процентов

  • WHEN доля — 0,1, и клиент выполняет N ≥ 1000 запросов с известными X-Request-Id
  • THEN трасс этих запросов в Tempo — в 95-процентном биномиальном интервале около 0,1 · N, счёт histogram длительности вырос на N, в Loki N записей доступа, у записей невыбранных запросов есть идентификатор трассы с флагом «не выбрано», а трассы с ним в Tempo нет, и счёт отброшенных выборкой корней близок к 0,9 · N

Scenario: Цепочка загрузки выбирается целиком

  • WHEN доля — 0,1, и участник загружает файлы, которые становятся ready
  • THEN у каждой загрузки в Tempo либо вся цепочка — server span API, span producer relay, consumer span worker с дочерними span, — либо ни одного её span, а счёт исходов worker и время до готовности учитывают все загрузки

Scenario: Выборка не считается потерей

  • WHEN доля — 0,1, и стенд работает под нагрузкой без отказов
  • THEN панель потерь показывает ноль, TelemetryDataLoss неактивно, а счёт отброшенных выборкой span растёт

Requirement: Наборы границ histogram

Границы buckets histogram длительности HTTP, длительности заданий и времени до готовности SHALL выбираться набором из настроек (service-configuration, «Параметры телеметрии»): default — прежние границы, coarse — меньше границ при тех же покрываемых диапазонах (требования «Метрики HTTP API», «Метрики заданий worker», «Время до готовности»). Оба набора SHALL содержать границы SLO — 0,25 с у длительности HTTP и 30 с у времени до готовности (требование «SLI и SLO»): правила записи, оповещения и панели работают при любом наборе. Интервал отправки метрик SDK SHALL быть не больше половины срока, после которого экспортёр Collector перестаёт отдавать необновлённый ряд (требование «Счётчики после перезапуска процесса»): иначе ряды пропадали бы между отправками.

Scenario: Грубые границы

  • WHEN телеметрия реплик и worker включена с набором coarse, и под нагрузкой загрузки становятся ready
  • THEN значения le трёх histogram в Prometheus — границы набора coarse, среди них "0.25" у длительности HTTP и "30.0" у времени до готовности, а правила записи SLI задержки и времени до готовности дают значения

Scenario: Границы по умолчанию

  • WHEN телеметрия включена без настройки набора
  • THEN границы трёх histogram — прежние, ряды и запросы панелей те же, что раньше

Requirement: Сбалансированная конфигурация телеметрии

Сбалансированная конфигурация — выбор трасс в Collector после завершения трассы (tail sampling) по правилам этой системы и отбор лишних рядов Prometheus — SHALL лежать в git рядом с профилем цены телеметрии и проверяться им (load-benchmark, «Профиль цены телеметрии»):

  • SDK отправляет все трассы; Collector держит трассу до решения не дольше срока ожидания, которого хватает цепочке загрузки при нагрузке ниже насыщения;
  • сохраняются все трассы, где есть span со статусом ошибки, consumer span с неуспешным исходом задания (failed, retry, error, requeued, dropped: у failed статуса ошибки нет — это исход, а не исключение), server span не короче порога SLO задержки (0,25 с) или consumer span не короче 5 с, и заданная доля остальных; поздние span уже сохранённой трассы сохраняются вместе с ней;
  • Prometheus забирает у Loki, Tempo и у себя только ряды приёма данных, отказов и объёма хранения (up — всегда); остальные собственные ряды хранилищ — нет: их не читает ни панель, ни правило, ни проверка; метрики приложения и Collector — все;
  • журнал и метрики приложения не выбираются.

Слой конфигурации Collector MUST NOT менять ничего, кроме выбора трасс в pipeline трасс, а конфигурация Prometheus — ничего, кроме отбора рядов собственных метрик хранилищ: проверка до замера сравнивает их с конфигурациями рабочего стенда и проверяет инструментами Collector и Prometheus. Рабочий стенд SHALL оставаться со всеми трассами и полным набором рядов: проверки уровней 3 и 4 ищут свой запрос и задание по сохранённым наблюдениям. Конфигурация считается проверенной, когда метка профиля подтверждает критерии B1–B5 (load-benchmark, «Цена телеметрии в отчёте»).

Scenario: Ошибки и медленные запросы сохраняются

  • WHEN под нагрузкой профиля со сбалансированной конфигурацией внесены 500 API, неудачные задания и медленные записи
  • THEN в Tempo есть трасса каждого 500 и каждой записи, медленной по серверу (server span не короче 0,25 с), по X-Request-Id, у неудачного задания — вся цепочка от server span загрузки до consumer span исхода failed, а из остальных запросов, в том числе быстрых регистраций, сохранена заданная доля в биномиальном интервале

Scenario: Слой Collector меняет только выбор трасс

  • WHEN проверка до замера собирает итоговую конфигурацию Collector со слоем и без него
  • THEN они отличаются только процессором выбора трасс и списком процессоров pipeline трасс, а иначе профиль завершается ненулевым кодом до стенда

Scenario: Рабочий стенд без выбора

  • WHEN выполнены make run_docker и проверка телеметрии рабочего стенда
  • THEN в конфигурации Collector нет выбора трасс, Prometheus забирает все ряды хранилищ, а свой запрос и своё задание находятся, как раньше