forked from mtusi2026/mtusi2026lab2
57 lines
5.8 KiB
Markdown
57 lines
5.8 KiB
Markdown
# 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`
|
||
|