Files
mtusi2026lab6/openspec/specs/observability/spec.md
T
2026-11-11 11:31:22 +03:00

29 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, «Параметры телеметрии»).

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-Id I, а worker обработал задание
  • THEN у трассы, записей лога и рядов метрики этого ответа service.name — messenger-api, service.instance.id — I, service.version — версия контракта, deployment.environment.name — lab; у сигналов задания service.name — messenger-worker и service.instance.id — instance_id из журнала worker

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

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

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

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

Scenario: Чужой traceparent

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

Requirement: Метрики HTTP API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Requirement: Трассы API и worker

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Телеметрия SHALL быть включена на рабочем стенде compose у реплик API и worker. В консоли (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 есть имя, единица и запрос, для каждого хранилища — назначение и версия, а для суммы лимитов — числа и замер