15 KiB
Отчёт — лабораторная 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.
cp .env.example .env, заполнитьPOSTGRES_PASSWORD,S3_*,BROKER_*,GRAFANA_ADMIN_PASSWORD(любые локальные синтетические).docker compose --env-file .env up -d --build— все сервисы (17 контейнеров, включая телеметрию).- Дождаться healthy:
docker compose --env-file .env ps. make test— PASS.GRAFANA_PASS=$(grep '^GRAFANA_ADMIN_PASSWORD=' .env | cut -d= -f2-)- Открыть
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_*в composeCACHE_URL—redis://cache:6379/0(Valkey, deny-list)BROKER_URL— AMQP URL изBROKER_*OTEL_SERVICE_NAME—messenger-api/messenger-worker/messenger-relayOTEL_EXPORTER_OTLP_ENDPOINT—http://otel-collector:4318WORKER_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
src/otel.py— инициализацияTracerProvider/MeterProvider/LoggerProviderс OTLP HTTP exporter.src/logging_config.py—JsonFormatter+ trace_id/span_id/request_id в каждой строке.src/main.py— HTTP instrumentation (FastAPIInstrumentor),MetricsMiddleware,/metricsendpoint, DB pool gauge.src/broker.py—otel_injectвBasicProperties.headersпри publish,otel_extractпри consume (W3C traceparent).src/worker.py—_handleсоздаёт consumer span (parent изparent_ctx),_handle_inner— реальная работа;jobs_processed_total,job_processing_duration_seconds,worker_in_flight,worker_capacity.src/relay.py— producer span с parent изjobs.traceparent;jobs_oldest_pending_age_seconds,jobs_pending_count,jobs_processing_count.src/store.py—create_jobпишетtraceparent/tracestateв outbox.- Миграция
2667e1880881—jobs.traceparent,jobs.tracestate. compose.yaml—otel-collector,prometheus,loki,tempo,grafana+ volumes, ports.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 2mHighLatency— p95 > 2s for 5m
infra/otel/prometheus/rules/worker-alerts.yml:
QueueLagHigh—jobs_oldest_pending_age_seconds > 60for 2mWorkerSaturated—worker_in_flight >= worker_capacityfor 5m
Runbook'и: infra/otel/runbooks/high-error-rate.md, queue-lag.md.
Collector — поведение при backpressure
memory_limiter:limit_mib: 256,spike_limit_mib: 64batch: 512/1024, timeout 5s- Bounded queue по умолчанию у
otlphttpexporter'ов (queue_size: 1000,num_consumers: 4) - При переполнении — drop (счётчик
otelcol_exporter_queue_size,otelcol_processor_dropped_*в/metricsCollector'а) - При недоступном 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в/metricsCollector'а растёт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'а