# Лабораторная 6. Наблюдаемость: OpenTelemetry и Grafana Автор: **Каменский Андрей, БПИ2301**. Целевая оценка: **4**. Исследовательский трек на 5 не заявлен. Реализация продолжает собственную lab5. Commit/PR в рамках этой работы не публиковались. ## Запуск и проверка Docker с Compose v2, Python 3.13 для полного набора инструментов. Все зависимости поднимаются из этого репозитория. Предварительно установленный broker/БД/S3 не нужен. ```sh 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, например: ```promql 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/