122 lines
14 KiB
Markdown
122 lines
14 KiB
Markdown
# Отчёт — лабораторная 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.
|