Files

15 KiB
Raw Permalink Blame History

Лабораторная 6. Наблюдаемость: OpenTelemetry и Grafana

Автор: Каменский Андрей, БПИ2301. Целевая оценка: 4. Исследовательский трек на 5 не заявлен. Реализация продолжает собственную lab5. Commit/PR в рамках этой работы не публиковались.

Запуск и проверка

Docker с Compose v2, Python 3.13 для полного набора инструментов. Все зависимости поднимаются из этого репозитория. Предварительно установленный broker/БД/S3 не нужен.

python3 scripts/setup-env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py --base-url http://localhost:8086
python3 tests/observability.py --base-url http://localhost:8086

setup-env.py создаёт .env со случайными паролями и правами 0600, не выводит секреты и не перезаписывает существующий файл. Первый запуск скачивает образы и компилирует закреплённый MinIO. Миграции до 010 и bootstrap bucket/политик выполняются автоматически. 010 добавляет traceparent/tracestate к durable jobs, прежние данные сохраняются.

Grafana: http://localhost:3000/d/messenger-lab6. Просмотр без входа разрешён только на локальном loopback, права Viewer. Редактор: admin / GRAFANA_ADMIN_PASSWORD из .env. API: http://localhost:8086/docs. Prometheus и alerts: http://localhost:9090/alerts.

Обычная остановка docker compose down сохраняет данные. Намеренное удаление всех учебных данных выбранного проекта: docker compose down --volumes. Эта команда для обычного запуска не нужна.

Быстрая приёмка: make verify-lab6 PYTHON=.venv/bin/python после установки requirements.txt и requirements-dev.txt. Опциональная проверка инцидентов: python3 tests/observability.py --base-url http://localhost:8086 --incidents. Тест снимает воздействия в finally. Долгие эксперименты и исследование цены наблюдаемости не проводились по выбранному уровню и запросу на короткие проверки.

Компоненты и версии

Компонент Версия / роль
Python / FastAPI / Pillow 3.13.0 / 0.141.1 / 13.0.0; приложение и изображения
PostgreSQL / Redis 16.6 / 7.4.2; данные, сессии и отдельный Streams broker
HAProxy / MinIO 3.0.12 / закреплённый commit RELEASE.2025-10-15T17-29-55Z
OpenTelemetry Python API/SDK/OTLP HTTP 1.31.1, semconv 0.52b1
Collector contrib 0.123.0; OTLP receiver, memory_limiter, batch, exporters
Prometheus 3.2.1; временные ряды и вычисление alert rules
Loki 3.4.2; структурные логи через нативный OTLP endpoint
Tempo 2.7.2; реальные traces API/worker
Grafana 11.6.0; импортируемые datasource/dashboard provisioning

Схема: API/worker/dispatcher → OTLP HTTP/protobuf → Collector → Prometheus / Loki / Tempo → Grafana. Collector не является долговременным хранилищем, Grafana — интерфейс. Все backend имеют persistent volumes; Prometheus, Loki и Tempo настроены на 7 дней. Конфигурация находится в infra/observability/. JSON dashboard содержит запросы и единицы.

Бизнес-API lab5 сохранён: пользователи, Bearer-сессии, два API, сообщения/пагинация, идемпотентность, raw upload 202 queued, durable outbox, очередь, worker, оригинал и thumbnail/crop/WebP, retry, failed и replay. Публичные tests/контракты skeleton lab6 не изменены. Дополнительный X-Trace-Id облегчает поиск своего запроса.

Инструментация и перенос контекста

Каждый HTTP-запрос получает настоящий SERVER span. После маршрутизации его имя и http.route используют шаблон, а не URL с UUID. SQLAlchemy events создают CLIENT spans DB-операций без SQL/parameters. S3 transport создаёт CLIENT spans без object key/URL. Worker создаёт CONSUMER span и дочерний image.transform; dispatcher — PRODUCER.

При принятии файла текущий W3C context сохраняется вместе с job/outbox в PostgreSQL. После перезапуска он не зависит от памяти API. Dispatcher извлекает его, создаёт queue.publish и inject-ит traceparent/tracestate в envelope Redis Streams. Worker extract-ит carrier и создаёт queue.consume с producer-родителем. При retry текущий consumer context сохраняется в job; следующая публикация продолжает ту же причинную цепь. Нет передачи тела картинки или произвольного URL.

Resource attributes: service.name=messenger-api / messenger-worker / messenger-dispatcher, service.version=1.6.0, service.instance.id=случайный UUID жизни процесса, deployment.environment.name=lab. API, worker и dispatcher имеют разные service.name; две API-реплики различаются instance ID.

Отдельный безопасный event logger экспортирует JSON с timestamp, severity, service_name, event, trace_id, span_id; HTTP содержит request_id. Не экспортируются пароли, Authorization/session tokens, тела сообщений, изображения, filename, SQL, parameters, S3 keys или signed URLs. В exceptions передаётся только класс ошибки, без произвольного сообщения/stack trace. SDK exception auto-recording для бизнес-spans отключён. Внутренние предупреждения SDK не пересылаются в Loki.

Сигналы и единицы

Контракт Реальная Prometheus-метрика Labels / единица
HTTP requests http_server_requests_total method, route template, status_class; count
HTTP duration http_server_duration_seconds_bucket / sum / count те же labels; seconds
Jobs processed/failed worker_jobs_total job_type, outcome=ready/retry/failed; attempts count
Job processing duration worker_job_duration_seconds_bucket job_type/outcome; seconds
Acceptance → ready attachment_ready_duration_seconds_bucket job_type; seconds
Queue depth queue_depth queue; число queued + processing в PostgreSQL, включая outbox
Oldest job queue_oldest_age_seconds queue; seconds от принятия самой старой незавершённой job
DB pool db_pool_used / db_pool_waiting checked-out connections / ожидающие checkout
Worker saturation worker_busy / worker_capacity число занятых consumers / конфигурационная ёмкость
Process resources process_memory_rss_bytes / process_cpu_time_seconds_total текущий RSS bytes / CPU seconds

Collector также добавляет ограниченные resource labels. Пользовательские IDs, request/trace IDs, raw URL и filename не используются в labels метрик. job_id тоже не label. Технические trace/span IDs находятся только в логах/трассах.

Histogram boundaries: 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120 секунд и +Inf. p95 API, например:

histogram_quantile(0.95,
  sum by (le) (rate(http_server_duration_seconds_bucket{route=~"/api/v1/.*"}[1m])))

Для p50/p99 меняется quantile. Buckets агрегируются по всем репликам ДО quantile. Средние и средние перцентили реплик не используются. HTTP duration измеряется до готовности ответа/его заголовков, а не длительности полного download stream. Backlog age не является histogram processing duration.

SLI, SLO и alerts

SLI = 1 − число 5xx / число всех бизнес-запросов за скользящие 5 минут. SLO: не менее 99% запросов без server error в таком окне. Бизнес-запросы — route под /api/v1/, достигшие API; health исключены, 4xx не считаются server error. Ошибки самого HAProxy до попадания в API этот SLI не измеряет — ограничение стенда. При отсутствии запросов SLI не следует трактовать как доказанное выполнение SLO.

Prometheus rules в infra/observability/alerts.yaml, evaluation interval 2 секунды:

  • ApiHighErrorRate: 5xx/all >5% в окне 30 секунд, минимум 3 запроса, for=5 секунд.
  • QueueLagGrowing: oldest accepted job >15 секунд и depth>0, for=5 секунд.

Это короткие учебные диагностические пороги, а не multi-window burn-rate трека 5. Отправка во внешние каналы отсутствует, проверяется локальное firing/resolved. Правила содержат описание и ссылку на RUNBOOK.md. Prometheus ALERTS хранит историю состояний; после восстановления правило становится inactive (resolved).

Два инцидента и диагностика

1. Worker остановлен. API принимает файл и сообщение с queued-вложением. queue_depth/oldest растут, QueueLagGrowing переходит в firing. По сохранённым наблюдениям: публикация есть, свежего consumer/completion нет, HTTP не деградировал. Причина локализуется в фоновой обработке. После запуска worker тот же ID доходит до ready, backlog/age возвращаются в 0, alert resolved.

Дополнительная краткая пауза S3 демонстрирует retry: consumer получает временный отказ, следующая попытка сохраняет trace ID upload. После восстановления S3 видны несколько consumer spans в одной трассе и готовый результат.

2. INSERT блокирован PostgreSQL. Учебная SHARE-блокировка messages задерживает запись, но совместима с SELECT readiness. Запросы получают ограниченный 503, появляются ApiHighErrorRate firing, длинные ERROR db.INSERT spans и db.error logs. Причина — ожидание DB-операции, а не image resize или просто медленный HTTP handler. После снятия блокировки запись снова даёт 201; по выходу ошибок из окна alert resolved.

Команды, подтверждения и trace/log evidence сохраняет tests/observability.py. Сценарий не требует чтения секретов или ручного поиска по Docker stdout.

Ограничение буферов и отказ backend

В SDK spans/logs передаются background processors: queue=256, batch=32, schedule=500 ms, HTTP timeout=1 s. Метрики экспортируются раз в 2 s, export timeout=1.5 s; агрегируются ограниченные наборы атрибутов. Нет sync export в обработчике запроса. При переполнении SDK теряет telemetry, а не блокирует API.

Collector: memory_limiter 192 MiB, spike 32 MiB при container limit 256 MiB; batch до 256 записей, timeout 1 s. Для Loki/Tempo sending_queue=64 batch, 2 consumers, HTTP timeout 2 s, retry до 10 s с интервалом 1–3 s. Очереди in-memory: при длительном отказе/restart возможны потери, они не называются durable telemetry.

Метрики Collector фиксируют failures/queue. При остановке Tempo бизнес-сообщения и новый attachment продолжают работать, а exporter показывает ошибки. Это проверка ограниченного сценария и конфигурационных caps; длительного исследования роста RAM под многодневной нагрузкой не проводилось. Бизнес-readiness не зависит от Collector, Grafana, Prometheus, Loki или Tempo.

Доказательства и ограничения

  • evidence/lab6-checks.txt — offline/OpenAPI/lint и публичный smoke.
  • evidence/lab6-signals.txt — короткая проверка трёх сигналов и dashboard queries.
  • evidence/lab6-trace.json, lab6-correlated-logs.json — реальные связанные данные.
  • evidence/lab6-incidents.txt, lab6-observability-summary.json — DB/backend проверки; lab6-worker-incident.json — ранее проверенные остановка worker и retry.
  • evidence/lab6-retry-trace.json — цепочка с повтором.
  • evidence/lab6-db-incident-trace.json, lab6-db-incident-logs.json — диагностика DB.

Стек однокопийный учебный, backend и host — точки отказа; нет HA/backups. Sampling по умолчанию сохраняет все созданные traces; нагрузочных выводов о цене такого режима нет. worker.capacity — конфигурация, не heartbeat; последнее значение может временно сохраняться после остановки процесса. Loss telemetry при отказах допускается и наблюдается, не обещается exactly-once доставка telemetry.

Источники и помощь

Задание/контракты взяты из предоставленного skeleton lab6.