forked from mtusi2026/mtusi2026lab6
Переиспользован стек 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>
134 lines
16 KiB
Markdown
134 lines
16 KiB
Markdown
# Отчёт — лабораторная 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 по реальному состоянию системы.
|