Files
mtusi2026lab6/REPORT.md

30 KiB
Raw Permalink Blame History

Отчёт — лабораторная 6

  • Автор, группа: Савельев Иван, БВТ2304.
  • Целевая оценка: 5, трек 2 — SLO и обнаружение инцидентов. Реализованы уровни 3 и 4.
  • Основа: готовая lab5, включая асинхронный pipeline и все её проверки на 4. Исторический отчёт — 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. Интернет нужен для первой установки зависимостей и загрузки закреплённых образов. Все команды из корня:

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: локальный 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 генерируются заново.
# Весь минимум 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 и затем выключает.

Архитектура и версии

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 содержит 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.

# 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 и логи показывают реальную цепочку 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. Доставка наружу не нужна; firing/inactive (resolved) наблюдаются через Prometheus API и панель ALERTS. Runbook содержит запросы и порядок диагностики другим студентом.

Эксперимент трека 2 и разбор инцидентов

Гипотеза, заранее заданная методика, нагрузка и ограничения — 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.

Фаза Запросы / 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 с сохранением состояния.

Первичные источники