20 KiB
Отчёт — лабораторная 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.
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:
docker compose --env-file .env down
Намеренное удаление всех учебных данных выполняется отдельно:
docker compose --env-file .env down -v
Архитектура
Возможности Lab 5 сохранены: две API-реплики за Nginx, PostgreSQL как источник бизнес-состояния, Valkey для сессий, MinIO/S3 для изображений, transactional outbox, Redis Streams и отдельный worker. Lab 6 добавляет единый telemetry pipeline.
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 и среды
Каждый процесс объявляет:
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 показывает цепочку:
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 не считаются отказом сервиса.
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.
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.
Полный сценарий:
make test-lab6
Он выполняет:
- baseline mixed load;
- короткую остановку worker;
- краткую недоступность PostgreSQL под message traffic;
- длительную остановку worker;
- остановку Loki и Tempo под mixed traffic;
- проверку 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.