docs: document Lab 6 results

This commit is contained in:
2026-11-01 17:06:39 +03:00
parent 441b752257
commit 0b237618c0
+240 -20
View File
@@ -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.