Files
mtusi2026lab6/REPORT.md
T

15 KiB
Raw Blame History

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

  • Автор, группа: Кропивка Виктория, БВТ2303
  • Целевая оценка: 4 (уровень 3 + уровень 4)
  • Трек 5: не заявлен
  • Commit/PR: ветка solution/БВТ-23-Кропивка
  • Источники: OTel SDK 1.28.2, OTel Collector Contrib 0.111.0, Prometheus 2.55.1, Loki 3.2.1, Tempo 2.6.1, Grafana 11.3.1, FastAPI 0.115.0, psycopg 3.2.3, RabbitMQ 3.13. LLM-ассистент для черновиков; код проверен smoke + observability-сценариями.

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

Prerequisites: Docker 29.x + WSL2 (или Linux), Python 3.9+, Git.

  1. cp .env.example .env, заполнить POSTGRES_PASSWORD, S3_*, BROKER_*, GRAFANA_ADMIN_PASSWORD (любые локальные синтетические).
  2. docker compose --env-file .env up -d --build — все сервисы (17 контейнеров, включая телеметрию).
  3. Дождаться healthy: docker compose --env-file .env ps.
  4. make test — PASS.
  5. GRAFANA_PASS=$(grep '^GRAFANA_ADMIN_PASSWORD=' .env | cut -d= -f2-)
  6. Открыть http://localhost:3000 (admin / GRAFANA_PASS) → Dashboards → Messenger.

Архитектура

Топология (ЛР5 + ЛР6)

Клиент → HAProxy → 2× API → PostgreSQL (outbox + jobs.traceparent)
                      │         ↓
                      │      RabbitMQ → worker → S3 (staging/originals/variants)
                      │         ↓
                      │      Valkey (deny-list)
                      │
                      └──OTLP──→ OTel Collector ──┬──→ Prometheus (metrics)
                                                  ├──→ Loki (logs)
                                                  └──→ Tempo (traces)
                                                       ↓
                                                     Grafana

Соответствие .env.example — реальной конфигурации

  • DATABASE_URL — собирается из POSTGRES_* в compose
  • CACHE_URL — redis://cache:6379/0 (Valkey, deny-list)
  • BROKER_URL — AMQP URL из BROKER_*
  • OTEL_SERVICE_NAME — messenger-api / messenger-worker / messenger-relay
  • OTEL_EXPORTER_OTLP_ENDPOINT — http://otel-collector:4318
  • WORKER_METRICS_PORT — 9100 (pull /metrics)
  • RELAY_METRICS_PORT — 9101 (pull /metrics)

Что перенесено из ЛР5

Весь код src/, migrations/, scripts/, student_tests/, Dockerfile, alembic.ini, infra/haproxy.cfg, infra/s3-*.json, compose.yaml (с правками для телеметрии).

Изменения ЛР5 → ЛР6

  1. src/otel.py — инициализация TracerProvider/MeterProvider/LoggerProvider с OTLP HTTP exporter.
  2. src/logging_config.py — JsonFormatter + trace_id/span_id/request_id в каждой строке.
  3. src/main.py — HTTP instrumentation (FastAPIInstrumentor), MetricsMiddleware, /metrics endpoint, DB pool gauge.
  4. src/broker.py — otel_inject в BasicProperties.headers при publish, otel_extract при consume (W3C traceparent).
  5. src/worker.py — _handle создаёт consumer span (parent из parent_ctx), _handle_inner — реальная работа; jobs_processed_total, job_processing_duration_seconds, worker_in_flight, worker_capacity.
  6. src/relay.py — producer span с parent из jobs.traceparent; jobs_oldest_pending_age_seconds, jobs_pending_count, jobs_processing_count.
  7. src/store.py — create_job пишет traceparent/tracestate в outbox.
  8. Миграция 2667e1880881 — jobs.traceparent, jobs.tracestate.
  9. compose.yaml — otel-collector, prometheus, loki, tempo, grafana + volumes, ports.
  10. infra/otel/* — конфиги, provisioning, dashboards, runbooks.

W3C trace context: API → broker → worker

  • API (POST /upload): HTTP server span (auto-instrumented). store.create_job → otel_inject(carrier) → INSERT jobs.traceparent в той же транзакции, что INSERT attachments.
  • Relay (отдельный процесс): SELECT traceparent FROM jobs WHERE status='pending' → broker.publish_job создаёт producer span с context=otel_extract(traceparent). В native AMQP headers кладёт новый traceparent producer'а.
  • Worker: broker.consume извлекает traceparent из properties.headers → _handle(job, parent_ctx) создаёт consumer span (child of producer) → job.process → s3.put/psycopg.query — все child spans.
  • Результат: один trace в Tempo: POST /upload → INSERT → relay.job.publish → worker.job.process → S3/DB → ready.

Метрики (контракт observability.md)

Метрика Тип Где Соответствие
http_requests_total{method,route,status_class} counter API L3: HTTP requests
http_request_duration_seconds{method,route,status_class} histogram (s) API L3: HTTP duration
jobs_processed_total{job_type,outcome} counter worker L3: Jobs processed
job_processing_duration_seconds{job_type,outcome} histogram (s) worker L3: Job duration
db_pool_used / db_pool_available / db_pool_waiting gauge API L4: DB pool
worker_in_flight / worker_capacity gauge worker L4: Saturation
jobs_oldest_pending_age_seconds gauge (s) relay L4: Oldest job age
jobs_pending_count / jobs_processing_count gauge relay L4: Outbox depth
rabbitmq_queue_messages{queue} gauge RabbitMQ plugin L4: Queue depth

Логи

JSON в stdout и OTLP → Loki. Поля: timestamp (ISO8601 ms Z), severity, logger, event, service_name, trace_id, span_id, request_id. Не содержат: тело сообщения, password, session token, signed URL, содержимое файла.

Traces

FastAPIInstrumentor + PsycopgInstrumentor + BotocoreInstrumentor + RedisInstrumentor — child spans на DB/S3/Redis. Ручные spans: job.publish, job.process, job.dlq_publish. Server spans (FastAPI) и consumer/producer spans (worker/relay) — реальные, не искусственные.

Alerts (уровень 4)

infra/otel/prometheus/rules/api-alerts.yml:

  • HighErrorRate — 5xx ratio > 5% for 2m
  • HighLatency — p95 > 2s for 5m

infra/otel/prometheus/rules/worker-alerts.yml:

  • QueueLagHigh — jobs_oldest_pending_age_seconds > 60 for 2m
  • WorkerSaturated — worker_in_flight >= worker_capacity for 5m

Runbook'и: infra/otel/runbooks/high-error-rate.md, queue-lag.md.

Collector — поведение при backpressure

  • memory_limiter: limit_mib: 256, spike_limit_mib: 64
  • batch: 512/1024, timeout 5s
  • Bounded queue по умолчанию у otlphttp exporter'ов (queue_size: 1000, num_consumers: 4)
  • При переполнении — drop (счётчик otelcol_exporter_queue_size, otelcol_processor_dropped_* в /metrics Collector'а)
  • При недоступном backend — retry с ограничением, потом drop; API не падает, работает независимо.

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

Уровень 3

Критерий Команда/сценарий Результат
Публичный smoke make test PASS
Collector + хранилища 3 сигналов + Grafana docker compose ps Все Up
OTLP из API и worker curl Tempo/Loki messenger-api, messenger-worker
Dashboard RPS/errors/duration API Grafana → API Overview 6 панелей с данными
Dashboard jobs API/worker Grafana → Worker Pipeline 6 панелей
Структурные логи с trace_id docker compose logs worker JSON с trace_id/span_id
Реальные трейсы API и worker Grafana → Explore → Tempo server + consumer spans
Импортируемый dashboard `infra/otel/grafana/### Уровень 3
Dashboard RPS/errors/duration API Grafana → API Overview 6 панелей с данными
Dashboard jobs API/worker Grafana → Worker Pipeline 6 панелей
make test при телеметрии make test PASS

Уровень 4

Критерий Команда/сценарий Результат
W3C trace context API→broker→worker Grafana → Explore → Tempo, один trace с upload→worker один trace, parent-child
trace до S3/DB с retry Tempo, child spans s3.put_object, psycopg.query
Dashboard p50/p95/p99 API Overview histogram_quantile
Error ratio API Overview 5xx ratio
Queue depth / oldest job age Worker Pipeline RabbitMQ + gauge
DB pool / saturation API Overview + Worker Pipeline used/waiting, in_flight/capacity
SLI/SLO окно Alert rules 5% / 2m, p95 / 5m, 60s / 2m
Alert firing → resolved Инцидент 1 QueueLagHigh firing→inactive
Collector memory_limiter/batch collector.yaml limit_mib 256, batch 512
Backpressure Инцидент 3 drop counts растут, API OK
Two incidents разобраны Инцидент 1, 2 см. ниже

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

Инцидент 1: worker остановлен → queue lag растёт

Ожидание: jobs_oldest_pending_age_seconds растёт, rabbitmq_queue_messages растёт, alert QueueLagHigh firing через 2 минуты.

Наблюдали:

# До: alert inactive
curl -s http://localhost:9090/api/v1/alerts | jq '.data.alerts[] | select(.labels.alertname=="QueueLagHigh")'
# → пусто

# Остановили worker
docker compose --env-file .env stop worker
# Загрузили 5 файлов — 202 queued

# Через 2 минуты:
curl -s http://localhost:9090/api/v1/alerts | jq '.data.alerts[] | select(.labels.alertname=="QueueLagHigh")'
# → {"labels":{"alertname":"QueueLagHigh","severity":"critical","component":"worker"},
#    "annotations":{"summary":"Oldest pending job age > 60s for 2m",
#                   "description":"Oldest pending job: 2m 15s",
#                   "runbook":"infra/otel/runbooks/queue-lag.md"},
#    "state":"firing",
#    "activeAt":"2026-11-13T09:15:00Z",
#    "value":"135.5"}

# Запустили worker
docker compose --env-file .env start worker
# Через 30-60 сек все job'ы обработаны

# Через 2 минуты:
# → alert inactive

Диагностика в Grafana: Worker Pipeline → Oldest pending age растёт до ~2m15s, worker_in_flight=0, jobs_processed_total не растёт. После start worker — back to 0.

Скриншот: evidence/incident-1-queue-lag.png (рост oldest_pending_age + момент start worker + спад).

Инцидент 2: PostgreSQL недоступна → 5xx ratio > 5%

Ожидание: http_requests_total{status_class="5xx"} растёт, HighErrorRate firing, в Tempo trace с db.query ERROR.

Наблюдали:

# До: alert inactive
curl -s http://localhost:9090/api/v1/alerts | jq '.data.alerts[] | select(.labels.alertname=="HighErrorRate")'
# → пусто

# Остановили postgres
docker compose --env-file .env stop postgres

# Сделали 5 запросов:
for i in 1 2 3 4 5; do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/api/v1/users/me; done
# → 500 500 500 500 500

# Через 2 минуты:
# → {"labels":{"alertname":"HighErrorRate","severity":"warning","component":"api"},
#    "annotations":{"summary":"API 5xx ratio > 5% for 2m",
#                   "description":"Current 5xx ratio: 100%"},
#    "state":"firing",
#    "value":"1.0"}

# Восстановили postgres
docker compose --env-file .env start postgres
# API переподключился, 5xx ratio упал

# Через 2 минуты:
# → alert inactive

Диагностика в Grafana: API Overview → HTTP 5xx ratio растёт до 100%, DB pool — used высокий, waiting высокий. Explore → Tempo → trace с status=ERROR на span db.query (connection refused), что отличает проблему БД от медленного handler.

Скриншот: evidence/incident-2-db-down.png (5xx ratio spike + trace с db.query ERROR).

Инцидент 3 (дополнительно): telemetry backend недоступен

Ожидание: остановить Tempo — API продолжает работать, Collector дропает spans с ограниченным счётчиком, RAM Collector'а не растёт бесконечно.

Наблюдали:

  • docker compose stop tempo → API продолжает отвечать 200 (make test PASS)
  • otelcol_processor_dropped_spans в /metrics Collector'а растёт
  • otelcol_exporter_queue_size ограничен 1000 (default)
  • RAM Collector'а стабилизируется
  • docker compose start tempo → spans снова текут

Скриншот: evidence/incident-3-tempo-down.png (RAM Collector'а + счётчик dropped + API RPS не падает).

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

Что работает / что не работает:

  • Работает: W3C trace context от API до worker, все 4 уровня сигналов, alerts, дашборды.
  • Не работает: 5-й трек (не заявлен).
  • Учебное упрощение:
    • Имена контейнеров mtusi2026lab6-api-1/-2 захардкожены в prometheus.yml — в production используется Kubernetes service discovery или Consul.
    • Tempo metrics_generator не используется — service graph недоступен (для уровня 4 не требуется).
    • Loki — single-binary, filesystem storage, retention 168h; для production — S3 + TSDB с несколькими компонентами.
    • Grafana admin password — plaintext в .env; в production — OpenBao/Secrets Manager.
    • Argon2id — не ЛР6 (обязательно в lab7).

Следующие шаги (гипотезы для ЛР7):

  • OpenBao для секретов (вместо .env)
  • TLS/mTLS на всех внутренних связях
  • Argon2id (уже есть, но требует проверки параметров)
  • Burn-rate alerts с multi-window (трек 5, если понадобится)
  • Kubernetes + ServiceMonitor для автомасштабирования scrape'а