29 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, «Параметры телеметрии»).
Relay, уборщик, сервис миграций и процесс обработки изображения SDK MUST NOT запускать: их журнал — stdout контейнера, а работа процесса обработки видна span в трассе worker.
Телеметрия MUST NOT влиять на ответы API и обработку заданий: отправка идёт в фоне, очереди SDK ограничены, недоступный или зависший Collector MUST NOT задерживать запросы и задания и приводить к ошибкам, и SDK SHALL продолжать отправку, когда Collector вернулся, без перезапуска процесса. Телеметрия, которую не удалось отправить, теряется. Записи самого SDK об отказе отправки SHALL идти только в stdout и не чаще одной записи в минуту от каждого модуля SDK.
API MUST NOT продолжать трассу клиента: входящие traceparent и tracestate игнорируются, каждый запрос начинает свою
трассу (публичная точка входа; перенос контекста внутри стенда — уровень 4).
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. В консоли (make run_dev, make run_worker), во временном прогоне make test_isolated, на стенде отказов make failure_checks и на стенде bench/ она
SHALL быть выключена по умолчанию: методика и бюджеты этих стендов прежние, а профиль, которому нужна телеметрия, включает её
явно. Выключенная телеметрия SHALL выключать SDK целиком: ни трасс, ни метрик, ни отправки записей журнала, ни обращений к
Collector, ни полей трассы в журнале. Вариант «телеметрия выключена» трека 1 — та же одна настройка.
Scenario: Консоль без телеметрии
- WHEN сервис запущен
make run_devбез настроек телеметрии - THEN запись о старте говорит, что телеметрия выключена, попыток отправки нет, а в записях журнала нет
trace_id
Scenario: Тестовые стенды без телеметрии
- WHEN выполняются
make test_isolatedиmake failure_checks - THEN записи о старте их API и worker говорят, что телеметрия выключена, Collector на этих стендах не запускается, а результаты проверок прежние
Requirement: Наблюдаемость в отчёте
REPORT.md SHALL описывать:
- назначение Collector и каждого хранилища: на какой вопрос об инциденте отвечают метрика, лог и трасса;
- закреплённые версии SDK, semantic conventions, дистрибутива Collector, хранилищ и Grafana;
- таблицу «логический сигнал контракта → инструмент SDK → имя и метки в Prometheus или поля в Loki и Tempo → единица» и запросы панелей dashboard;
- определение доли ошибок HTTP и успешных и ошибочных заданий;
- соответствие атрибутов ресурса меткам хранилищ и имён
OTEL_*skeleton настройкам; - сумму лимитов стенда с телеметрией против ресурсов ВМ и замер простоя и пика сервисов телеметрии;
- ограничения: что теряется при отказе Collector, ответы балансировщика вне метрик API, приём OTLP без аутентификации до лабы 7.
Scenario: Отчёт по наблюдаемости
- WHEN проверяющий читает
REPORT.md - THEN для каждого сигнала уровня 3 есть имя, единица и запрос, для каждого хранилища — назначение и версия, а для суммы лимитов — числа и замер