forked from mtusi2026/mtusi2026lab6
204 lines
15 KiB
Markdown
204 lines
15 KiB
Markdown
# Лабораторная 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/
|