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

134 lines
16 KiB
Markdown
Raw 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
- Автор, группа: Сарибекян, БПИ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
```sh
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 по реальному состоянию системы.