Лабораторная 6. Наблюдаемость: OpenTelemetry и Grafana
Научиться находить причину деградации через метрики, логи и трассы всей системы, включая фоновую обработку.
В этой реализации сохранён сервер Lab 5 и добавлены OpenTelemetry-инструментация, Collector, Prometheus, Loki, Tempo, Grafana, alert rules и эксперимент по sampling. Язык и framework свободные; UI не обязателен.
Карта курса · Процесс fork/PR · OpenAPI · Семантика API · Проверки · Отчёт · Примеры JSON · Памятка преподавателю
Откуда начинаем
Бизнес-API и фоновый pipeline перенесены из lab5; контракт не меняется. Стенд сохраняет API-реплики, PostgreSQL, S3, RabbitMQ, publisher, worker и reconciler.
Архитектура: API/worker → OTLP → OTel Collector → хранилища metrics/logs/traces → Grafana; queue context связывает API и worker.
Что сделать
- Выберите хранилища: например Prometheus для метрик, Loki для логов, Tempo для трасс. Разрешена другая совместимая комбинация с Grafana; Grafana сама не хранит все три сигнала.
- Добавьте SDK-инструментацию API и worker и отдельный Collector в общий Compose/Swarm; настройте receivers/processors/exporters и хранение данных.
- Реализуйте набор сигналов contracts/observability.md и импортируемые dashboard/datasources. Не используйте user_id/chat_id/message_id как labels метрик.
- Проверьте связь запроса, структурного лога и обработки задания. Секреты, тела сообщений и изображения не должны попадать в telemetry.
- Создайте нагрузку, внедрите два ограниченных отказа и найдите их причину только с помощью сохранённых наблюдений; приложите доказательства.
Оценка «3»: работающий минимум
- Весь минимум lab5 работает. Collector, хранилища трёх сигналов и Grafana включены в общий воспроизводимый стенд; конфиги и provisioning лежат в Git, persistent volumes сохраняют нужную историю.
- API и worker отдают OTLP в Collector. В Grafana видны: RPS/errors/duration API, успешные/ошибочные jobs и duration worker; доступны структурные логи и реальные трассы API и worker.
- Есть импортируемый dashboard, а не только screenshot. Сохраняются низкокардинальные атрибуты и идентификаторы trace/span в логах; содержимое сообщений, пароли/токены не экспортируются.
- На контролируемом запросе можно найти trace и связанный лог; на job — worker trace и лог. make test проходит при включённой телеметрии. Объяснено назначение каждого хранилища.
Оценка «4»: уровень стажёра/джуна
Весь уровень 3 и все пункты ниже:
- W3C trace context переносится API → broker → worker; видны producer/consumer spans с корректной связью parent или link. По одному upload найдена цепочка до S3/DB результата, включая retry.
- Dashboard показывает p50/p95/p99, долю ошибок, queue depth/возраст старейшей job, DB pool и saturation worker. Приведены запросы и единицы измерения; percentile вычисляется из histogram, не средних.
- Задан проверяемый SLI/SLO и окно; сохранены alert rules минимум для высокого error rate и растущего queue lag. Alerts проверены искусственным отказом; доставка наружу не нужна, достаточно локального состояния firing/resolved.
- Collector имеет memory limiter/batch и ограниченную буферизацию/поведение при недоступном backend. Остановка telemetry-хранилища не ломает сообщения и не вызывает бесконечный рост RAM. Отчёт содержит разбор двух инцидентов и шаги диагностики.
Оценка «5»: исследование и доказанный результат
Весь уровень 4 и один законченный трек на выбор. Приведите гипотезу, повторяемую методику, результаты и ограничения.
Трек 1. Цена наблюдаемости. Сравните telemetry off/on и ≥2 sampling/aggregation настройки при одинаковой нагрузке: latency, CPU/RAM, объём ingest, потери spans. Объясните, какие ошибки и редкие медленные запросы теряются; предложите и проверьте сбалансированную конфигурацию.
Трек 2. SLO и обнаружение инцидентов. Обоснуйте SLO для API и времени до ready, реализуйте burn-rate alerts с несколькими окнами, воспроизведите краткий всплеск и длительную деградацию. Измерьте время обнаружения/восстановления, ложные срабатывания и покажите runbook, по которому другой студент находит причину.
Как начать и проверить
# Локальный offline check, Python 3.9+:
make check
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
cp .env.example .env
scripts/bootstrap-secrets.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь health/ready. По умолчанию API публикуется на localhost:8080.
make test PYTHON=.venv/bin/python BASE_URL=http://localhost:8080
.env.example содержит локальные настройки без секретов. Секреты генерируются в secrets/ и не должны коммититься. compose.example.yaml — worksheet с пустым services, реальный запускаемый стенд — compose.yaml. Образы закреплены версиями, данные приложения и трёх backend хранятся в named volumes.
Для полной OpenAPI-валидации установите requirements-dev.txt и выполните make validate PYTHON=.venv/bin/python. Основные локальные проверки pipeline: make test-worker, make test-reconcile, make test-pipeline-faults. Сводный отчёт о затратах sampling запускается после старта стенда командой make benchmark-observability PYTHON=.venv/bin/python BASE_URL=http://localhost:8080.
Grafana доступна на http://localhost:3000; пароль администратора находится в локальном secrets/grafana_admin_password. OTLP endpoints и telemetry backends доступны только внутри Compose-сети. При занятом порте задайте другой APP_PORT в локальном .env и соответствующий BASE_URL.
Примеры запросов доступны в examples/requests.http, примеры JSON — в contracts/examples.json. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по tests/README.md, остальные доказательства приведите в отчёте.
Сценарий защиты
- С нуля поднять стенд, импортировать provisioning без ручного набора dashboard, запустить smoke и нагрузку.
- Показать свежие метрики, одну трассу и соответствующий структурный лог API и worker; проверить, что это данные своего приложения.
- Для 4: пройти от upload до worker в одном trace/связанных traces, остановить worker или ограничить DB, увидеть firing и затем resolved.
- Остановить telemetry backend, проверить сохранение работы API и ограниченное поведение exporter. Для 5: повторить эксперимент.
Что должно быть в PR
Collector configuration, конфиги backend, Grafana provisioning/dashboards, alert rules по уровню, схема сигналов и отчёт инцидентов.
Заполните REPORT.md и шаблон PR, укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах объявленных переходов.
Вопросы на защите
- Чем лог, метрика и trace отвечают на разные вопросы об одном инциденте?
- Почему chat_id в labels может исчерпать хранилище?
- Как очередь переносит причинную связь между процессами?
- Почему среднее latency не заменяет p99 и почему нельзя усреднять p99 реплик?