Files
mtusi2026lab6/REPORT.md

222 lines
30 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
- Автор, группа: Савельев Иван, БВТ2304.
- Целевая оценка: **5**, трек 2 — **SLO и обнаружение инцидентов**. Реализованы уровни 3 и 4.
- Основа: готовая lab5, включая асинхронный pipeline и все её проверки на 4. Исторический отчёт — [REPORT.lab5.md](REPORT.lab5.md).
- Commit/PR: рабочее дерево поверх исходного skeleton; публикация выполняется отдельно. Проверенные файлы перечислены с SHA-256 в `evidence/lab6-source-manifest.json`.
- Помощь ИИ: Codex использован для переноса, реализации, проверок и подготовки отчёта. Evidence получен реальными запусками Docker и запросами к хранилищам.
- Проверено 19.11.2026 на macOS arm64, Docker Desktop 29.0.1: 10 CPU, 8217448448 bytes RAM (≈7.65 GiB) доступны Docker VM. Это учебный стенд на одном host.
## Запуск из чистого clone
Нужны Docker Engine/Desktop с Compose v2, Python 3.11, Bash и make. Интернет нужен для первой установки зависимостей и загрузки закреплённых образов. Все команды из корня:
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make check validate PYTHON=.venv/bin/python
./scripts/start.sh
./scripts/check.sh
```
`start.sh` создаёт локальные `.env` и `secrets/`, собирает приложение, применяет миграции и bootstrap приватного S3 bucket, поднимает API/worker и наблюдаемость. Затем ожидает две API-реплики через LB, scrape Collector, все хранилища и provisioning Grafana. Ручной импорт dashboard не нужен.
- API: http://localhost:8080; health: `/health/live`, `/health/ready`.
- [Grafana dashboard](http://localhost:3000/d/messenger-lab6): локальный anonymous Viewer; пароли приложения в Grafana не вводятся.
- Порты меняются через `HOST_PORT` и `GRAFANA_PORT` в `.env`; для API-тестов передать соответствующий `BASE_URL`. Драйвер наблюдаемости определяет опубликованный порт Grafana через Compose; можно задать `GRAFANA_URL`.
- Compose project `mtusi-lab6`, приложение `mtusi-messenger:lab6`; volumes отделены от lab5. Локальные `.env`/secrets не входят в Git и Docker build context. В новом clone credentials генерируются заново.
```sh
# Весь минимум lab5 + API/telemetry/persistence + исследование lab6:
./scripts/check-lab6.sh
# Только исследование трека 2 на уже запущенном синтетическом стенде (~11 минут):
./scripts/research.sh
# Остановка с сохранением данных / повторный запуск:
./scripts/stop.sh
./scripts/start.sh
# Перезапуск процессов и хранилищ без удаления volumes:
./scripts/restart.sh
# Только намеренное удаление данных СВОЕГО учебного Compose project:
docker compose down --volumes
```
Полный script сначала проверяет lab5 в отдельном временном project на свободных портах и новых volumes, затем удаляет только этот временный стенд. Исследование lab6 использует текущий локальный синтетический стенд и намеренно создаёт ограниченные отказы. Стандартная работа приложения не требует `ENABLE_FAULT_INJECTION`; проверка retry временно включает его только для worker и затем выключает.
## Архитектура и версии
```text
HTTP → HAProxy → API ×2 → PostgreSQL / Valkey sessions / private S3
└ durable metadata + job + outbox (W3C context)
→ publisher → Valkey Streams → worker ×2
→ S3 GET/PUT → DB ready → ACK
API / publisher / worker → OTLP HTTP → Collector
├ Prometheus exporter → Prometheus ← scrape
├ OTLP HTTP → Loki
└ OTLP gRPC → Tempo
↑
Grafana: metrics / logs / traces
```
API, ACL, сессии, идемпотентность, ограничения изображений, at-least-once/retry/replay и очистка staging перенесены из lab5. Обязательные контракты и публичные tests сохранены. Миграции 001–004 не изменены; 005 добавляет сохранённый trace context и `ready_at`. Новые поля не меняют бизнес-API. Источник истины — PostgreSQL; ACK по-прежнему выполняется после устойчивого результата/retry.
| Роль / service | Закреплённая версия | Persistence / readiness / credentials |
| --- | --- | --- |
| API / worker / publisher / cleanup / migrate | Python 3.11.15, FastAPI 0.142.4; image `mtusi-messenger:lab6` | Исходники и lock версий в requirements; API `/health/ready`, worker читает broker; отдельный migrate проверяет checksum. Docker secrets, non-root UID 10001 |
| PostgreSQL / postgres | 17.6-bookworm | `postgres_data`, pg_isready; password/DSN из secrets |
| Сессии / valkey | 8.1.3 | `valkey_data`, AOF fsync always; ping; только внутренняя сеть |
| Очередь / broker | Valkey 8.1.3 | `broker_data`, AOF fsync always; authenticated ping; password/URL из secrets |
| S3 / s3, s3-storage | SeaweedFS 3.85 с digest | `s3_data`, внутренний TCP/HTTP readiness; private bucket и service account создаёт bootstrap; secrets |
| LB / lb | HAProxy 3.2.6-alpine | `/health/ready`; только `127.0.0.1:8080`; API-порты напрямую не опубликованы |
| Collector / otel-collector | contrib 0.123.0 | Config `infra/otel/collector.yaml`, health 13133 и self metrics 8888 внутри сети; долговременной БД не является |
| Метрики / prometheus | 3.4.1 | `prometheus_data`, retention 7d, scrape/evaluation 5s; rules в Git |
| Логи / loki | 3.5.1 | `loki_data`, TSDB v13/filesystem, retention 7d, native OTLP со structured metadata |
| Трассы / tempo | 2.8.1 | `tempo_data`, WAL + local blocks, retention 7d; OTLP receiver только внутри сети |
| Grafana / grafana | 12.0.2 | `grafana_data`, `/api/health`; 3 datasources + dashboard provisioned из Git; localhost:3000, Viewer |
Grafana запрашивает хранилища, сама не хранит три сигнала. Collector принимает/буферизует/экспортирует, долгую историю хранят backends. У всех контейнеров заданы CPU/RAM limits; точные значения, volumes и опубликованные порты — `lab6-runtime.json`. Collector: 1 CPU/256 MiB; Prometheus/Loki/Grafana: по 1 CPU/384 MiB; Tempo: 1 CPU/512 MiB с GOMEMLIMIT 384 MiB. Приложение сохранило ограничения lab5.
SDK/API/exporters OTel **1.45.1**, semantic conventions **0.66b1**; полный список зависимостей закреплён в `requirements.txt`. Используются явные span/metric имена, а не автосбор SQL/HTTP headers. Встроенная автоматическая telemetry FastAPI отключена: один SDK и один набор инструментов без дублирования сигналов. Counter series для известных маршрутов и status classes инициализированы нулём до первого scrape: короткий первый всплеск ошибок не теряется из rate из-за отсутствия исходного нулевого sample. Фиктивные запросы или histogram observations для этого не создаются.
`.env.example` соответствует настройкам: `DATABASE_URL_FILE`, `CACHE_URL_FILE`, S3 и `BROKER_URL_FILE` читают Docker secrets; worker concurrency/retry/lease/time/memory — перенесённые настройки pipeline; `OTEL_EXPORTER_OTLP_ENDPOINT` — общий Collector, protocol HTTP/protobuf. Resource `service.name` устанавливается отдельно для API, worker и publisher; `service.version=6.0.0`, instance — hostname:pid, environment — lab. `OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED=true` включает контроль очередей SDK. Перезапуск сохраняет volumes всех signal stores.
## Сигналы и запросы
[Dashboard JSON](infra/grafana/dashboards/messenger.json) содержит 19 панелей; datasources/provider рядом в `infra/grafana/provisioning/`. `lab6-dashboard-checks.json` подтверждает выполнение запросов ко всем трём источникам.
| Реальное имя в Prometheus | Тип / единицы / labels |
| --- | --- |
| `messenger_http_requests_total` | counter запросов; method, route template, status_class; health исключён |
| `messenger_http_duration_seconds_*` | histogram, секунды до response headers; те же labels |
| `messenger_job_attempts_total` | counter попыток; job_type, outcome (ready/retry/failed/error/duplicate/busy/obsolete/invalid) |
| `messenger_job_duration_seconds_*` | histogram длительности consumer attempt, секунды; job_type/outcome |
| `messenger_attachment_ready_duration_seconds_*` | histogram acceptance → ready успешных jobs, секунды; job_type |
| `messenger_queue_depth` / `messenger_queue_oldest_age_seconds` | gauges: незавершённые durable jobs / возраст самой старой, секунды; queue=attachments |
| `messenger_db_pool` | gauge соединений; state=used/waiting |
| `messenger_worker_busy` / `messenger_worker_capacity` | gauges занятых/доступных worker процессов |
| `messenger_process_cpu_time_seconds_total` / `messenger_process_memory_bytes` | process CPU seconds / RSS bytes; группировка по service_name |
| `messenger_ready_deadlines_total` | durable cohort counter; outcome=good/bad, включая failed/stuck/late jobs |
`_bucket`, `_sum`, `_count` — части одного histogram. Resource labels добавляются Collector; технический instance ID нужен для суммирования процессов и различения перезапусков. User/chat/message/attachment/request IDs, raw URL, filename и текст labels не являются. Лимит экспирации неактивных metric series Collector — 30s.
```promql
# RPS (без health), ошибки 5xx / все business requests:
sum(rate(messenger_http_requests_total[1m]))
lab6:api_bad_ratio:1m
# p95 по всем API-репликам; для p50/p99 меняется quantile:
histogram_quantile(0.95,
sum by (le) (rate(messenger_http_duration_seconds_bucket[1m])))
max(messenger_queue_depth)
max(messenger_queue_oldest_age_seconds)
sum by (state, service_name) (messenger_db_pool)
sum(messenger_worker_busy) / sum(messenger_worker_capacity)
```
Buckets в секундах: .005, .01, .025, .05, .1, .25, .5, 1, 2, 5, 10, 20, **30**, 60, 120, 300, 600, +Inf. Percentiles считаются из суммарных buckets, не средних latency/p95 реплик. Backlog не подменяет processing duration. `s3.get_object` измеряет получение ответа S3; чтение stream входит в общий consumer span.
Лог — структурный JSON с timestamp, severity, service.name, event, trace_id/span_id; HTTP содержит также `request_id`, совпадающий с X-Request-Id. В ответе есть X-Trace-Id. Только job/attachment IDs разрешены в явных диагностических событиях для синтетических заданий; в labels их нет. Пароли, Authorization/session tokens, bodies, изображения, filenames/storage keys/signed URLs и SQL/params не собираются. Exception events с текстом/stack trace отключены; сохраняется только класс ошибки. Loki индексирует service/environment, instance — structured metadata.
W3C traceparent/tracestate сохраняются в job той же транзакцией, что metadata/outbox. Producer восстанавливает parent, инжектирует свой context в broker payload. Consumer извлекает его; retry сохраняет актуальный context для следующей публикации. После перезапуска процессов связь сохраняется. [Сохранённый trace с retry](evidence/lab6-trace-retry.json) и [логи](evidence/lab6-correlated-logs.json) показывают реальную цепочку API → producer → consumer → retry → producer → consumer → S3/DB. Sampling 100% для учебного стенда.
## SLI/SLO и alerts
- **API availability ≥99% за скользящий час**. Bad — instrumented business responses 5xx; denominator — все business requests, включая 4xx; health исключён. Неверный пароль не является серверной ошибкой. Нужны внешние probes для отказов LB/сети до API; в этот SLI они не входят.
- **Ready ≥95% за ≤30s, окно час**. Acceptance timestamp — `job.created_at` в durable metadata transaction; запись становится видна после COMMIT. По `ready_at` оценивается каждый cohort после истечения deadline. Позднее завершение, failed и незавершившееся задание считаются bad. Часовое окно относится к созревшим cohorts, acceptance сдвинута на 30s. В отличие от histogram только successful jobs, SLI не скрывает остановку worker.
Обоснование: 99% availability задаёт заметный бюджет серверных ошибок для учебного single-host стенда с единственной БД; это проверяемая цель, а не обещание production SLA. Для асинхронного изображения 30s оставляют запас на S3, ожидание публикации и краткий retry; минуты без обработки уже нарушают пользовательское ожидание. Цель 95% допускает редкие тяжёлые изображения/повторы, сохраняя чувствительность к остановке worker. При нашем постоянном профиле час содержит около 9000 HTTP requests и 1800 jobs: budgets — 90 ошибок и 90 просроченных jobs. Четыре ошибки короткого всплеска расходуют около 4.4% часового API budget, ниже порогов эскалации 20%/30%. Час выбран для воспроизводимого учебного исследования; production потребует отдельного обоснования периода и целей.
| Alert policy | Long / short window | Burn rate / порог API / ready | for / guards |
| --- | --- | --- | --- |
| Fast | 2m AND 30s | 6× / 6% / 30% bad | 15s; long ≥30 API / ≥5 jobs, short ≥2 события |
| Slow | 6m AND 1m | 3× / 3% / 15% bad | 30s; те же guards |
| APIHighErrorRate (сравнение) | 30s | >5% 5xx | 5s |
| AttachmentQueueLag | текущие age/depth | oldest >20s и depth >0 | 10s |
Fast и slow одновременно проверяют оба окна. Это учебный **1h SLO**: fast соответствует расходу 20% бюджета за 2m, slow — 30% за 6m (`burn × long_window / 1h`). Production окна из примера 30-дневного SLO не копируются механически. Guards снижают шум при малом числе событий. При нулевом denominator ratio — NaN, а не искусственные 0% ошибок/100% availability; отдельно проверяются scrape и трафик. Есть CollectorUnavailable warning.
Rules/условия/описания/for/runbook находятся в [alerts.yaml](infra/otel/alerts.yaml). Доставка наружу не нужна; firing/inactive (resolved) наблюдаются через Prometheus API и панель ALERTS. [Runbook](docs/runbook.md) содержит запросы и порядок диагностики другим студентом.
## Эксперимент трека 2 и разбор инцидентов
Гипотеза, заранее заданная методика, нагрузка и ограничения — [research/README.md](research/README.md). Один real-time прогон: 2 сообщения/s + 0.5 PNG/s, 16 max in-flight, без retries; baseline 120s, spike БД 4s, recovery 60s, lock messages 90s, recovery 100s, worker stopped 120s, recovery 120s. SQL-lock ограничен pg_sleep; worker восстанавливается в finally. Каждые 5s читаются сохранённые alert states/метрики. Исследование выполняется отдельно от полного lab5 regression, чтобы они не конкурировали за ресурсы.
Финальный прогон **19.11.2026, 18:26:14–18:36:34 МСК**, 619.4s. 1544 ответов, пропущенных arrivals: 0. p50/p95/p99 ниже рассчитаны по всем ответам, включая 5xx; successful RPS — только 2xx.
[Открыть этот интервал в Grafana](http://localhost:3000/d/messenger-lab6?from=1795101974987&to=1795102594377).
| Фаза | Запросы / 5xx | Successful RPS | p50 / p95 / p99, ms |
| --- | --- | --- | --- |
| Baseline | 301 / 0 | 2.51 | 16.6 / 31.3 / 35.2 |
| Короткий DB spike, 4s | 10 / 4 | 1.50 | 1670.7 / 2017.2 / 2017.2 |
| После короткого всплеска | 150 / 0 | 2.50 | 16.5 / 30.7 / 32.8 |
| Длительное ожидание DB, 90s | 225 / 176 | 0.54 | 2011.8 / 2022.5 / 2025.8 |
| После восстановления DB | 250 / 0 | 2.50 | 16.3 / 31.0 / 33.4 |
| Worker stopped, 120s | 300 / 0 | 2.50 | 16.2 / 31.3 / 35.5 |
| После восстановления worker | 300 / 0 | 2.50 | 13.1 / 30.7 / 35.3 |
| Alert | Detection после воздействия, s | Resolved после восстановления, s |
| --- | --- | --- |
| APIAvailabilityFastBurn | 40.2 | 35.1 |
| APIAvailabilitySlowBurn | 60.3 | 65.3 |
| APIHighErrorRate | 25.1 | 35.1 |
| AttachmentQueueLag | 45.2 | 30.1 |
| AttachmentReadyFastBurn | 95.5 | 45.2 |
| AttachmentReadySlowBurn | 131.6 | 75.3 |
Baseline: **0** firing alerts. Короткий реальный всплеск виден в сохранённой 30s error ratio (peak **6.37%**); burn alerts на него сработали **0** раз. Single-window comparator: **APIHighErrorRate**.
В исследовании false positive означает эскалацию короткого всплеска, заранее принятого допустимым для выбранной SLO policy; предупреждение APIHighErrorRate при этом корректно соответствует собственному порогу.
Все заявленные alerts наблюдались firing и затем inactive/resolved. Сохранённый worker trace подтверждает consumer спустя **94.3s** после upload, уже после восстановления worker.
| Процесс | Max 1m CPU rate, cores | Max RSS, MiB |
| --- | --- | --- |
| messenger-api | 0.149 | 603.75 |
| messenger-publisher | 0.012 | 147.05 |
| messenger-worker | 0.013 | 319.40 |
Это maxima точек с шагом 5s; CPU усреднён по минуте, RSS суммирован по процессам сервиса. Два consumer процесса worker показаны суммарно. Исходные samples, timestamps и все запросы без credentials сохранены в `lab6-slo-research.json`, ряды — в `lab6-slo-series.json`.
Причина деградации API локализуется по сохранённым наблюдениям: 5xx и HTTP latency растут, внутри server trace `postgresql.SELECT` занимает около 2s и заканчивается `_WaitTimeout`, тогда как acceptance и worker продолжаются. Это I/O ожидание PostgreSQL, а не искусственный sleep HTTP handler. Конкретные spans/durations — `lab6-db-incident-trace.json`, коррелированные request logs — `lab6-db-incident-logs.json`. Методика внедряет SQL lock, но по одному сохранённому timeout нельзя доказать именно блокировку вместо другой причины медленного ответа БД; этот предел диагностики явно учитывается.
При остановке worker acceptance/producer продолжаются, successful processing прекращается, capacity исчезает после истечения series, backlog/oldest age растут. В trace принятого upload до восстановления отсутствует consumer; после восстановления очередь дренируется, появляются S3/DB ready spans, но просроченные cohorts сохраняют bad исход. Это проверено по timestamps consumer в `lab6-worker-incident-trace.json` и связанным `lab6-worker-incident-logs.json`. Подробные ряды, CPU/RSS, pool и saturation — `lab6-slo-series.json`.
## Отказ telemetry backend и границы буферизации
Collector memory limiter: 192 MiB со spike 32 MiB, check 1s; hard container limit 256 MiB. Batch максимум 128 записей; отдельные exporter queues по 64 batch, 2 consumers, timeout 2s, retry максимум 15s. SDK trace/log queues по 256 записей, batch 64, фоновый export; metric export каждые 5s. Internal SDK queue capacity/size и Collector exporter metrics доступны в Prometheus. Бесконечной буферизации нет: при недоступном backend telemetry теряется, бизнес-запрос не ждёт экспорт.
Контролируемая остановка Loki проверена `student-tests/lab6_observability.py`: отказ около **51.39s**, **24/24 сообщения записаны**, история читается. После восстановления не найдены **6 из 24** соответствующих request logs; это фактически измеренная потеря по известным request IDs. RAM Collector в четырёх samples — **70.46–72.80 MiB** при limit 256 MiB, OOM=false. Отдельный счётчик failed exports вырос на 6; вообще его нельзя считать числом потерянных записей без проверки из-за retries. Raw результаты — `lab6-checks.json`. Grafana/Prometheus/Tempo сохраняли доступность; Loki после запуска снова принимает OTLP. Потери не маскируются debug exporter или stdout.
## Доказательства критериев
| Критерий | Команда/сценарий | Наблюдение / evidence |
| --- | --- | --- |
| Весь minimum lab5 и сохранённые переходы | `.venv/bin/python -u student-tests/lab5_pipeline.py` (тот же stage в check-lab6) | 17 групп PASS, включая outbox/worker crash, retry/replay, processing limits, cleanup, broker outage, persistence/failover; `lab6-lab5-regression.json/.txt` |
| Контракт, публичный smoke, свои API-тесты с telemetry | make check validate test; unittest discover | PASS и 39 tests OK; `lab6-api-checks.txt` |
| Collector + три persistent stores + Grafana | start.sh; readiness/provisioning | 2 API, CPU/RAM limits, localhost порты, volumes; `lab6-runtime.json` |
| Все обязательные metrics и dashboard queries | lab6_observability; check_dashboard | Реальные series и 19 панелей трёх источников; `lab6-checks.json`, `lab6-dashboard-checks.json` |
| API/worker logs + traces, W3C, retry → S3/DB | Deterministic transient worker failpoint | 59 связанных spans; `lab6-trace-retry.json`, `lab6-correlated-logs.json` |
| Отсутствие секретов/body/ID labels | Canary body/filename/password/token + metric label check | PASS; `lab6-checks.json` |
| Telemetry persistence | Restart всех постоянных контейнеров и запрос старого trace | IDs/volumes сохранены; `lab6-restart.json/.txt`, `lab6-telemetry-persistence.json` |
| Ограниченный отказ Loki | Stop/start Loki, 24 записи под отказом, memory samples | API работает, потери logs измерены, OOM=false; `lab6-checks.json/.txt` |
| SLO/rules и пограничные сценарии | promtool test rules | Spike/sustained/recovery/stalled/no traffic PASS; `lab6-promtool.txt` |
| Два инцидента + трек 2 | research.sh, runbook | Реальные firing/resolved, detection/recovery/false positives, stored observations; `lab6-slo-research.json/.txt`, `lab6-slo-series.json` |
## Ограничения и следующие шаги
Один host, единственные PostgreSQL/S3/telemetry stores: потеря host/disk/volumes не покрыта. Persistent volumes и проверенный restart не означают HA или backup. Срок хранения telemetry 7d; heap/queues ограничены, при длительном отказе часть наблюдений теряется. Нет внешней доставки alerts и внешнего black-box SLI LB/сети: это не требуется выбранным минимумом. Histogram HTTP измеряет время до headers; полный stream download отдельно не профилируется. Queue depth берётся из durable state БД, а не только broker.
Эксперимент короче часа и выполнен по одному live прогону каждого отказа на небольшой синтетической нагрузке. Он проверяет работу детектора и воспроизводимость диагностики; не доказывает часовую/месячную надёжность, предел RPS или универсальную частоту ложных срабатываний. Точность detection/resolution ограничена шагом 5s плюс SDK export/scrape. Часовые ratio при неполной истории — только доступная часть окна. CPU/RSS относятся к долгоживущим instrumented процессам; resize subprocess ограничен общим Docker limit и отдельные resource series не экспортирует. SQL cohort scan достаточен для учебного объёма; на больших объёмах понадобится incremental aggregation с сохранением состояния.
## Первичные источники
- [OpenTelemetry Collector configuration](https://opentelemetry.io/docs/collector/configuration/) и [internal telemetry](https://opentelemetry.io/docs/collector/internal-telemetry/).
- [OTel Python SDK](https://opentelemetry.io/docs/languages/python/) и [W3C Trace Context](https://www.w3.org/TR/trace-context/).
- [Native OTLP в Loki](https://grafana.com/docs/loki/latest/send-data/otel/).
- [Prometheus histograms](https://prometheus.io/docs/practices/histograms/) и [configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/).
- [Google SRE Workbook: multiwindow, multi-burn-rate alerts](https://sre.google/workbook/alerting-on-slos/) — принцип двух окон, адаптированный к явно выбранному учебному периоду.
- [Grafana provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/); compatibility TraceQL query проверена по source Grafana v12.0.2 и реальному Tempo search API.