23 KiB
Отчёт — лабораторная 6
- Автор, группа: Попов Константин Дмитриевич, группа БВТ2303
- Целевая оценка: 4; трек 5 не заявляется
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: OpenTelemetry Python SDK 1.29.0 (
opentelemetry-sdk,opentelemetry-exporter-otlp-proto-http), инструментации 0.50b0 (fastapi,psycopg,botocore); OpenTelemetry Collector contrib 0.115.1, Prometheus 2.55.1, Loki 3.3.2, Tempo 2.6.1, Grafana 11.4.0. Документация: OTel Collector configuration (memory_limiter, batch, sending_queue/retry_on_failure), W3C Trace Context, OTel messaging semantic conventions (producer/consumer,messaging.*), HTTP semconv (http.server.request.duration), Prometheus histograms /histogram_quantile, Loki OTLP ingestion (structured metadata), Grafana provisioning. Остальной стек — как в lab5 (см.docs/lab5/REPORT.md). Помощь ИИ (Claude) — при проектировании схемы сигналов, написанииsrc/telemetry.py, конфигураций, dashboard, alert rules, сценариев инцидентов и отчёта.
Минимум lab5 перенесён целиком (HAProxy, 2 реплики API, PostgreSQL, Redis-кэш, SeaweedFS S3, Redis Streams broker, worker, outbox, retry/DLQ). Бизнес-API не менялся; новые поля только служебные: traceparent/tracestate в сообщении задания (уже разрешены contracts/jobs.schema.json).
Запуск из чистого clone
Версии. API и worker — один образ из Dockerfile (python:3.12.7-slim-bookworm), postgres:16.4-alpine, redis:7.4.1-alpine (кэш и broker), haproxy:2.8.30-alpine, chrislusf/seaweedfs:4.50, otel/opentelemetry-collector-contrib:0.115.1, prom/prometheus:v2.55.1, grafana/loki:3.3.2, grafana/tempo:2.6.1, grafana/grafana:11.4.0. Нужны Docker с Compose v2 и Python 3.9+ на хосте. Оркестрация — Compose.
make up # = python scripts/init_secrets.py; cp .env.example .env;
# docker compose --env-file .env up -d --build; ожидание готовности API/S3/worker
make test # публичный smoke через LB http://localhost:8080
make obs-urls # Grafana http://127.0.0.1:3000 (admin / secrets/grafana_admin_password), Prometheus :9090
make down # безопасная остановка, все volumes сохраняются
make destroy # НАМЕРЕННОЕ удаление всех данных (down -v): БД, S3, очередь, история телеметрии
Bootstrap: секреты (secrets/, вне Git) создаёт scripts/init_secrets.py, в т.ч. новый grafana_admin_password. Миграции — one-shot migrate, бакет — s3-init (как в lab5). Provisioning Grafana (datasources + dashboard) и rules Prometheus подключаются из Git read-only при старте — ручной набор не нужен. Повторный make up идемпотентен.
Архитектура и решения
клиент -> HAProxy -> API x2 ──SQL──> PostgreSQL (источник истины, job_outbox)
│ └─S3──> SeaweedFS
└─outbox relay─XADD(traceparent)─> broker (Redis Streams) ─> worker ─S3/SQL─> ...
API/worker ──OTLP/HTTP :4318──> otel-collector ─┬─ traces ─OTLP gRPC─> Tempo (volume tempodata)
├─ metrics ─/metrics :8889 <─scrape─ Prometheus (promdata, rules)
└─ logs ─OTLP /otlp─> Loki (lokidata)
Grafana (grafanadata) читает все три
| Роль | Сервис | Образ | Назначение | Volume | Порт наружу |
|---|---|---|---|---|---|
| Collector | otel-collector |
contrib 0.115.1 | приём OTLP, memory_limiter, batch, ограниченные очереди, экспорт | — (не хранилище) | нет |
| Метрики | prometheus |
v2.55.1 | TSDB метрик 7 д, вычисление recording/alert rules, состояние firing/resolved | promdata |
127.0.0.1:9090 |
| Логи | loki |
3.3.2 | хранение логов 7 д; индекс только по service_name/service_instance_id, остальное — structured metadata |
lokidata |
нет |
| Трассы | tempo |
2.6.1 | хранение spans 72 ч, поиск TraceQL | tempodata |
нет |
| UI | grafana |
11.4.0 | запросы и dashboard; сама сигналы не хранит | grafanadata |
127.0.0.1:3000 |
Почему три хранилища. Метрика отвечает «сколько и как часто» (дёшево, агрегаты, алерты), но не «какой запрос»; лог отвечает «что именно произошло и почему» в одном процессе; trace отвечает «где ушло время» по цепочке процессов. Prometheus хранит числовые ряды с метками, Loki — строки с минимальным индексом, Tempo — деревья spans по trace_id.
Инструментация (src/telemetry.py). Вызывается до создания пула БД/клиента S3:
- Resource:
service.name=messenger-api/messenger-worker,service.version=APP_VERSION,service.instance.id=X-Instance-Id(hostname контейнера),deployment.environment.name=lab. - Traces: FastAPI (SERVER span, только шаблон маршрута; health исключены; внутренние send/receive spans отключены), psycopg (SQL без параметров), botocore (S3). Redis не инструментируется: команды
AUTHи ключи кэша сессий не должны попасть в spans. SamplerDropOrphanClientSpans: CLIENT-span без родителя не сохраняется — это фоновые SQL/S3 (sweeper outbox раз в секунду, GC, readiness, callbacks метрик), иначе Tempo заполнялся бы тысячами пустых трасс. Всё внутри SERVER/PRODUCER/CONSUMER сохраняется (ParentBased AlwaysOn). - Logs: JSON в stdout (для
docker logs) и OTLP. Поля:timestamp,severity,service.name,event,trace_id,span_id(если есть активный span), плюс технические поля (request_id,http_route,outcome...). Каждый бизнес-запрос даёт строкуevent=http.requestс шаблоном маршрута, статусом, длительностью иrequest_id; каждое сообщение worker'а —event=job.processed. X-Request-Idзаписывается атрибутомmessenger.request_idв SERVER span: ответ с ошибкой → trace → лог.
Перенос контекста через очередь (W3C). job_payload() записывает traceparent текущего span в JSON задания, который хранится в job_outbox (PostgreSQL) — контекст переживает задержку публикации и рестарты. Relay (быстрый путь API или sweeper любого процесса) создаёт PRODUCER span attachments.jobs publish — ребёнок span'а из строки outbox — и кладёт в брокер уже его traceparent. Worker создаёт CONSUMER span attachments.jobs process — ребёнок producer. Внутри него — SQL claim/complete и S3 GetObject/PutObject. При временной ошибке retry_or_fail() пишет новую строку outbox с traceparent consumer span → следующая попытка в той же трассе (связь parent-child, а не link: одна логическая операция «upload → ready»).
Сигналы и их реальные имена в Prometheus (Collector prometheus exporter: точки → _, единица → суффикс, counter → _total; job = service.name, instance = service.instance.id):
| Логический сигнал (contracts/observability.md) | Имя OTel | Имя в Prometheus | Атрибуты | Ед. |
|---|---|---|---|---|
| HTTP requests (counter) | http.server.request.duration (count) |
http_server_request_duration_seconds_count |
http_request_method, http_route (шаблон), http_response_status_code → класс через label_replace |
шт |
| HTTP duration | http.server.request.duration |
http_server_request_duration_seconds_bucket |
те же; buckets 5 мс…10 с (View) | с |
| Jobs processed/failed | messenger.jobs.processed |
messenger_jobs_processed_total |
job_type, outcome = succeeded/retry/failed/noop/lease_lost/poison/error |
шт |
| Job duration | messenger.job.duration |
messenger_job_duration_seconds_bucket |
job_type, outcome; buckets 50 мс…60 с |
с |
| Queue depth | messenger.queue.depth |
messenger_queue_depth |
queue, state=queued/processing |
шт |
| Oldest job age | messenger.queue.oldest_age |
messenger_queue_oldest_age_seconds |
queue |
с |
| Outbox backlog | messenger.outbox.pending |
messenger_outbox_pending |
queue |
шт |
| DB pool | messenger.db.pool.connections / .waiting / .max |
messenger_db_pool_connections{state=used|idle}, messenger_db_pool_waiting, messenger_db_pool_max |
— | шт |
| Worker saturation | messenger.worker.busy / .capacity |
messenger_worker_busy, messenger_worker_capacity |
— | слоты |
| CPU / RAM процесса | process.cpu.time, process.memory.rss |
process_cpu_time_seconds_total, process_memory_rss_bytes |
— | с, байты |
| End-to-end time to ready | messenger.attachment.time_to_ready |
messenger_attachment_time_to_ready_seconds_bucket |
job_type; от COMMIT задания (ответ 202) до COMMIT ready |
с |
| Публикации relay | messenger.jobs.published |
messenger_jobs_published_total |
job_type |
шт |
Глубина/возраст очереди считаются из PostgreSQL (источник истины) и публикуются API-репликами: при остановленном worker метрика продолжает жить. Реплики дают одинаковые значения — в запросах max(). В метках нет user_id/chat_id/message_id/attachment_id/request_id/URL/filename. Технические ID (job_id, attachment_id, request_id) есть только в атрибутах spans и логов — они нужны для поиска конкретного upload, данные синтетические.
Что не экспортируется: тела сообщений, байты изображений, filename (в логах/spans нет), заголовки Authorization/Cookie (инструментация их не пишет), параметры SQL (db.statement — шаблон с %s), подписанные URL (их нет в API), пароли/токены. Проверено: grep по всем выгруженным spans/логам локального прогона на Authorization|Bearer |password — 0 совпадений.
Перцентили считаются только из histogram: histogram_quantile(0.95, sum by (le) (rate(..._bucket[5m]))) — buckets всех реплик суммируются, а не усредняются p95 реплик. Важная найденная ошибка: инструментация 0.50b0 при метрике в секундах ставит buckets по умолчанию 0…10000 (миллисекундные) — все запросы попадали бы в первый bucket; заданы явные buckets через View.
SLI/SLO (infra/prometheus/rules/messenger.yml, recording rules):
- доступность:
1 − 5xx/всебизнес-запросы, health исключены, 4xx не ошибка сервиса; SLO 99% за скользящий 1 ч; - задержка: доля запросов быстрее 0.5 с (bucket
le="0.5"); SLO 95% за 1 ч; - очередь: возраст старейшего незавершённого задания; цель < 60 с.
Alert rules (состояние — Prometheus /alerts, Grafana; доставка наружу не нужна), runbook — docs/runbooks.md:
| Alert | Условие | Окно / for |
|---|---|---|
ApiHighErrorRate |
доля 5xx > 5% и трафик ≥ 0.2 RPS | rate 1m, for 1m |
QueueLagGrowing |
max(messenger_queue_oldest_age_seconds) > 60 |
for 30s |
TelemetryExportFailing |
растут otelcol_exporter_send_failed_* / enqueue_failed_* |
rate 1m, for 1m |
Collector и ограниченная буферизация (infra/otel/collector.yaml): memory_limiter (180 MiB, spike 40) → batch (512/1024, 2 с) → exporters с sending_queue 20 батчей и retry_on_failure не дольше 60 с; GOMEMLIMIT=200MiB, лимит контейнера 384M. Переполнение очереди → отбрасывание с подсчётом (otelcol_exporter_enqueue_failed_*). На стороне SDK: BatchSpanProcessor/BatchLogRecordProcessor с очередью 2048, таймаут экспорта 5 с; при недоступном Collector батч отбрасывается, ошибки SDK — одна JSON-строка в stdout без трейсбека и не в OTLP (иначе петля «лог о неудачной отправке логов»). Ни API, ни worker не имеют depends_on на телеметрию.
Переменные .env.example → конфигурация: OTEL_SDK_DISABLED (выключатель), OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=lab; OTEL_SERVICE_NAME задаётся в compose отдельно для API и worker. GRAFANA_PORT, PROMETHEUS_PORT — порты UI на 127.0.0.1. Остальное — как в lab5.
Что изменено относительно lab5: src/telemetry.py (новый); src/main.py (setup, FastAPI-инструментация, access-лог, метрики пула/очереди), src/worker.py (consumer span, метрики заданий/пула/занятости, time-to-ready), src/outbox.py (producer span, повторная инъекция контекста), src/jobs.py (traceparent в payload, complete() возвращает время до ready); requirements.txt (+OTel); compose.yaml (+5 сервисов, сеть telemetry, 4 volume, OTEL_* env); infra/{otel,prometheus,loki,tempo,grafana}; scripts/incident.py, scripts/alerts_watch.py; Makefile (obs-*, incident-*, alerts-watch, destroy); docs/runbooks.md. Отчёт lab5 и его доказательства перенесены в docs/lab5/.
Доказательства критериев
Важно о среде. Доказательства в evidence/local-sandbox/ получены в песочнице без доступа к Docker Hub: те же исходники запускались напрямую (Python 3.13, PostgreSQL 16.2, Redis 6.2, S3-эмулятор moto вместо SeaweedFS, 1 реплика API без HAProxy) с настоящими бинарниками Collector 0.115, Prometheus 2.55.1, Loki 3.3.2, Tempo 2.6.1 и конфигурациями из этого репозитория. Grafana там не запускалась (дистрибутив недоступен) — все PromQL-запросы dashboard выполнены через Prometheus API (0 ошибок), LogQL/TraceQL — через API Loki/Tempo. Docker-стенд: Windows 10, Ryzen 5 7500f, 32 GB; доказательства в корне evidence/.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Публичный smoke при включённой телеметрии | make test |
PASS: lab6 public API scenario |
evidence/local-sandbox/smoke.txt |
make check |
make check |
PASS: offline skeleton structure |
— |
| API и worker отдают OTLP в Collector; три хранилища | make obs-probe → Loki/Tempo API |
лог event=http.request с trace_id в Loki; trace с тем же id в Tempo |
trace_retry_chain.txt |
| RPS/errors/duration API; jobs success/error и duration worker | dashboard, Prometheus API | все 31 PromQL dashboard возвращают данные | metric_names.txt |
| Структурные логи с trace_id/span_id | Loki {service_name=~"messenger-.+"} | request_id="<id>" |
API http.request и worker job.processed одного upload — один trace_id |
trace_retry_chain.txt |
| Импортируемый dashboard | infra/grafana/dashboards/messenger.json + provisioning |
загружается при старте Grafana, папка Messenger | — |
| Нет секретов/тел сообщений в telemetry | grep выгрузки spans/logs | 0 совпадений Authorization, Bearer , password; SQL без параметров |
— |
| Уровень 4: W3C через broker, producer/consumer, retry, S3/DB | upload fault-transient-until-3.png при WORKER_FAULTS=true |
SERVER → PRODUCER → CONSUMER(retry) → PRODUCER → CONSUMER(retry) → PRODUCER → CONSUMER(succeeded) → S3.PutObject×4, SQL — одна трасса из 76 spans | trace_retry_chain.txt, trace_upload_chain.txt |
| p50/p95/p99, ошибки, queue depth/age, DB pool, saturation worker | dashboard «Messenger lab6» | панели с единицами (s, percentunit, reqps, bytes) | messenger.json |
| SLI/SLO и окно; alert error rate | make incident-db + make alerts-watch |
lock 180 с: pending +60 с, firing +120 с, resolved через 21 с после снятия lock | alerts_db_lock_180s.txt |
| Alert queue lag | make incident-worker + make alerts-watch |
queued растёт, QueueLagGrowing pending → firing → resolved; 22 upload'а готовы через 8.7 с после старта worker |
alerts_queue_lag_and_db_short.txt, incident_worker_stop.jsonl |
| Медленная БД отличима от медленного handler | make incident-db |
503 только на /messages; CLIENT span INSERT 5.01 с QueryCanceled |
db_lock_span.txt |
| Collector memory limiter/batch, недоступный backend | make incident-telemetry (SERVICES=otel-collector и SERVICES=tempo,loki) |
API 0 ошибок, ~300 RPS; RSS API 135.0→135.4 MiB; Collector пик 234 MiB, очередь 20/20, потери посчитаны | telemetry_outage.txt |
Эксперименты и отказы
Локальная песочница: 1 реплика API (без LB), 1 worker (2 потока), нагрузка tests/load.py (closed loop, POST сообщений, 2–4 потока), ~300 успешных RPS. Docker-стенд: Windows 10, Ryzen 5 7500f, 32 GB; доказательства в корне evidence/.
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
|---|---|---|---|
| Worker остановлен 110 с, upload каждые 5 с | 202 продолжаются; queue depth и oldest age растут; QueueLagGrowing firing | queued до 22, age > 90 с, firing; API без ошибок | старт worker → все 22 ready за 8.7 с, alert resolved; потерь нет |
LOCK TABLE messages 180 с под нагрузкой |
503 на /messages после statement_timeout 5 с; ApiHighErrorRate firing; trace показывает SQL |
доля 5xx = 100% на маршруте; firing через 120 с; SQL span 5.01 с QueryCanceled |
resolved через 21 с после снятия lock; запросы с 503 не записаны (клиент повторяет с тем же Idempotency-Key) |
| Collector остановлен 45 с | API работает, RAM не растёт, телеметрия за период теряется | 0 ошибок, 303 RPS; RSS 135.0 → 135.4 MiB | после старта экспорт возобновился; spans/логи/метрики за 45 с потеряны (SDK отбрасывает) |
| Tempo + Loki остановлены 120 с (Collector жив) | очередь Collector заполняется и ограничена; потери считаются | queue 20/20; enqueue_failed_spans 131083, ..._log_records 22016; пик RSS 234 MiB; API 0 ошибок |
после старта backend очередь → 0, новые trace/логи видны; потеря — посчитанное число |
Детекция ошибок не мгновенная: rate(...[1m]) первую минуту «разбавлен» трафиком до инцидента (при closed-loop нагрузке RPS падает в сотни раз), поэтому pending наступает примерно через 60 с, firing — ещё через for: 1m. Инцидент короче ~2 мин до firing не доходит (наблюдалось на lock 100 с — только pending). Это осознанный компромисс против ложных срабатываний; для быстрой детекции нужны burn-rate alerts с короткими окнами (трек 5, не заявлен).
Ограничения и следующие шаги
- Весь стенд на одном Docker-host; Collector, Prometheus, Loki, Tempo — по одному экземпляру без репликации. Потеря host = потеря телеметрии и приложения.
- При недоступном Collector телеметрия за этот период теряется (SDK держит только ограниченную очередь в памяти) — так сделано намеренно: приложение важнее телеметрии.
- Метрики очереди публикуют API-реплики: если упадут все API, метрика пропадёт (alert на отсутствие данных не настроен).
- Sampling 100% (кроме фоновых сиротских SQL) — на учебной нагрузке приемлемо; цену наблюдаемости и tail sampling не исследовал (трек 5 не заявлен).
- Метрики
process_*— RSS/CPU процесса, а не cgroup контейнера; для контейнеров можно добавить cAdvisor.