Files

57 lines
5.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`