Files
mtusi2026lab6/openspec/specs/lab6-telemetry-stack/spec.md
T

5.8 KiB
Raw Blame History

lab6-telemetry-stack Specification

Purpose

Определяет стек наблюдаемости в стенде: Collector, хранилища метрик, логов и трасс и Grafana, их конфигурацию и provisioning в Git, volumes, опубликованные порты и проверки конфигурации.

Requirements

Requirement: Collector, хранилища и Grafana в общем стенде

Стенд SHALL поднимать одной командой make up вместе с приложением сервисы otel-collector (OpenTelemetry Collector contrib), prometheus (метрики), loki (логи), tempo (трассы) и grafana; образы SHALL быть закреплены тегом и digest, контейнеры SHALL работать не от root с лимитами CPU и памяти и healthcheck, который доходит до healthy. Collector SHALL принимать OTLP/HTTP только во внутренних сетях стенда и раскладывать метрики в Prometheus, логи в Loki, трассы в Tempo; в каждом pipeline SHALL стоять ограничитель памяти, маскирование и батчинг, а экспортёры SHALL иметь ограниченную очередь и ограниченный по времени повтор. Приложение SHALL NOT зависеть от готовности этих сервисов при старте.

Scenario: Стенд из чистого состояния

  • WHEN в новом изолированном Compose project с пустыми volumes выполняется make up
  • THEN docker compose ps показывает otel-collector, prometheus, loki, tempo, grafana в состоянии healthy рядом с lb, api ×2, relay, worker, postgres, valkey, s3, broker

Scenario: OTLP не опубликован

  • WHEN проверяются опубликованные порты стенда
  • THEN порты 4318 и 8888 Collector не опубликованы на хост, а Prometheus, Loki, Tempo и Grafana опубликованы только на 127.0.0.1

Requirement: Конфигурация и provisioning в Git

Конфигурация Collector, Prometheus (включая recording rules), Loki, Tempo, datasources и dashboards Grafana SHALL лежать в infra/ и подключаться в контейнеры только для чтения. Grafana SHALL при старте импортировать datasources с фиксированными uid prometheus, loki, tempo и связями trace ↔ log, а также dashboards из JSON в Git без ручных действий; dashboards SHALL ссылаться только на существующие имена метрик. make obs-validate SHALL проверять конфигурацию Collector его же бинарником, конфигурацию и rules Prometheus — promtool, конфигурации Loki и Tempo — их бинарниками, dashboards — как валидный JSON с uid и панелями.

Scenario: Provisioning импортирован

  • WHEN стенд поднят из чистого состояния
  • THEN API Grafana показывает три datasource со статусом OK и dashboards messenger-api и messenger-pipeline с provisioned: true в папке Messenger

Scenario: Dashboard показывает данные приложения

  • WHEN выполнен make test и создана нагрузка
  • THEN каждый запрос панелей к Prometheus выполняется без ошибок и ссылается на существующие метрики, панели RPS, ошибок, длительности API и jobs по исходу возвращают серии job="messenger-api"/job="messenger-worker"

Scenario: Ошибка конфигурации ловится до запуска

  • WHEN выполняется make obs-validate
  • THEN команда завершается кодом 0 и печатает успешную проверку Collector, Prometheus, Loki, Tempo и dashboards

Requirement: История телеметрии переживает рестарт

Prometheus, Loki, Tempo и Grafana SHALL хранить данные в именованных volumes с ограниченным retention; рестарт этих сервисов без удаления volumes SHALL сохранять ранее записанные метрики, логи и трассы. Удаление учебных данных SHALL выполняться только явной командой make reset-data.

Scenario: Рестарт хранилищ

  • WHEN найден лог и трасса контролируемого запроса, затем выполнен docker compose restart prometheus loki tempo grafana
  • THEN после готовности тот же лог по request_id, та же трасса по trace id и серии метрик API находятся снова

Requirement: Секрет Grafana вне Git

Пароль администратора Grafana SHALL генерироваться локально в gitignored secrets/ (make secrets) и передаваться контейнеру как compose secret через GF_SECURITY_ADMIN_PASSWORD__FILE; анонимный доступ и регистрация SHALL быть выключены.

Scenario: Вход без пароля отклонён

  • WHEN клиент без учётных данных запрашивает GET /api/search Grafana
  • THEN ответ 401