Files
mtusi2026lab6-fork/REPORT.md
T

23 KiB
Raw Blame History

Отчёт — лабораторная 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. Sampler DropOrphanClientSpans: 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.