5.8 KiB
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и dashboardsmessenger-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/searchGrafana - THEN ответ
401