Files
2026-11-04 20:56:35 +03:00

261 lines
20 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.
# Отчёт — лабораторная 6
- Автор, группа: Пластинин Денис, БВТ2303
- Целевая оценка: 5
- Выбранный трек: 2 — SLO и обнаружение инцидентов
## Запуск из чистого clone
Требуются Docker Desktop с Compose v2, Go из `go.mod`, Python 3.9+ и `curl`. Все образы закреплены в Compose или Dockerfile. Основной observability stack: OpenTelemetry Collector `0.160.0`, Prometheus `3.13.3`, Loki `3.7.9`, Tempo `2.10.10`, Grafana `13.2.4`.
```bash
cp lab6.env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 180
make test
make test-lab5-acceptance
make test-lab5
make test-lab6-smoke
```
Интерфейсы локального стенда:
- API: `http://127.0.0.1:8080`;
- Swagger: `http://127.0.0.1:8081`;
- Grafana: `http://127.0.0.1:3000`;
- Prometheus: `http://127.0.0.1:9090`;
- Loki API: `http://127.0.0.1:3100`;
- Tempo API: `http://127.0.0.1:3200`.
Безопасная остановка сохраняет volumes:
```bash
docker compose --env-file .env down
```
Намеренное удаление всех учебных данных выполняется отдельно:
```bash
docker compose --env-file .env down -v
```
## Архитектура
Возможности Lab 5 сохранены: две API-реплики за Nginx, PostgreSQL как источник бизнес-состояния, Valkey для сессий, MinIO/S3 для изображений, transactional outbox, Redis Streams и отдельный worker. Lab 6 добавляет единый telemetry pipeline.
```text
Client → Nginx → API replicas → PostgreSQL / Valkey / MinIO
│
PostgreSQL outbox → Dispatcher → Redis Streams → Worker → PostgreSQL / MinIO
│ │
└──────── OTLP ──────────┤
API ────────────────────────────── OTLP ──────────┤
▼
OpenTelemetry Collector
├─ metrics → Prometheus
├─ logs → Loki
└─ traces → Tempo
│
▼
Grafana
```
Приложения экспортируют OTLP только в Collector. Они не знают адреса Loki и Tempo. Collector выполняет `memory_limiter` до `batch`, ограничивает очереди exporter и прекращает retry через 30 секунд. Evidence проверяет queue size/capacity, failures и drops отдельно для `otlp_grpc/tempo` и `otlp_http/loki`, а память — по пиковому RSS за двухминутное окно. Недоступность telemetry backend поэтому не блокирует бизнес-запросы и не вызывает неограниченный рост памяти.
Prometheus, Loki, Tempo и Grafana используют отдельные volumes. Retention локальных logs/traces — 7 суток; Prometheus хранит 7 суток. Collector является транспортом и процессором, а не долговременным хранилищем.
### Resource attributes и среды
Каждый процесс объявляет:
```text
service.name = messenger-api | messenger-dispatcher | messenger-worker
service.version = значение SERVICE_VERSION
deployment.environment.name = lab
service.instance.id = стабильный ID процесса
```
В учебном Compose одна среда `lab`. Атрибут среды всё равно передаётся: один и тот же dashboard и TraceQL остаются пригодны для `test`/`production`, если стенд будет развёрнут там позднее. Среда и service name имеют низкую кардинальность.
### Middleware и сквозной контекст
HTTP middleware создаёт server span, нормализует route template, считает request counter/histogram и добавляет в JSON-лог `request_id`, `trace_id` и `span_id`. Реальный UUID из URL не становится label.
При upload текущий W3C context сохраняется в outbox envelope как `traceparent`/`tracestate`. Dispatcher создаёт producer span. Worker извлекает context и создаёт consumer span. Поэтому один trace показывает цепочку:
```text
HTTP upload → staging S3 → PostgreSQL/outbox → Redis publish
→ Redis consume → image transform → S3 variants → PostgreSQL ready
```
Идентификаторы пользователя, чата, сообщения, вложения, filename, raw URL и request ID запрещены в metric labels. Ограниченные технические ID допустимы в logs/spans синтетического стенда для расследования. `Authorization`, session token, пароль, тело сообщения, байты изображения, S3 credentials и signed URL не экспортируются.
## Хранилища и назначение сигналов
| Сигнал | Хранилище | На какой вопрос отвечает |
| --- | --- | --- |
| Метрика | Prometheus TSDB | Есть ли массовая деградация, когда началась и каков масштаб |
| Лог | Loki | Какое событие и ошибка произошли в конкретном процессе |
| Trace | Tempo | На каком участке сквозного запроса потрачено время или возникла ошибка |
| Dashboard / Explore | Grafana | Единый поиск, корреляция и переходы между тремя сигналами |
Grafana provisioning создаёт Prometheus, Loki и Tempo без ручной настройки. Tempo datasource включает поиск TraceQL, node graph, service map, переходы trace → logs и trace → metrics. Loki derived field открывает trace по `trace_id`; Prometheus exemplars ведут из histogram в Tempo.
## Карта сигналов
| Контрактный сигнал | Реализация и единица |
| --- | --- |
| HTTP requests | `messenger_http_requests_total{method,route,status_class}`, requests |
| HTTP duration | `messenger_http_request_duration_seconds_bucket`, seconds |
| Delivery outcomes | `messenger_attachment_worker_jobs_total{job_type,result}`, deliveries |
| Terminal job transitions | `messenger_attachment_terminal_transitions_total{status}`, first durable outcome per job |
| Job duration | `messenger_attachment_worker_job_duration_seconds_bucket`, seconds |
| Time to ready | `messenger_attachment_time_to_ready_seconds_bucket`, seconds |
| Queue states | `messenger_attachment_jobs_count{status}`, jobs |
| Oldest job | `messenger_attachment_jobs_oldest_age_seconds{status}`, seconds |
| Worker saturation | `messenger_attachment_worker_jobs_in_flight` / `messenger_attachment_worker_capacity`, jobs |
| Outbox | `messenger_outbox_pending`, events |
| Logs | OTLP log records: timestamp, severity, service, event, trace/span IDs |
| Traces | HTTP server, producer, consumer, PostgreSQL, Redis and S3 spans |
p50/p95/p99 вычисляются `histogram_quantile` из суммы bucket всех реплик. Перцентили реплик не усредняются. Queue depth и oldest age показываются отдельно: количество элементов не измеряет длительность ожидания.
## SLO
### Доступность API
SLI — доля бизнес-запросов без `5xx`. Health и `/metrics` исключены. Ожидаемые клиентские `4xx` не считаются отказом сервиса.
```text
bad = business responses 5xx
total = all business responses
SLI = 1 - bad / total
SLO = 99.5% за 30 дней
error budget = 0.5%
```
Цель 99,5% выбрана для учебного single-host стенда без multi-zone HA: она требует реагировать на деградацию, но не заявляет недостижимую для локального Compose доступность.
### Время готовности вложений
SLI — доля уникальных durable attachment jobs, чей первый terminal outcome равен `ready` и наступил не позднее 30 секунд после acceptance. Время acceptance назначает PostgreSQL при создании job, поэтому начало и конец интервала принадлежат одному clock domain. PostgreSQL записывает первый outcome в append-only ledger в той же транзакции, что и переход job. Миграция переносит уже завершённые jobs с `accepted_at = created_at` и `terminal_at = updated_at`. Повторная delivery и ручной replay не меняют уже учтённый результат: job, впервые завершившаяся `failed`, остаётся bad event даже после успешного replay.
```text
bad = failed + ready later than 30s
total = ready + failed
SLI = 1 - bad / total
SLO = 99% за 30 дней
error budget = 1%
```
`messenger_attachment_terminal_transitions_total` и cumulative buckets `messenger_attachment_time_to_ready_seconds_bucket` экспортируются из ledger. Bucket `le="+Inf"` является durable количеством первых outcomes `ready` и используется как знаменатель ready jobs.
30 секунд отделяют нормальную асинхронную обработку от видимой пользователю задержки и существенно превышают обычное время небольшого синтетического изображения.
### Multi-window burn-rate alerts
Для обоих SLO используются две пары окон:
| Alert | Burn rate | Короткое окно | Длинное окно | Назначение |
| --- | ---: | ---: | ---: | --- |
| Fast | 14,4× | 5 минут | 1 час | быстро обнаружить сильный инцидент |
| Slow | 6× | 30 минут | 6 часов | обнаружить устойчивую деградацию |
Условие должно выполняться в обоих окнах пары. Короткое окно быстро реагирует, длинное отсекает одиночный шум. Отдельные operational alerts контролируют отсутствие worker, рост oldest queued age и Redis Stream lag.
## Dashboard и поиск
Dashboard **Messenger Lab 6 overview** содержит:
- API RPS, error ratio, p50/p95/p99;
- состояния API/worker/dispatcher и DB pool;
- accepted/ready/failed jobs, processing duration и end-to-end ready time;
- queue depth, oldest age, Redis lag/PEL, outbox pending;
- worker busy/capacity;
- SLO и firing alerts;
- Collector export failures и переходы к Explore.
Поиск trace выполняется в Grafana Explore → Tempo по `service.name`, span name, route, status и duration. Из trace доступен переход в Loki по тому же `trace_id`. Пошаговые процедуры:
- `monitoring/runbooks/api-availability.md`;
- `monitoring/runbooks/attachment-pipeline.md`.
## Доказательства критериев
| Критерий | Команда/сценарий | Проверяемый результат | Доказательство |
| --- | --- | --- | --- |
| Offline contract | `make check` | структура и обязательные файлы не ослаблены | stdout CI |
| OpenAPI | `make validate` | OpenAPI 3.1 проходит полную проверку | stdout CI |
| Публичный smoke | `make test` | бизнес-API предыдущих лабораторных работает | stdout CI |
| Lab 5 regression | `make test-lab5-acceptance && make test-lab5` | durable jobs, retry, replay и idempotency сохранены | stdout CI |
| Три telemetry signal | `make test-lab6-smoke` | нагрузка создаёт metrics/logs/traces, attachments доходят до terminal state | `evidence/runtime/.../baseline-*.json` |
| Worker incident | `scripts/incident-worker.sh short` | alert firing, после запуска worker backlog дренирован и alert resolved | `worker-short-*/` |
| DB incident | `scripts/incident-database.sh` | видны 5xx и DB error spans, burn-rate firing, API восстанавливается, оперативный alert resolved | `database-*/` |
| Длительная деградация | `scripts/incident-worker.sh long` | растут oldest age/lag, срабатывает backlog alert, все jobs затем ready | `worker-long-*/` |
| Telemetry outage | `scripts/incident-telemetry.sh` | API readiness остаётся 200, Collector queue/retry ограничены, backend восстанавливается | `telemetry-*/` |
| Полный трек 2 | `make test-lab6` | выполнены short/long incidents, firing/resolved и schema validation | `evidence/runtime/lab6-*/` |
Runtime evidence создаётся локально и игнорируется Git до проверки содержимого. В нём нет session tokens, cookies, passwords, payload envelope и пользовательских текстов. Для публикации выбираются только небольшие агрегированные JSON.
## Методика экспериментов
`scripts/lab6-traffic.py` создаёт изолированных синтетических пользователей и чат, затем генерирует сообщения и PNG-вложения. Нагрузка closed-loop, concurrency и duration фиксируются в JSON; HTTP status и p50/p95/p99 рассчитываются клиентом только как вспомогательные данные. Серверные SLO используют Prometheus histograms.
Полный сценарий:
```bash
make test-lab6
```
Он выполняет:
1. baseline mixed load;
2. короткую остановку worker;
3. краткую недоступность PostgreSQL под message traffic;
4. длительную остановку worker;
5. остановку Loki и Tempo под mixed traffic;
6. проверку evidence и переходов alert `firing → resolved`.
Каждый incident script устанавливает trap и восстанавливает затронутые сервисы. `docker compose down -v` не используется. Baseline/degraded/recovered snapshots содержат одни и те же PromQL, поэтому сравнение не зависит от ручного выбора панели.
Гипотезы трека:
- короткий сильный отказ расходует бюджет быстрее 14,4× и обнаруживается fast alert;
- длительная деградация выявляется ростом oldest queued age и multi-window SLO;
- после восстановления worker backlog уменьшается, все принятые jobs достигают terminal state, alerts переходят в resolved;
- отказ Loki/Tempo не влияет на бизнес-ответы, а ограниченные очереди Collector отражают потери telemetry без неограниченного роста RAM.
Фактические времена обнаружения и восстановления берутся из `started_at`, `alert-firing.json`, `recovery_started_at` и `alert-resolved.json`. Отсутствие перехода считается падением сценария, а не успешным экспериментом. Ложное срабатывание проверяется baseline snapshot: до fault operational и burn-rate alerts не должны находиться в `firing`.
## Результаты прогона
Полный прогон `2026-11-04` сохранён локально в `evidence/runtime/lab6-20261104T174049Z` и прошёл schema validation без ошибок. Обезличенная сводка включена в `evidence/lab6-results.json`. Время обнаружения является верхней границей: сценарий опрашивает alert после выдержки заданной длительности отказа.
| Инцидент | Наблюдение | Обнаружение | Восстановление |
| --- | --- | ---: | ---: |
| Worker, короткий | `AttachmentWorkerUnavailable` firing, очередь затем обработана | не более 76 с | alert resolved через 13 с, полное наблюдение 33 с |
| PostgreSQL | operational 5xx и fast burn-rate firing; сохранены 3 DB error traces, один связан с API-логом | не более 78 с | operational alert resolved через 134 с, API стабилен через 154 с |
| Worker, длительный | oldest queued age рос; backlog, fast и slow burn alerts firing | не более 181 с | alert resolved через 20 с, backlog обработан за 91 с |
| Loki и Tempo | очереди выросли до 15/512 и 16/512, затем дренировались до нуля; peak RSS 226.7 MB | 30 с отказа | `/health/ready` вернул 200, backends healthy через 31 с |
Перед первым fault список firing alerts был пуст. Burn-rate alerts после инцидента закономерно остаются активными дольше оперативных alerts: их длинные окна сохраняют уже потраченный error budget. Это не считается ложным срабатыванием следующей фазы.
## Ограничения
- Стенд single-host и не проверяет потерю всего Docker host или volume.
- Loki и Tempo работают в single-binary режиме без репликации.
- 30-дневный SLO определяется production-подобными окнами, но учебный эксперимент создаёт искусственно высокий error ratio и не заменяет месячное наблюдение.
- Closed-loop generator подвержен coordinated omission; capacity conclusions по его RPS не делаются.
- Остановка telemetry backend проверяет ограниченное поведение exporter, но не гарантирует отсутствие потерь: после заполнения bounded queue часть telemetry намеренно отбрасывается.
- Внешняя доставка alerts не настраивается; проверяются локальные состояния Prometheus `firing` и `resolved`.
## Источники
ИИ-ассистент использовался при подготовке кода, конфигурации и текста; результат проверен тестами, CI-сценариями и воспроизводимым fault-прогоном.
- OpenTelemetry Collector configuration и Go SDK;
- W3C Trace Context;
- Prometheus histograms и multi-window burn-rate alerts;
- Grafana provisioning, Loki OTLP ingestion и Tempo TraceQL;
- документация Redis Streams, PostgreSQL, MinIO и Docker Compose.