Переиспользован стек 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>
16 KiB
Отчёт — лабораторная 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, автовосстановление |
Ограничения и следующие шаги
Найдены и исправлены четыре реальные проблемы в процессе проверки (не поймались бы одной только статической проверкой):
FastAPIInstrumentor.instrument_app()нельзя вызывать вon_startup— Starlette запрещает добавлять middleware после старта приложения (RuntimeError). Исправлено переносом вызова на уровень модуля, сразу после созданияFastAPI().- После
await call_next(...)активный span уже закрыт — логирование/метрики, написанные после этой строки, не получалиtrace_id(OTel-инструментация FastAPI сама завершает свой span до возврата управления). Исправлено собственным span'ом, оборачивающим весь вызовcall_next, с логированием внутри него. - Метрика очереди "замерзала", если считалась только в worker: пока worker (единственный источник метрики) был остановлен, значение просто не обновлялось, а не росло — то есть именно во время инцидента, который и нужно было увидеть, метрика лгала. Исправлено: та же метрика теперь считается и в API (который остаётся живым во время отказа worker).
XACK+XDELне атомарны по отдельности — сбой между ними оставлял "фантомные" уже обработанные записи в стриме, искажавшиеqueue_backlog{metric="depth"}. Исправлено объединением в один Redis pipeline (атомарныйMULTI/EXEC).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 по реальному состоянию системы.