Files

204 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 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/