Files
2026-11-18 21:37:25 +03:00

16 KiB
Raw Permalink Blame History

Лабораторная 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.