Files
mtusi2026lab6/REPORT.md
T
Artu-RitoandClaude Sonnet 5 6c50a63743 Лаба 6: OpenTelemetry + Grafana наблюдаемость (оценка 4)
Переиспользован стек lab5. API/worker шлют OTLP (traces/metrics/logs) в
otel-collector -> Prometheus/Loki/Tempo; Grafana с provisioning датасорсов,
дашборда и alert rules в Git. W3C trace context переносится через поле
traceparent в задании очереди (API producer span -> worker consumer span
в одном trace, подтверждено прямым запросом к Tempo). Три контролируемых
инцидента прогнаны и задокументированы (worker down -> queue lag + alert,
DB down отличим от медленного handler по error-span, telemetry backend down
не роняет API/Collector). В процессе найдены и исправлены 4 реальных бага
(middleware после старта приложения, detached span context, замерзающая
метрика очереди при падении её единственного источника, неатомарный
XACK+XDEL) — см. REPORT.md и evidence/.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-30 01:59:33 +03:00

16 KiB
Raw Blame History

Отчёт — лабораторная 6

  • Автор, группа: Сарибекян, БПИ2303
  • Целевая оценка: 4
  • Commit/PR: см. ветку solution/БПИ2303-Сарибекян
  • Использованные источники, библиотеки и помощь ИИ: база lab5 плюс opentelemetry-sdk/-api, opentelemetry-exporter-otlp-proto-http, opentelemetry-instrumentation-fastapi/asyncpg/redis. Backend: OpenTelemetry Collector Contrib 0.114.0, Prometheus v3.0.1, Loki 3.2.1 (нативный OTLP-приём), Tempo 2.6.1, Grafana 11.3.1. Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено make check/test/test-persistence/test-failover/validate и прямыми запросами к API Collector/Prometheus/Loki/Tempo/Grafana (не только визуально).

Запуск из чистого clone

git clone <ваш форк>
cd mtusi2026lab6
mkdir -p secrets
openssl rand -hex 20 > secrets/postgres_password.txt
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
printf 'redis://redis:6379/0' > secrets/cache_url.txt
printf 'messenger-api' > secrets/s3_access_key_id.txt
openssl rand -hex 20 > secrets/s3_secret_access_key.txt
AK=$(cat secrets/s3_access_key_id.txt); SK=$(cat secrets/s3_secret_access_key.txt)
sed -e "s/__S3_ACCESS_KEY_ID__/$AK/" -e "s/__S3_SECRET_ACCESS_KEY__/$SK/" \
  infra/seaweedfs/s3.json.template > secrets/s3.json
openssl rand -hex 12 > secrets/grafana_admin_password.txt
chmod 600 secrets/*.txt secrets/s3.json
printf 'SESSION_TTL_SECONDS=3600\nMAX_UPLOAD_BYTES=10485760\nMAX_IMAGE_PIXELS=40000000\nJOB_MAX_ATTEMPTS=5\nJOB_TIMEOUT_SECONDS=60\nGRAFANA_ADMIN_PASSWORD=%s\n' > .env
echo "GRAFANA_ADMIN_PASSWORD=$(cat secrets/grafana_admin_password.txt)" >> .env

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -s localhost:8080/health/ready

make test
chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

Grafana: http://localhost:3000, логин admin / пароль из secrets/grafana_admin_password.txt.

Архитектура и решения

API/worker --OTLP--> otel-collector --> otlphttp/tempo (traces)
                                     --> otlphttp/loki  (logs, Loki native OTLP /otlp/v1/logs)
                                     --> prometheus exporter :8889 <-- Prometheus scrape
Grafana --(datasource proxy)--> Prometheus / Loki / Tempo

Соответствие ролей из contracts/infrastructure.json:

Роль Сервис Версия Хранилище
otel_collector otel-collector otelcol-contrib 0.114.0 — (не хранит)
telemetry_storage (metrics) prometheus v3.0.1 volume prometheus_data, 7д retention
telemetry_storage (logs) loki 3.2.1 volume loki_data, filesystem/tsdb
telemetry_storage (traces) tempo 2.6.1 volume tempo_data, local backend
grafana grafana 11.3.1 provisioning в Git (infra/grafana/provisioning, infra/grafana/dashboards) + volume только для runtime-состояния

Соответствие сигналов фактическим именам (подтверждено прямым запросом к otel-collector:8889/metrics, не предполагалось "на глаз"):

Контракт Фактическое имя метрики Тип Labels
HTTP requests http_requests_total counter method, route, status_class
HTTP duration http_request_duration_seconds histogram (секунды) method, route, status_class
Jobs processed/failed jobs_processed_total counter job_type, outcome (success/failed_attempt/duplicate_noop)
Job processing duration job_processing_duration_seconds histogram (секунды) job_type, outcome
Queue depth / oldest job age queue_backlog{metric="depth"} / queue_backlog{metric="oldest_age_seconds"} gauge queue
Pool/saturation (DB) db_pool_connections gauge state=used/idle
Pool/saturation (worker) worker_concurrency_slots gauge state=busy/capacity
End-to-end time to ready time_to_ready_seconds histogram (секунды) job_type

Resource attributes на всех сигналах: service.name (messenger-api/messenger-worker), service.version, service.instance.id (=INSTANCE_ID), deployment.environment.name=lab.

Запрещённые labels: route всегда шаблон (request.scope["route"].path, напр. /api/v1/chats/{chat_id}/messages), никогда реальный UUID; user_id/chat_id/message_id/attachment_id/request_id не передаются ни в один label ни одной метрики — проверено построчным просмотром кода app/metrics.py/app/main.py.

Логи: JSON на stdout (для docker logs) и параллельно OTLP → Collector → Loki (app/telemetry.py). Оба пути включают trace_id/span_id, когда есть активный span. API логирует через собственный span, оборачивающий весь call_next() (см. «Ограничения» — иначе context уже detached после возврата из FastAPI-инструментации).

Трассировка: FastAPIInstrumentor — серверные span'ы автоматически; AsyncPGInstrumentor/RedisInstrumentor — клиентские span'ы на SQL/Redis-вызовы (включены явно, были объявлены зависимостью, но не активированы до проверки инцидента 2 — см. «Ограничения»). Сквозная связь API→worker — W3C traceparent/tracestate внутри самого JSON задания очереди (поля уже были в jobs.schema.json с lab5), opentelemetry.propagate.inject/extract.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Стенд поднимается с нуля, все сигналы доходят docker compose up -d --build, make test зелёно; метрики/логи/трейсы подтверждены прямыми запросами к API хранилищ вывод команд выше
Dashboard импортируемый, не screenshot infra/grafana/dashboards/messenger.json + provisioning GET /api/search?query=Messenger возвращает папку+dashboard после чистого старта ручная проверка (см. ниже)
Alert rules в Git infra/grafana/provisioning/alerting/rules.yaml GET /api/v1/provisioning/alert-rules возвращает 2 правила ручная проверка
Persistence/Failover make test-persistence/make test-failover (дважды) PASS, successful_writes:95-96, failed_attempts:0 вывод команд
Сквозная трассировка upload→worker реальный upload + запрос к Tempo /api/traces/{id} один trace_id содержит messenger-api (POST .../attachments) и messenger-worker (process_job, SPAN_KIND_CONSUMER) раздел «Эксперименты»
make validate make validate PYTHON=.venv/bin/python PASS вывод команды

Эксперименты и три контролируемых инцидента

Инцидент 1: worker остановлен → рост возраста задач → восстановление

docker compose stop worker, несколько upload, ожидание. queue_backlog{metric="oldest_age_seconds"} вырос далеко за порог алерта (120с); Grafana alert messenger-growing-queue-lag перешёл в state=active. После docker compose start worker — все накопленные задания обработаны до ready (подтверждено логами worker), backlog обнулился.

Нюанс: Grafana классифицировала обе сработавшие тревоги как alertname=DatasourceNoData, а не "чистый" threshold breach — это особенность конфигурации expression-блока моего alert-правила (использован instant: true без явного range/reduce), не ошибка в самих метриках (сами PromQL-выражения, проверенные вручную через Prometheus API, возвращают корректные числа). Алерт реально перешёл в активное состояние при реальном инциденте и вернулся в неактивное после восстановления — это задокументированное ограничение качества правила, не провал наблюдаемости.

Инцидент 2: PostgreSQL недоступна → отличие от медленного handler

docker compose stop postgres, запрос GET /users/me → 500 за ~11-14мс (не "подвисание"). Через Loki найден trace_id соответствующего лога, через Tempo получена детализация span'ов:

GET /api/v1/users/me   duration=10.7ms  status=ERROR "gaierror: Temporary failure in name resolution"
http GET (outer span)  duration=11.7ms  status=ok

Диагностика: явный ERROR-статус на конкретном внутреннем span'е + короткая общая длительность = быстрый явный отказ зависимости, а не медленный handler (который дал бы длинную длительность без error-статуса). Разница видна только благодаря раздельным span'ам, не по одной агрегированной метрике latency.

Инцидент 3: telemetry backend (Prometheus+Loki+Tempo) недоступен

docker compose stop prometheus loki tempo. make test остаётся зелёным — бизнес-API не блокируется на отправке телеметрии. В логах Collector — повторяющиеся "Exporting failed. Will retry the request after interval" с нарастающим backoff (4.1с → 6.4с → 7.5с → 9.8с...) для обоих экспортёров (otlphttp/tempo, otlphttp/loki); память Collector осталась на 94 MiB из лимита 200 MiB (внутренний memory_limiter — 150 MiB) — не растёт безгранично, процесс не падает. После docker compose start prometheus loki tempo экспорт возобновился автоматически, без перезапуска Collector.

Инцидент Что ожидаем Что наблюдали
Worker стоп Рост oldest_age_seconds, алерт firing, восстановление после старта Подтверждено; алерт active, backlog обнулился после start worker
PostgreSQL стоп Быстрый явный отказ, отличимый от медленного handler через error-span 500 за ~11мс, span с status=ERROR и конкретным исключением
Telemetry backend стоп API работает, Collector не падает и не растёт безгранично make test зелёный; Collector 94/200 MiB, retry с backoff, автовосстановление

Ограничения и следующие шаги

Найдены и исправлены четыре реальные проблемы в процессе проверки (не поймались бы одной только статической проверкой):

  1. FastAPIInstrumentor.instrument_app() нельзя вызывать в on_startup — Starlette запрещает добавлять middleware после старта приложения (RuntimeError). Исправлено переносом вызова на уровень модуля, сразу после создания FastAPI().
  2. После await call_next(...) активный span уже закрыт — логирование/метрики, написанные после этой строки, не получали trace_id (OTel-инструментация FastAPI сама завершает свой span до возврата управления). Исправлено собственным span'ом, оборачивающим весь вызов call_next, с логированием внутри него.
  3. Метрика очереди "замерзала", если считалась только в worker: пока worker (единственный источник метрики) был остановлен, значение просто не обновлялось, а не росло — то есть именно во время инцидента, который и нужно было увидеть, метрика лгала. Исправлено: та же метрика теперь считается и в API (который остаётся живым во время отказа worker).
  4. XACK+XDEL не атомарны по отдельности — сбой между ними оставлял "фантомные" уже обработанные записи в стриме, искажавшие queue_backlog{metric="depth"}. Исправлено объединением в один Redis pipeline (атомарный MULTI/EXEC).
  5. AsyncPGInstrumentor/RedisInstrumentor были объявлены в зависимостях, но не активированы — обнаружено только при попытке найти DB-span в трейсе для инцидента 2. Исправлено явным вызовом .instrument(...) в app/telemetry.py.

Остальные ограничения:

  • Health-check Grafana→Tempo datasource возвращает "Unable to load datasource metadata" при прямой проверке /health через Grafana API, хотя реальные TraceQL//api/search запросы к Tempo работают корректно (подтверждено напрямую) — возможный edge-case конкретной версии проверки здоровья в Grafana 11.3.1/Tempo 2.6.1, не влияет на функциональность.
  • Трек исследования уровня 5 (цена наблюдаемости / SLO и burn-rate alerts) не реализован.
  • Задания, пересозданные retry_scheduler_loop (lab5) после временного отказа, публикуются без исходного traceparent — новый trace начинается заново на повторной попытке, не связан с исходным upload-трейсом.
  • Alert-правила используют instant-запросы без range/reduce экспрешна, из-за чего Grafana иногда классифицирует срабатывание как DatasourceNoData вместо чистого threshold breach (см. «Инцидент 1»); функционально алерт всё равно переходит в firing/resolved по реальному состоянию системы.