Files
mtusi2026lab6/REPORT.md
T

122 lines
14 KiB
Markdown
Raw 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
- Автор, группа: Казанцева Виктория / БПИ2301
- Целевая оценка: 5, трек 2 (SLO и обнаружение инцидентов)
- Commit/PR: не публиковался
- Источники: OpenTelemetry Collector, Prometheus histograms, W3C Trace Context, Grafana provisioning.
## Запуск из чистого clone
Нужны Docker Compose v2 и Python 3.9+ на хосте (проверки). Образы закреплены в `compose.yaml`, приложение собирается из этого репозитория.
```
python scripts/render-s3-config.py
docker compose --env-file .env config --quiet
docker compose --env-file .env build api-1
docker compose --env-file .env up -d
```
`scripts/render-s3-config.py` читает `S3_ACCESS_KEY` и `S3_SECRET_KEY` из локального `.env` и пишет gitignored `infra/seaweed/s3.json`. Шаблон переменных — `.env.example`. Файл `.env` не коммитится.
Схема БД применяется дважды и одинаково: `app/schema.sql` монтируется в `docker-entrypoint-initdb.d` и повторно накатывается приложением под `pg_advisory_lock`. Бакет S3 создаёт API/worker при старте, если его ещё нет. Очередь `attachment.process.v1` объявляет приложение.
Готовность: `GET http://127.0.0.1:8080/health/ready` возвращает 200. На Windows публичные скрипты запускать с `PYTHONUTF8=1`, потому что `Path.read_text()` в проверках курса читает JSON в кодировке локали.
```
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080
```
Остановка без удаления данных: `docker compose --env-file .env stop`. Удаление учебных томов только явно: `docker compose --env-file .env down -v`.
`scripts/restart.sh` перезапускает postgres, SeaweedFS, RabbitMQ, обе API-реплики и worker, ждёт их healthcheck и затем перечитывает upstream в nginx. Тома не удаляются. `scripts/stop-one.sh` останавливает только `api-1` или `api-2` из `TARGET_INSTANCE_ID`. На Windows эти `.sh` напрямую не исполняются (`WinError 193`); проверка ниже запускала их через Git Bash, не меняя `tests/resilience.py`.
## Архитектура
Бизнес-API лабораторий 1–5 не менялся. Две реплики `api-1` и `api-2` за nginx (`127.0.0.1:8080`, round-robin). PostgreSQL — источник истины для пользователей, сессий, чатов, сообщений, идемпотентности и outbox. SeaweedFS хранит байты вложений (`staging/`, `originals/`, `variants/`). RabbitMQ — durable очередь `attachment.process.v1`, persistent messages, confirm и ручной ack. Worker отдельно от API.
Запись вложения: проверка доступа, байты в staging, строка attachment и outbox в одной транзакции, затем publish. Сбой брокера после commit не отменяет `202 queued`: poller допубликует outbox. Worker идемпотентен, lease 60 с, повтор того же `traceparent`.
Наблюдаемость: API и worker шлют OTLP/HTTP protobuf на Collector (`:4318`). Collector: memory limiter 192 MiB, удаление URL/SQL/Authorization, batch, очередь exporter 200 и retry не дольше 30 с. Дальше Prometheus (scrape `:8889`), Loki (OTLP), Tempo (gRPC). Grafana только запрашивает эти три хранилища и не хранит сигналы сама. Дашборд `messenger-overview` и datasources поднимаются provisioning-ом из Git. Правила — `infra/prometheus/rules.yml`.
| Роль | Сервис | Образ |
| --- | --- | --- |
| API, worker | api-1, api-2, worker | локальная сборка `mtusi-lab6-messenger:1.6.0` на `python:3.12.8-slim-bookworm` |
| Балансировщик | nginx | `nginx:1.27.4-alpine` |
| БД | postgres | `postgres:16.6-alpine` |
| S3 | s3 | `chrislusf/seaweedfs:4.51` |
| Брокер | rabbitmq | `rabbitmq:3.13.7-management-alpine` |
| Collector | otel-collector | `otel/opentelemetry-collector-contrib:0.120.0` |
| Метрики | prometheus | `prom/prometheus:v2.55.1` |
| Логи | loki | `grafana/loki:3.3.2` |
| Трассы | tempo | `grafana/tempo:2.7.2` |
| UI | grafana | `grafana/grafana:11.5.2` |
Prometheus хранит ряды и состояние алертов. Loki хранит структурные JSON-логи. Tempo хранит спаны. Grafana их показывает.
Метрики не используют `user_id`, `chat_id`, `message_id`, `attachment_id` как labels. Маршрут в метрике — шаблон. В логах есть `trace_id` и `span_id`. Пароли, токены, текст сообщений и байты картинок в telemetry не пишутся.
## Доказательства критериев
| Критерий | Команда | Наблюдение | Файл |
| --- | --- | --- | --- |
| Контракт skeleton | `PYTHONUTF8=1 python scripts/check_contract.py` | PASS | вывод в этой сессии |
| Публичный smoke | `PYTHONUTF8=1 python tests/smoke.py --base-url http://127.0.0.1:8080` | PASS после включённой telemetry | — |
| Готовность не зависит от Grafana | `GET /health/ready` при остановленном Tempo | 200, бизнес-GET тоже 200 | `evidence/incidents.json` |
| Метрики API и worker | PromQL после smoke | есть `http_server_requests_total`, `http_server_duration_seconds_bucket`, `messenger_jobs_total`, `messenger_job_duration_seconds_bucket`, глубина/возраст очереди, пул БД, busy/capacity/consumers | `scripts/probe_signals.py` |
| Лог и трасса одного upload | Loki `job.ready` и Tempo по тому же `trace_id` | лог `attempt: 2` и трасса ниже | `evidence/retry-trace.json` |
| Дашборд из Git | `GET /api/dashboards/uid/messenger-overview` | uid `messenger-overview`, Grafana 11.5.2 | provisioning в `infra/grafana` |
| p50/p95/p99 из histogram | панели дашборда, `histogram_quantile` по сумме bucket | не среднее и не среднее p99 реплик | `infra/grafana/dashboards/messenger.json` |
| W3C API → broker → worker, retry, S3/DB | один upload с `process_fail_remaining=1` | см. цепочку | `evidence/retry-trace.json` |
| SLI/SLO и burn rate | правила Prometheus | семь alert rules загружены | `infra/prometheus/rules.yml` |
| Короткий всплеск не открывает fast burn | `scripts/slo_experiment.py` | pending, не firing | `evidence/slo-track2.json` |
| Длинная деградация | тот же прогон | fast burn firing через 51.6 с, resolved через 70.6 с | `evidence/slo-track2.json` |
| Остановка worker | `scripts/incident_followup.py` | consumers firing 75.5 с, queue lag 105.7 с, оба resolved за 20.1 с | `evidence/incidents.json` |
| Остановка Tempo | Tempo stop 40 с | 76× HTTP 200, failed spans 9→24, очередь 22, RAM collector 68.8 MiB / 320 MiB | `evidence/incidents.json` |
| Сохранность | публичный persistence через `scripts/restart.sh` | PASS, сессия и вложение на месте | — |
| Отказ одной реплики | публичный failover через `scripts/stop-one.sh` | 2 instance id до отказа, 77 успешных записей, 0 ошибок, восстановление 2.094 с | — |
| Нагрузка | `python tests/load.py --duration 15 --concurrency 2` | 1247 успехов, 0 ошибок, 82.7 rps, p50 31 мс, p95/p99 47 мс | `evidence/load.json` |
Цепочка одного upload, trace `cf5025ad9d9a2a248da8335a0c6caee2`:
1. `POST /api/v1/chats/{chat_id}/attachments` — корень.
2. `attachment.process publish`, parent = POST.
3. Два `attachment.process consume` с одним и тем же parent = publish. Первый — внедрённый transient (`job.retry`, attempt 1). Второй — sibling, attempt 2, `job.ready`.
4. У второго consume дети `s3.get`, два `s3.put` и `db.transaction`. У POST свои `db.transaction` и `s3.put` staging.
Перцентили на дашборде считаются как `histogram_quantile` от `sum by (le)` rate bucket. p99 реплик не усредняется: сначала складываются bucket, потом берётся квантиль.
## SLI / SLO
SLI API: доля ответов бизнес-маршрутов, которые не 5xx. Знаменатель — все бизнес-запросы. `/health/*` и несовпавший маршрут исключены. 4xx не ошибка SLI. SLO: 99% за скользящие окна burn rate (бюджет 1%).
- Быстрое сжигание: и 1 мин, и 5 мин строго выше 14.4% дольше 30 с, при трафике больше 0.2 rps.
- Медленное: и 5 мин, и 15 мин выше 6% дольше 1 мин.
- Дополнительно: error rate 5 мин выше 5% дольше 1 мин; возраст старейшей job больше 30 с дольше 1 мин; число consumers по данным API равно 0 дольше 1 мин; p95 времени до ready выше 10 с.
Доставка наружу не настраивалась. Состояние — локальные ряды `ALERTS`.
## Трек 2
Гипотеза: при уже идущем успешном трафике всплеск около 10 с поднимает минутное окно и не поднимает пятиминутное выше 14.4%, поэтому fast burn не становится firing. Непрерывные 5xx дольше примерно 45 с поднимают оба коротких окна, и fast burn зажигается. Остановленный worker виден по возрасту очереди и нулю consumers, а не по error rate API. Остановленный Tempo не мешает принять сообщения, exporter упирается в очередь и лимит памяти.
Методика на этом хосте (16 ГБ RAM, лимиты контейнеров в `compose.yaml`): закрытый цикл `GET /api/v1/chats` около 2 rps. Прогрев 90 с дал 180 ответов 200 и ноль alerts. Затем 10 с с `http_error_ratio=1`: 20 ответов 500. Сразу после этого `ApiHighErrorRate` и `ApiErrorBudgetSlowBurn` были только pending, `ApiErrorBudgetFastBurn` не появился. Дальше те же 100% ошибок: fast burn, high error rate и slow burn стали firing через 51.6 с (104 ответа 500). После снятия fault fast burn ушёл через 70.6 с; high и slow оставались firing и к началу следующего прогона (около двух минут спустя) уже были inactive.
Ограничения измерения. Короткий всплеск и длинный прогон шли подряд, поэтому ошибки всплеска ещё лежали в пятиминутном окне и ускорили детект длинной деградации относительно «холодного» старта. p99 нагрузки 15 с на 2 потоках совпал с p95 (47 мс): выборка короткая, это закрытый цикл, не открытый поток. Время resolved для slow burn снято по факту «уже нет» к 21:49:48 UTC, без секундомера. `AttachmentReadyLatencyHigh` стал firing из-за job, которая ждала остановленный worker: это следствие того же инцидента, гистограмма 15 мин ещё держит медленное завершение.
## Два инцидента
Остановка worker. Сразу после stop API показывал `messenger_worker_consumers = 0` и растущий возраст очереди. `WorkerConsumersZero` firing на 75.5 с, `QueueLagHigh` на 105.7 с при возрасте около 98 с. После start оба alert исчезли за 20.1 с. Runbook: `docs/runbooks/queue-lag.md`.
Остановка Tempo на 40 с. Бизнес-GET: 76 ответов 200, ошибок нет. `otelcol_exporter_send_failed_spans` вырос с 9 до 24. Размер очереди exporter дошёл до 22 при лимите 200. Память collector 68.8 MiB при лимите контейнера 320 MiB и memory limiter 192 MiB. Сообщения не терялись. Runbook: `docs/runbooks/telemetry-backend.md`.
Как отличить медленную БД от медленного handler: `db_slow_ms` спит внутри спана `db.transaction`, `handler_slow_ms` спит в серверном спане и вне `db.transaction`.
## Ограничения
Публичные `tests/resilience.py` на этом Windows запускают `.sh` как Win32 и получают `WinError 193`. Сами хуки прогнаны тем же тестом через Git Bash. На Linux `make test-persistence` и `make test-failover` вызывают скрипты напрямую.
Чтобы вообще скачать образы, с диска C: были удалены неиспользуемые образы других локальных проектов. Их тома не удалялись. Образы этих проектов при следующем запуске нужно скачать снова.
SeaweedFS выбран вместо MinIO: образы `minio/minio` с Docker Hub в этой среде не скачиваются. Контракт разрешает SeaweedFS.