# 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`