15 KiB
Лабораторная 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.
- https://opentelemetry.io/docs/collector/configuration/
- https://opentelemetry.io/docs/collector/internal-telemetry/
- https://opentelemetry.io/docs/concepts/context-propagation/
- https://redis.io/docs/latest/develop/data-types/streams/
- https://grafana.com/docs/loki/latest/send-data/otel/
- https://prometheus.io/docs/practices/histograms/