forked from mtusi2026/mtusi2026lab6
docs: document Lab 6 results
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user