Files
mtusi2026lab6-fork/REPORT.md
T
2026-11-19 18:40:32 +03:00

16 KiB
Raw Blame History

Отчёт — лабораторная 6

  • Автор, группа: Тюрина Александра, БВТ2304
  • Целевая оценка: 4
  • Commit/PR: solution/bvt2304-tyurina (после публикации)
  • Использованные источники: документация OpenTelemetry Go SDK, otelcol-contrib 0.112.0, Loki 3.2.0, Tempo 2.6.0, Prometheus 2.55.0, Grafana 11.2.0; помощь ИИ при отладке polling-скриптов и интерпретации /api/v1/rules

Запуск из чистого clone

# Prerequisites: Docker, docker compose, Go 1.22, make, python3 (для smoke)
git clone <repo> && cd mtusi2026lab6-fork

# 1. Локальный .env (без секретов в репозитории)
cp .env.example .env
# Переменные уже содержат безопасные dev-значения; реальные секреты
# (production JWT signing key и т.п.) не требуются для локальной разработки.

# 2. Сборка образов и старт всех сервисов
docker compose --env-file .env build
docker compose --env-file .env up -d

# 3. Ожидание готовности (~30s — healthcheck'и postgres, broker, otelcol, prometheus)
docker compose ps -a | grep -E "(unhealthy|starting)"   # должно быть пусто
sleep 15

# 4. Миграции применяются автоматически при старте worker (idempotent)
docker compose logs worker | grep -E "Skipping migration|Applying migration" | tail -5

# 5. Smoke-тест (проверяет публичный API + observability pipeline)
make test   # PASS: lab6 public API scenario

# 6. Доступ к observability UI
#   Grafana:    http://localhost:3000  (admin/admin)
#   Prometheus: http://localhost:9090
#   Tempo UI:   http://localhost:3200/api/search
#   Loki:       http://localhost:3100/ready

# Безопасная остановка (данные в volumes сохраняются)
docker compose --env-file .env down

# Намеренное удаление учебных данных (volumes + images)
docker compose --env-file .env down -v --rmi local

Версии runtime/образов: Go 1.22-alpine (builder), Alpine 3.20 (runtime), otel/opentelemetry-collector-contrib:0.112.0, prom/prometheus:v2.55.0, grafana/loki:3.2.0, grafana/tempo:2.6.0, grafana/grafana:11.2.0, postgres:16-alpine, redis:7-alpine.

Архитектура и решения

Схема процессов:

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  API (×2)   │ ───► │ Redis       │ ───► │ Worker (×N) │
│ :8080       │      │ Streams     │      │             │
└──────┬──────┘      └─────────────┘      └──────┬──────┘
       │                                         │
       ▼                                         ▼
   ┌───────┐  ┌─────┐  ┌─────┐              ┌───────┐  ┌─────┐
   │ Post  │  │ S3  │  │Redis│              │ Post  │  │ S3  │
   │ gres  │  │     │  │sess.│              │ gres  │  │     │
   └───────┘  └─────┘  └─────┘              └───────┘  └─────┘

┌──────────────────────────────────────────────────────────────┐
│  OpenTelemetry pipeline (observability)                      │
│  API/Worker ──(OTLP/gRPC)──► OTel Collector ─┬─► Prometheus │
│                                               ├─► Loki       │
│                                               └─► Tempo      │
│                                                     ▲        │
│                                                Grafana ◄─────┤
└──────────────────────────────────────────────────────────────┘

Источник истины: PostgreSQL (attachments, jobs, users, sessions). Redis — брокер задач (Streams) и сессии (уровень 5 опционально). S3 — хранение файлов (staging → variants).

Транзакционные границы:

  • API: создание attachment + job в одной транзакции (create_attachment_and_job)
  • Worker: claim_job (FOR UPDATE SKIP LOCKED + update) → обработка → complete_attachment (update + insert variants) в одной транзакции
  • Redis Streams: at-least-once через consumer groups + XACK только после успешного commit в БД

Что перенесено из lab5:

  • PostgreSQL, Redis, S3, структура приложения, миграции, обработчики API, job queue через Redis Streams
  • Graceful shutdown, healthchecks, idempotent worker

Что изменено/добавлено в lab6:

  • Инициализация OTel SDK в telemetry.Init() с graceful fallback при недоступном Collector
  • Автоматическая инструментация HTTP через otelhttp middleware
  • Структурированные логи через otelslog bridge с TraceContextHandler (автоматическое добавление trace_id/span_id в каждый лог)
  • W3C trace context propagation: API инжектит traceparent в Redis Streams через otel.GetTextMapPropagator().Inject(), worker извлекает через extractParent() и создаёт CONSUMER span
  • OTel Collector как центральная точка с memory_limiter + batch processors
  • Stack: Prometheus (метрики), Loki (логи), Tempo (трейсы), Grafana (визуализация + provisioning datasources/dashboards)
  • Alert rules: ApiHighErrorRate, AttachmentQueueLagHigh, WorkerStalled, ApiLatencyP95High

Соответствие .env.example:

  • OTEL_EXPORTER_OTLP_ENDPOINT=http://otelcol:4317 — Collector в Docker-сети
  • OTEL_SERVICE_NAME=messenger-api|worker — различение сервисов
  • OTEL_RESOURCE_ATTRIBUTES=service.name=...,service.version=lab6,deployment.environment=dev
  • DATABASE_URL, REDIS_URL, S3_* — connection strings (без секретов)

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab6 public API scenario evidence/smoke_output.txt
OTel Collector + Prometheus + Loki + Tempo + Grafana docker compose ps 5 сервисов healthy/started evidence/docker_compose_ps.txt
API отправляет OTLP (метрики) curl 'http://localhost:9090/api/v1/query?query=http_server_request_duration_seconds_count' Вектор с service_name="messenger-api", http_response_status_code, http_route evidence/metric_http_count.json
Worker отправляет OTLP (метрики) curl 'http://localhost:9090/api/v1/query?query=worker_in_flight_jobs' Вектор с service_name="messenger-worker" evidence/metric_in_flight.json
Trace ID в логах Loki query: {service_name=~".+"} | json | trace_id!="" Логи содержат "traceid":"e96eb...","spanid":"b4ec..." evidence/loki_trace_id.json
Dashboard JSON infra/grafana/dashboards/messenger-overview.json Файл существует, provisioning datasources/dashboards работает infra/grafana/dashboards/messenger-overview.json
Секреты не экспортируются otelcol/config.yaml + telemetry.go В resource attributes только service.name/version, deployment.environment, service.instance.id; никаких JWT/паролей infra/otelcol/config.yaml, src/internal/telemetry/telemetry.go
W3C trace context через брокер (ур. 4) Tempo API: GET /api/traces/{traceID} Один traceID содержит spans от messenger-api (SERVER) и messenger-worker (CONSUMER) с корректным parentSpanId evidence/trace_upload_to_worker.json, evidence/trace_upload_to_worker.txt
Alert rules (ур. 4) /api/v1/rules 4 правила загружены, health: ok evidence/prometheus_rules_state.json
Alert firing доказан (ур. 4) /api/v1/alerts + ALERTS{alertstate="firing"} ApiHighErrorRate: firing, activeAt=2026-11-19T15:20:36Z, value=245 evidence/alerts_firing.json, evidence/alerts_firing_history.json
Graceful degradation (ур. 4) docker compose stop tempo && sleep 5 && make test PASS, API продолжает работать без Tempo evidence/smoke_tempo_down.txt
Collector: memory_limiter + batch (ур. 4) infra/otelcol/config.yaml processors: [memory_limiter, batch] для всех pipeline (traces/metrics/logs) infra/otelcol/config.yaml

Эксперименты и отказы

Окружение: Apple MacBook Air (ARM), Docker Desktop 24.x, лимит памяти 8 GB на Docker, single-host deployment. Версии: OTel Collector 0.112.0, Loki 3.2.0, Tempo 2.6.0, Prometheus 2.55.0.

Объём данных: ~20 attachments, ~200 jobs, ~400 MB S3-объектов. Профиль нагрузки: синтетический (smoke + ручные curl-запросы).

Метрики из Prometheus:

  • HTTP p50: ~3 ms, p95: ~15 ms, p99: ~80 ms (нормальный режим)
  • Queue depth: 0 (норма) → до 16 при остановленном worker
  • Worker concurrency: 2 (по умолчанию), worker_in_flight_jobs ≤ 2

Эксперимент 1: Недоступность PostgreSQL → ApiHighErrorRate firing

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop postgres + 240 запросов с невалидным токеном за 240 сек Alert ApiHighErrorRate firing после for: 30s; 5xx ~100% Counter 5xx вырос до 245; alert перешёл в firing в 2026-11-19T15:20:36Z (подтверждено через ALERTS{alertstate="firing"}: 38 сэмплов за период 13:25:33–15:27:33 UTC) docker compose start postgres → API восстановлен за ~8 сек; alert перешёл в inactive после restart API (счётчик обнулился). Потеря данных: 0 (все успешные requests сохранены до отказа; во время отказа API возвращал 503 без побочных эффектов)

Ограничения измерения: Prometheus scrape interval 10s; alert for: 30s означает фактическое срабатывание через ~40-50s после начала отказа. Метрика http_server_request_duration_seconds_count — counter, не rate: alert срабатывает по абсолютному числу 5xx (>10), а не по проценту, что устраняет проблему разбавления healthcheck'ами.

Эксперимент 2: Недоступность Tempo → graceful degradation

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop tempo + sleep 5 + make test API продолжает работать; OTel Collector retry с backoff make test → PASS; в логах otelcol видны ошибки экспорта traces (connection refused), но не блокирующие pipeline; метрики и логи продолжают поступать в Prometheus/Loki docker compose start tempo → traces снова экспортируются за ~10 сек. Потеря данных: traces за 10-секундный простой не сохранены в Tempo, но доступны в Loki через trace_id

Подтверждённое улучшение: memory_limiter (check_interval=1s, limit_mib=192, spike_limit_mib=50) в otelcol/config.yaml защищает Collector от OOM при backlog'е; batch (timeout=5s, send_batch_size=512) агрегирует экспорт и снижает нагрузку на бэкенд.

Неподтверждённая гипотеза: влияние sampling (текущий AlwaysSample) на overhead при высокой нагрузке (>100 RPS). В учебной среде не удалось создать достаточную нагрузку без внешнего load-generator.

Ограничения и следующие шаги

Какие отказы выдерживаются:

  • ✅ Остановка Tempo/Loki: API работает, метрики продолжают собираться в Prometheus
  • ✅ Остановка PostgreSQL: API возвращает 503, данные не теряются, восстановление автоматическое
  • ✅ Остановка S3: worker retry с exponential backoff, DLQ для permanent failures
  • ✅ Остановка одного API replica: нагрузка распределяется через nginx/клиент (2 реплики)
  • ✅ Collector OOM protection: memory_limiter дропает данные при нехватке RAM, не падая

Какие отказы НЕ выдерживаются:

  • ❌ Остановка PostgreSQL + Redis одновременно: полная недоступность (нет shared-nothing)
  • ❌ Потеря volume postgres: данные теряются (нет backup/replication)
  • ❌ Остановка брокера (Redis): API не может публиковать jobs, worker не может читать — очередь недоступна
  • ❌ Остановка OTel Collector: приложение fallback'ит на stderr (работает), но наблюдаемость теряется

Что не реализовано (уровень 5):

  • Канареечные деплои / blue-green через nginx
  • Persistent storage для Tempo/Loki (сейчас ephemeral)
  • Distributed tracing через несколько реплик worker'а с sticky consumer groups
  • SLO burn rate alerts (только absolute threshold)

Учебные упрощения:

  • Alert rules используют absolute thresholds вместо rate-based (из-за разбавления healthcheck'ами)
  • Sampling = 100% (не подходит для production при высокой нагрузке)
  • Grafana provisioning без RBAC (один admin-пользователь)
  • Loki в single-binary mode (не distributed)

Подтверждённые улучшения:

  • Graceful degradation observability: остановка Tempo/Loki не влияет на business-логику
  • W3C trace propagation через broker: полная цепочка upload → process_job в Tempo
  • Structured logs с trace context: связь логов и трейсов через trace_id

Гипотезы для проверки:

  • Влияние OTel overhead на CPU/RAM при production-нагрузке (ожидается +3-5% CPU, +20-30 MB RAM на инстанс)
  • Эффективность sampling 10% для снижения затрат на Tempo storage при сохранении видимости ошибок (через ParentBasedSampler)
  • Horizontal scaling worker'ов: consumer group с XReadGroup теоретически поддерживает N потребителей, но не проверено под нагрузкой