diff --git a/REPORT.md b/REPORT.md index b97ae42..38511cb 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,257 @@ # Отчёт — лабораторная 6 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Пластинин Денис, БВТ2303 +- Целевая оценка: 5 +- Выбранный трек: 2 — SLO и обнаружение инцидентов ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требуются 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`. -## Архитектура и решения +```bash +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 +``` -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab5, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Интерфейсы локального стенда: + +- 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: + +```bash +docker compose --env-file .env down +``` + +Намеренное удаление всех учебных данных выполняется отдельно: + +```bash +docker compose --env-file .env down -v +``` + +## Архитектура + +Возможности Lab 5 сохранены: две API-реплики за Nginx, PostgreSQL как источник бизнес-состояния, Valkey для сессий, MinIO/S3 для изображений, transactional outbox, Redis Streams и отдельный worker. Lab 6 добавляет единый telemetry pipeline. + +```text +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 секунд. Недоступность telemetry backend поэтому не блокирует бизнес-запросы и не вызывает неограниченный рост памяти. + +Prometheus, Loki, Tempo и Grafana используют отдельные volumes. Retention локальных logs/traces — 7 суток; Prometheus хранит 7 суток. Collector является транспортом и процессором, а не долговременным хранилищем. + +### Resource attributes и среды + +Каждый процесс объявляет: + +```text +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 показывает цепочку: + +```text +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 | +| Jobs processed / failed | `messenger_attachment_worker_jobs_total{job_type,result}`, jobs | +| 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` не считаются отказом сервиса. + +```text +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 — доля завершённых attachment jobs, достигших `ready` не позднее 30 секунд. `failed` и ready позже 30 секунд являются bad events. + +```text +bad = failed + ready later than 30s +total = ready + failed +SLI = 1 - bad / total +SLO = 99% за 30 дней +error budget = 1% +``` + +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`. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий | Команда/сценарий | Проверяемый результат | Доказательство | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| 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-*/` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Runtime evidence создаётся локально и игнорируется Git до проверки содержимого. В нём нет session tokens, cookies, passwords, payload envelope и пользовательских текстов. Для публикации выбираются только небольшие агрегированные JSON. -## Эксперименты и отказы +## Методика экспериментов -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +`scripts/lab6-traffic.py` создаёт изолированных синтетических пользователей и чат, затем генерирует сообщения и PNG-вложения. Нагрузка closed-loop, concurrency и duration фиксируются в JSON; HTTP status и p50/p95/p99 рассчитываются клиентом только как вспомогательные данные. Серверные SLO используют Prometheus histograms. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +Полный сценарий: -## Ограничения и следующие шаги +```bash +make test-lab6 +``` -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Он выполняет: + +1. baseline mixed load; +2. короткую остановку worker; +3. краткую недоступность PostgreSQL под message traffic; +4. длительную остановку worker; +5. остановку Loki и Tempo под mixed traffic; +6. проверку 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-01` сохранён локально в `evidence/runtime/lab6-20261101T135321Z` и прошёл schema validation без ошибок. Обезличенная сводка включена в `evidence/lab6-results.json`. Время обнаружения является верхней границей: сценарий опрашивает alert после выдержки заданной длительности отказа. + +| Инцидент | Наблюдение | Обнаружение | Восстановление | +| --- | --- | ---: | ---: | +| Worker, короткий | `AttachmentWorkerUnavailable` firing, очередь затем обработана | не более 76 с | alert resolved через 15 с, полное наблюдение 36 с | +| PostgreSQL | operational 5xx и fast burn-rate firing, 4 DB error traces связаны с логами | не более 76 с | operational alert resolved через 127 с, API стабилен через 148 с | +| Worker, длительный | oldest queued age рос; backlog, fast и slow burn alerts firing | не более 180 с | alert resolved через 15 с, backlog обработан за 65 с | +| Loki и Tempo | Collector использовал ограниченные retry/queue, бизнес-путь продолжил работу | 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.