16 KiB
Лабораторная 6: наблюдаемость мессенджера
Целевая оценка — 5, трек 1: цена наблюдаемости. Автор и группа заполняются студентом перед сдачей; commit/PR — после публикации. README задания, обязательный API и публичные проверки сохранены.
Запуск из чистого clone
Требуются Docker Engine, Compose v2 либо docker-compose, Python 3.9+.
Для локальных Go-тестов требуется Go не старее версии в go.mod.
Соседняя папка lab5 после переноса не нужна.
make up
make wait
make check
make test
make test-own
Полная проверка OpenAPI требует отдельной Python-зависимости:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make check validate PYTHON=.venv/bin/python
Bootstrap создаёт случайные credentials в secrets/, goose применяет migrations,
S3 bootstrap создаёт приватный bucket и ограниченного пользователя.
Повторный запуск сохраняет существующие credentials и данные.
Секреты передаются через /run/secrets; каталог исключён из Git и Docker context.
scripts/compose.sh использует --env-file /dev/null: локальный файл окружения не требуется.
| Интерфейс | Адрес |
|---|---|
| API / Swagger | http://localhost:18086 / http://localhost:18086/swagger/ |
| Grafana dashboard | http://localhost:13000/d/messenger/messenger-observability |
| Prometheus alerts | http://localhost:19090/alerts |
| Loki HTTP | http://localhost:13100 |
| Tempo HTTP | http://localhost:13200 |
Порты опубликованы только на loopback. OTLP, DB, Redis и S3 доступны внутри сети Compose.
Grafana разрешает локальный анонимный просмотр. Datasources/dashboard загружаются автоматически.
Для отдельного импорта используйте infra/grafana/dashboards/messenger.json.
Безопасная остановка: make down; named volumes сохраняются.
Намеренное удаление всех учебных данных lab6: ./scripts/compose.sh down -v.
Не удаляйте secrets/ при сохранённых volumes: credentials перестанут соответствовать данным.
Что перенесено и добавлено
Из lab5 перенесены cmd/, dto/, internal/, migrations 001–010, Dockerfile приложения/MinIO,
конфигурации S3, Redis AOF, HAProxy и мигратора. Сохранены сессии, две API-реплики,
идемпотентность сообщений, приватные вложения, durable Redis Streams, отдельный worker,
transactional outbox, lease/fence и ограниченные retry.
HTTP 202 означает устойчивый приём задания, обработка происходит в worker.
Добавлены SDK traces/metrics/logs, Collector, три хранилища и Grafana. Migration011 сохраняет W3C traceparent/tracestate в job вместе с durable acceptance. Publisher создаёт producer span и передаёт контекст через Redis Streams. Worker создаёт consumer span; retry продолжает исходную причинную связь. PostgreSQL spans содержат операцию, но не SQL, аргументы или строку подключения.
flowchart LR
Client --> HAProxy --> API[API x2]
API --> DB[(PostgreSQL)]
API --> S3[(MinIO)]
API --> Broker[(Redis Streams)]
Broker --> Worker
Worker --> DB
Worker --> S3
API -->|OTLP| Collector
Worker -->|OTLP| Collector
Collector --> Prometheus
Collector --> Loki
Collector --> Tempo
Prometheus --> Grafana
Loki --> Grafana
Tempo --> Grafana
PostgreSQL — источник истины бизнес-состояния. S3 хранит bytes изображений. Redis хранит сессии и очередь; AOF обеспечивает её устойчивость. Collector принимает/обрабатывает/пересылает сигналы, но не хранит историю долговременно. Prometheus хранит временные ряды, Loki — логи, Tempo — spans. Grafana запрашивает эти источники.
Компоненты и хранение
| Service | Версия | Volume / готовность |
|---|---|---|
| api x2, worker | Go из Dockerfile, mtusi-messenger:lab6 |
API /health/live, /health/ready; worker отдельно |
| gateway | HAProxy 3.2.4-alpine | Без состояния; проверяет readiness обеих реплик |
| postgres | 17.6-alpine3.22 | postgres_data; pg_isready |
| redis | 7.4.5-alpine3.21 | redis_data; redis-cli ping |
| minio | RELEASE.2025-09-07T16-13-09Z | s3_data; /minio/health/live |
| s3_bootstrap | mc RELEASE.2025-08-13T08-35-41Z | Идемпотентный bootstrap; exit0 |
| migrations | goose 3.27.1 | Журнал в PostgreSQL; exit0 |
| collector | contrib 0.137.0 | Ограниченные очереди RAM; метрики :8888 |
| prometheus | 3.6.0 | prometheus_data; /-/ready; retention7d/1GB |
| loki | 3.5.5 | loki_data; /ready; retention7d |
| tempo | 2.8.2 | tempo_data, WAL/blocks; /ready; retention7d |
| grafana | 12.2.0 | grafana_data; /api/health; provisioning из Git |
Все компоненты находятся в отдельной сети проекта mtusi2026lab6.
Лимиты CPU/RAM заданы в compose.yaml. Внешние хранилища или готовый сервер не используются.
OTel Go traces/metrics 1.38.0, logs 0.14.0. Имена инструментов зафиксированы явно.
Schema URL не заявляется: это собственные сигналы контракта, а не полная реализация semantic conventions.
Сигналы и единицы
| Требование | Метрика | Единица / агрегация |
|---|---|---|
| HTTP throughput/errors | messenger_http_requests_total | count; labels method/route/status_class |
| HTTP latency | messenger_http_duration_seconds_bucket | seconds; histogram_quantile после sum buckets реплик |
| Jobs outcomes | messenger_jobs_total | count; job_type/outcome |
| Worker duration | messenger_job_duration_seconds_bucket | seconds на попытку |
| End-to-end ready | messenger_attachment_ready_seconds_bucket | seconds от durable создания job, включая queue/retry |
| Queue | messenger_queue_depth / messenger_queue_oldest_age_seconds | jobs/seconds; max повторных наблюдений общей очереди |
| DB pool | messenger_db_pool_used / messenger_db_pool_waiting / messenger_db_pool_max | connections / acquisition calls / connections |
| Worker saturation | messenger_worker_busy / messenger_worker_capacity | active jobs / concurrency; отношение busy/capacity |
| Go runtime | messenger_process_memory_bytes / messenger_process_cpu_seconds_total | Sys bytes / cumulative CPU seconds |
| Контейнеры | docker stats в research JSON | cgroup memory / CPU percent |
Histogram buckets: .005,.01,.025,.05,.1,.25,.5,1,2,5,10,30,60,120 секунд. p50/p95/p99 вычисляются из объединённых buckets, а не из средних или percentile каждой реплики. Resource attributes: service.name=messenger-api/messenger-worker, service.version=lab6, service.instance.id=hostname, deployment.environment.name=lab. Логи содержат timestamp/severity/service.name/event/trace_id/span_id. X-Request-Id связывает HTTP-ошибку с логом; X-Trace-Id позволяет открыть трассу. UUID, request ID, raw URL и filename отсутствуют в metric labels. Authorization, токены, тела сообщений и изображений не экспортируются.
SLI/SLO и alerts
Учебный SLI API: 1 - sum(rate(messenger_http_requests_total{status_class="5xx"}[5m])) / sum(rate(messenger_http_requests_total[5m])).
SLO: не менее 99% бизнес-запросов без 5xx за скользящие 5 минут, при наличии трафика.
Health/Swagger исключены. Неверный пароль не считается серверным отказом;4xx остаются в знаменателе.
SLI attachments: доля ready за 10 секунд по end-to-end histogram, дополнительно к возрасту незавершённой очереди.
APIHighErrorRate: доля 5xx >5% за 1m, for: 5s. QueueLagGrowing: oldest age>10s и depth>0, for: 5s. Пороги сокращены для учебного опыта; трек 2 с burn-rate alerts не заявляется. Правила: infra/prometheus/alerts.yaml; диагностика: RUNBOOK.md. Внешняя доставка не требуется; проверяется локальное firing/resolved.
Backpressure telemetry
SDK traces/logs: bounded queue512, batch128, export timeout2s; metrics экспортируется каждые 5s. Collector: memory limiter128MiB/spike32MiB, batch256/max512, exporter queue256, два consumers для каждого backend, retry максимум 20s, cgroup192MiB. Длительный отказ приводит к потерям telemetry. Бизнес-запросы не ожидают записи telemetry в backend. Очереди в памяти Collector теряются при аварийном завершении.
Проверки, отказы и исследование
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
./scripts/compose.sh start api
python3 scripts/observability_faults.py
python3 scripts/observability_backend.py
python3 scripts/observability_experiment.py
python3 scripts/summarize_observability.py
python3 scripts/verify_observability.py
Сценарии запускайте последовательно; после failover восстановите две реплики. Fault suite останавливает worker, создаёт backlog, показывает firing/resolved, проверяет retry при недоступном S3, блокирует PostgreSQL и проверяет API при выключенном Tempo. Исторические результаты lab5 не используются как доказательства lab6. Команды и фактические результаты: evidence/lab6-validation.txt, evidence/lab6-smoke.txt, evidence/lab6-faults.json, evidence/lab6-research.json. Исследование: RESEARCH.md.
Доказательства критериев
| Критерий README | Проверка / результат | Доказательство |
|---|---|---|
| Минимум lab5, две API-реплики и отдельный worker | Публичный smoke PASS; PostgreSQL/Redis/MinIO и очередь работают | evidence/lab6-smoke.txt; compose.yaml |
| Сохранность после restart | Данные, оригинал вложения и прежняя сессия сохранены | evidence/lab6-persistence.txt; evidence/lab6-container-events.txt |
| Отказ API-реплики | 117 успешных записей, 4 неудачные попытки, восстановление за 3,382s; одна реплика остановлена и затем восстановлена | evidence/lab6-failover.txt; evidence/lab6-failover-containers.json |
| Collector, три хранилища, Grafana и persistent history | Пять scrape targets UP; dashboard provisioned, 15 панелей, 18 запросов выполняются | evidence/lab6-provisioning.json; infra/ |
| OTLP API/worker: counters, histograms, logs и traces | Обязательные сигналы найдены по реальным именам; сохранены server/producer/consumer spans и связанные логи | evidence/lab6-provisioning.json; evidence/trace-.json; evidence/logs-.json |
| Низкая кардинальность и безопасная telemetry | Проверены labels реальных series; unit tests не допускают SQL/аргументы/тело/Authorization в spans | evidence/lab6-provisioning.json; evidence/lab6-validation.txt; internal/observability/telemetry_test.go |
| W3C API → broker → worker → S3/DB, включая retry | В одной трассе upload видны 4 producer/consumer попытки и завершение | evidence/lab6-incidents-summary.json; INCIDENTS.md |
| p50/p95/p99, queue lag, pool, saturation и CPU/RAM | Histogram queries объединяют buckets реплик; gauges и process/container ресурсы измерены | infra/grafana/dashboards/messenger.json; evidence/lab6-provisioning.json; evidence/lab6-research.json |
| SLI/SLO и два alerts | Определены выше; оба alerts firing, затем resolved | infra/prometheus/alerts.yaml; evidence/lab6-faults.json |
| Два инцидента и диагностика | Worker/S3 и DB lock локализованы по метрикам, логам и трассам | INCIDENTS.md; RUNBOOK.md; evidence/lab6-incident-metrics.json |
| Ограниченное поведение при отказе backend | 35/35 записей успешны; queue максимум 27/256, затем 0; OOM нет; 3 request traces отсутствуют | evidence/lab6-backend-outage.json |
| Законченный трек 1 на 5 | Off/100%/10%/50%, два повтора, 960 запросов, 48 изображений ready; latency, CPU/RAM, ingest и потери; 50% проверено | RESEARCH.md; evidence/lab6-research.json; evidence/lab6-research.csv |
Полный fault suite завершился PASS. В начале проверки Tempo получил OOM при лимите 256MiB. Лимит исправлен на 512MiB с GOMEMLIMIT=320MiB; после исправления трассы и логи получены, отказы повторены успешно. Подробности и начальные неуспешные журналы сохранены в INCIDENTS.md и evidence/.
Ограничения и источники
Один host и единственные DB/broker/S3 не обеспечивают HA всего стенда. Research измеряет выбранный небольшой профиль, а не предельную пропускную способность. Head sampling может потерять ошибку или редкий медленный запрос: исход неизвестен при принятии решения. При снижении sampling traces метрики и логи продолжают экспортироваться. SDK off оставляет wrapper-код и stdout: измеряется дополнительная стоимость OTLP, не всей инструментации. Waiting учитывает текущие acquisition calls, включая немедленную выдачу соединения. Go Sys — зарезервированная runtime память, не RSS. Cgroup memory измеряется отдельно. Ready histogram содержит завершённые jobs; backlog контролируется отдельной метрикой.
Источники: документация OTel Go/Collector, Prometheus histograms, Grafana provisioning, Loki OTLP ingestion и Tempo configuration; первичные ссылки — в README. Основа — соседний проект lab5. Реализация и проверки выполнены с помощью O3 Agent Codex.