Files
mtusi2026lab6-fork/REPORT.md
T

137 lines
23 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**; трек 5 не заявляется
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: OpenTelemetry Python SDK 1.29.0 (`opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http`), инструментации 0.50b0 (`fastapi`, `psycopg`, `botocore`); OpenTelemetry Collector contrib 0.115.1, Prometheus 2.55.1, Loki 3.3.2, Tempo 2.6.1, Grafana 11.4.0. Документация: OTel Collector configuration (memory_limiter, batch, sending_queue/retry_on_failure), W3C Trace Context, OTel messaging semantic conventions (producer/consumer, `messaging.*`), HTTP semconv (`http.server.request.duration`), Prometheus histograms / `histogram_quantile`, Loki OTLP ingestion (structured metadata), Grafana provisioning. Остальной стек — как в lab5 (см. `docs/lab5/REPORT.md`). Помощь ИИ (Claude) — при проектировании схемы сигналов, написании `src/telemetry.py`, конфигураций, dashboard, alert rules, сценариев инцидентов и отчёта.
Минимум lab5 перенесён целиком (HAProxy, 2 реплики API, PostgreSQL, Redis-кэш, SeaweedFS S3, Redis Streams broker, worker, outbox, retry/DLQ). **Бизнес-API не менялся**; новые поля только служебные: `traceparent`/`tracestate` в сообщении задания (уже разрешены `contracts/jobs.schema.json`).
## Запуск из чистого clone
**Версии.** API и worker — один образ из `Dockerfile` (`python:3.12.7-slim-bookworm`), `postgres:16.4-alpine`, `redis:7.4.1-alpine` (кэш и broker), `haproxy:2.8.30-alpine`, `chrislusf/seaweedfs:4.50`, **`otel/opentelemetry-collector-contrib:0.115.1`, `prom/prometheus:v2.55.1`, `grafana/loki:3.3.2`, `grafana/tempo:2.6.1`, `grafana/grafana:11.4.0`**. Нужны Docker с Compose v2 и Python 3.9+ на хосте. Оркестрация — Compose.
```sh
make up # = python scripts/init_secrets.py; cp .env.example .env;
# docker compose --env-file .env up -d --build; ожидание готовности API/S3/worker
make test # публичный smoke через LB http://localhost:8080
make obs-urls # Grafana http://127.0.0.1:3000 (admin / secrets/grafana_admin_password), Prometheus :9090
make down # безопасная остановка, все volumes сохраняются
make destroy # НАМЕРЕННОЕ удаление всех данных (down -v): БД, S3, очередь, история телеметрии
```
Bootstrap: секреты (`secrets/`, вне Git) создаёт `scripts/init_secrets.py`, в т.ч. новый `grafana_admin_password`. Миграции — one-shot `migrate`, бакет — `s3-init` (как в lab5). Provisioning Grafana (datasources + dashboard) и rules Prometheus подключаются из Git read-only при старте — ручной набор не нужен. Повторный `make up` идемпотентен.
## Архитектура и решения
```
клиент -> HAProxy -> API x2 ──SQL──> PostgreSQL (источник истины, job_outbox)
│ └─S3──> SeaweedFS
└─outbox relay─XADD(traceparent)─> broker (Redis Streams) ─> worker ─S3/SQL─> ...
API/worker ──OTLP/HTTP :4318──> otel-collector ─┬─ traces ─OTLP gRPC─> Tempo (volume tempodata)
├─ metrics ─/metrics :8889 <─scrape─ Prometheus (promdata, rules)
└─ logs ─OTLP /otlp─> Loki (lokidata)
Grafana (grafanadata) читает все три
```
| Роль | Сервис | Образ | Назначение | Volume | Порт наружу |
| --- | --- | --- | --- | --- | --- |
| Collector | `otel-collector` | contrib 0.115.1 | приём OTLP, memory_limiter, batch, ограниченные очереди, экспорт | — (не хранилище) | нет |
| Метрики | `prometheus` | v2.55.1 | TSDB метрик 7 д, вычисление recording/alert rules, состояние firing/resolved | `promdata` | 127.0.0.1:9090 |
| Логи | `loki` | 3.3.2 | хранение логов 7 д; индекс только по `service_name`/`service_instance_id`, остальное — structured metadata | `lokidata` | нет |
| Трассы | `tempo` | 2.6.1 | хранение spans 72 ч, поиск TraceQL | `tempodata` | нет |
| UI | `grafana` | 11.4.0 | запросы и dashboard; сама сигналы не хранит | `grafanadata` | 127.0.0.1:3000 |
**Почему три хранилища.** Метрика отвечает «сколько и как часто» (дёшево, агрегаты, алерты), но не «какой запрос»; лог отвечает «что именно произошло и почему» в одном процессе; trace отвечает «где ушло время» по цепочке процессов. Prometheus хранит числовые ряды с метками, Loki — строки с минимальным индексом, Tempo — деревья spans по trace_id.
**Инструментация (`src/telemetry.py`).** Вызывается до создания пула БД/клиента S3:
- Resource: `service.name` = `messenger-api` / `messenger-worker`, `service.version` = `APP_VERSION`, `service.instance.id` = `X-Instance-Id` (hostname контейнера), `deployment.environment.name=lab`.
- Traces: FastAPI (SERVER span, только шаблон маршрута; health исключены; внутренние send/receive spans отключены), psycopg (SQL **без параметров**), botocore (S3). Redis **не** инструментируется: команды `AUTH` и ключи кэша сессий не должны попасть в spans. Sampler `DropOrphanClientSpans`: CLIENT-span без родителя не сохраняется — это фоновые SQL/S3 (sweeper outbox раз в секунду, GC, readiness, callbacks метрик), иначе Tempo заполнялся бы тысячами пустых трасс. Всё внутри SERVER/PRODUCER/CONSUMER сохраняется (ParentBased AlwaysOn).
- Logs: JSON в stdout (для `docker logs`) и OTLP. Поля: `timestamp`, `severity`, `service.name`, `event`, `trace_id`, `span_id` (если есть активный span), плюс технические поля (`request_id`, `http_route`, `outcome`...). Каждый бизнес-запрос даёт строку `event=http.request` с шаблоном маршрута, статусом, длительностью и `request_id`; каждое сообщение worker'а — `event=job.processed`.
- `X-Request-Id` записывается атрибутом `messenger.request_id` в SERVER span: ответ с ошибкой → trace → лог.
**Перенос контекста через очередь (W3C).** `job_payload()` записывает `traceparent` текущего span в JSON задания, который хранится в `job_outbox` (PostgreSQL) — контекст переживает задержку публикации и рестарты. Relay (быстрый путь API или sweeper любого процесса) создаёт **PRODUCER** span `attachments.jobs publish` — ребёнок span'а из строки outbox — и кладёт в брокер уже его `traceparent`. Worker создаёт **CONSUMER** span `attachments.jobs process` — ребёнок producer. Внутри него — SQL claim/complete и S3 GetObject/PutObject. При временной ошибке `retry_or_fail()` пишет новую строку outbox с `traceparent` consumer span → следующая попытка в **той же** трассе (связь parent-child, а не link: одна логическая операция «upload → ready»).
**Сигналы и их реальные имена в Prometheus** (Collector `prometheus` exporter: точки → `_`, единица → суффикс, counter → `_total`; `job` = service.name, `instance` = service.instance.id):
| Логический сигнал (contracts/observability.md) | Имя OTel | Имя в Prometheus | Атрибуты | Ед. |
| --- | --- | --- | --- | --- |
| HTTP requests (counter) | `http.server.request.duration` (count) | `http_server_request_duration_seconds_count` | `http_request_method`, `http_route` (шаблон), `http_response_status_code` → класс через `label_replace` | шт |
| HTTP duration | `http.server.request.duration` | `http_server_request_duration_seconds_bucket` | те же; buckets 5 мс…10 с (View) | с |
| Jobs processed/failed | `messenger.jobs.processed` | `messenger_jobs_processed_total` | `job_type`, `outcome` = succeeded/retry/failed/noop/lease_lost/poison/error | шт |
| Job duration | `messenger.job.duration` | `messenger_job_duration_seconds_bucket` | `job_type`, `outcome`; buckets 50 мс…60 с | с |
| Queue depth | `messenger.queue.depth` | `messenger_queue_depth` | `queue`, `state`=queued/processing | шт |
| Oldest job age | `messenger.queue.oldest_age` | `messenger_queue_oldest_age_seconds` | `queue` | с |
| Outbox backlog | `messenger.outbox.pending` | `messenger_outbox_pending` | `queue` | шт |
| DB pool | `messenger.db.pool.connections` / `.waiting` / `.max` | `messenger_db_pool_connections{state=used\|idle}`, `messenger_db_pool_waiting`, `messenger_db_pool_max` | — | шт |
| Worker saturation | `messenger.worker.busy` / `.capacity` | `messenger_worker_busy`, `messenger_worker_capacity` | — | слоты |
| CPU / RAM процесса | `process.cpu.time`, `process.memory.rss` | `process_cpu_time_seconds_total`, `process_memory_rss_bytes` | — | с, байты |
| End-to-end time to ready | `messenger.attachment.time_to_ready` | `messenger_attachment_time_to_ready_seconds_bucket` | `job_type`; от COMMIT задания (ответ 202) до COMMIT ready | с |
| Публикации relay | `messenger.jobs.published` | `messenger_jobs_published_total` | `job_type` | шт |
Глубина/возраст очереди считаются из PostgreSQL (источник истины) и публикуются **API-репликами**: при остановленном worker метрика продолжает жить. Реплики дают одинаковые значения — в запросах `max()`. В метках **нет** user_id/chat_id/message_id/attachment_id/request_id/URL/filename. Технические ID (job_id, attachment_id, request_id) есть только в атрибутах spans и логов — они нужны для поиска конкретного upload, данные синтетические.
**Что не экспортируется:** тела сообщений, байты изображений, filename (в логах/spans нет), заголовки Authorization/Cookie (инструментация их не пишет), параметры SQL (`db.statement` — шаблон с `%s`), подписанные URL (их нет в API), пароли/токены. Проверено: `grep` по всем выгруженным spans/логам локального прогона на `Authorization|Bearer |password` — 0 совпадений.
**Перцентили** считаются только из histogram: `histogram_quantile(0.95, sum by (le) (rate(..._bucket[5m])))` — buckets всех реплик суммируются, а не усредняются p95 реплик. Важная найденная ошибка: инструментация 0.50b0 при метрике в секундах ставит buckets по умолчанию 0…10000 (миллисекундные) — все запросы попадали бы в первый bucket; заданы явные buckets через View.
**SLI/SLO** (`infra/prometheus/rules/messenger.yml`, recording rules):
- доступность: `1 − 5xx/все` бизнес-запросы, health исключены, 4xx не ошибка сервиса; **SLO 99% за скользящий 1 ч**;
- задержка: доля запросов быстрее 0.5 с (bucket `le="0.5"`); **SLO 95% за 1 ч**;
- очередь: возраст старейшего незавершённого задания; цель < 60 с.
**Alert rules** (состояние — Prometheus `/alerts`, Grafana; доставка наружу не нужна), runbook — [docs/runbooks.md](docs/runbooks.md):
| Alert | Условие | Окно / for |
| --- | --- | --- |
| `ApiHighErrorRate` | доля 5xx > 5% и трафик ≥ 0.2 RPS | rate 1m, for 1m |
| `QueueLagGrowing` | `max(messenger_queue_oldest_age_seconds) > 60` | for 30s |
| `TelemetryExportFailing` | растут `otelcol_exporter_send_failed_*` / `enqueue_failed_*` | rate 1m, for 1m |
**Collector и ограниченная буферизация** (`infra/otel/collector.yaml`): `memory_limiter` (180 MiB, spike 40) → `batch` (512/1024, 2 с) → exporters с `sending_queue` **20 батчей** и `retry_on_failure` не дольше 60 с; `GOMEMLIMIT=200MiB`, лимит контейнера 384M. Переполнение очереди → отбрасывание с подсчётом (`otelcol_exporter_enqueue_failed_*`). На стороне SDK: `BatchSpanProcessor`/`BatchLogRecordProcessor` с очередью 2048, таймаут экспорта 5 с; при недоступном Collector батч отбрасывается, ошибки SDK — одна JSON-строка в stdout без трейсбека и **не** в OTLP (иначе петля «лог о неудачной отправке логов»). Ни API, ни worker не имеют `depends_on` на телеметрию.
**Переменные `.env.example` → конфигурация:** `OTEL_SDK_DISABLED` (выключатель), `OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318`, `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=lab`; `OTEL_SERVICE_NAME` задаётся в compose отдельно для API и worker. `GRAFANA_PORT`, `PROMETHEUS_PORT` — порты UI на 127.0.0.1. Остальное — как в lab5.
**Что изменено относительно lab5:** `src/telemetry.py` (новый); `src/main.py` (setup, FastAPI-инструментация, access-лог, метрики пула/очереди), `src/worker.py` (consumer span, метрики заданий/пула/занятости, time-to-ready), `src/outbox.py` (producer span, повторная инъекция контекста), `src/jobs.py` (`traceparent` в payload, `complete()` возвращает время до ready); `requirements.txt` (+OTel); `compose.yaml` (+5 сервисов, сеть `telemetry`, 4 volume, OTEL_* env); `infra/{otel,prometheus,loki,tempo,grafana}`; `scripts/incident.py`, `scripts/alerts_watch.py`; Makefile (`obs-*`, `incident-*`, `alerts-watch`, `destroy`); `docs/runbooks.md`. Отчёт lab5 и его доказательства перенесены в `docs/lab5/`.
## Доказательства критериев
**Важно о среде.** Доказательства в `evidence/local-sandbox/` получены в песочнице **без доступа к Docker Hub**: те же исходники запускались напрямую (Python 3.13, PostgreSQL 16.2, Redis 6.2, S3-эмулятор moto вместо SeaweedFS, 1 реплика API без HAProxy) с **настоящими** бинарниками Collector 0.115, Prometheus 2.55.1, Loki 3.3.2, Tempo 2.6.1 и **конфигурациями из этого репозитория**. Grafana там не запускалась (дистрибутив недоступен) — все PromQL-запросы dashboard выполнены через Prometheus API (0 ошибок), LogQL/TraceQL — через API Loki/Tempo. **Docker-стенд**: Windows 10, Ryzen 5 7500f, 32 GB; доказательства в корне `evidence/`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke при включённой телеметрии | `make test` | `PASS: lab6 public API scenario` | `evidence/local-sandbox/smoke.txt` |
| `make check` | `make check` | `PASS: offline skeleton structure` | — |
| API и worker отдают OTLP в Collector; три хранилища | `make obs-probe` → Loki/Tempo API | лог `event=http.request` с `trace_id` в Loki; trace с тем же id в Tempo | `trace_retry_chain.txt` |
| RPS/errors/duration API; jobs success/error и duration worker | dashboard, Prometheus API | все 31 PromQL dashboard возвращают данные | `metric_names.txt` |
| Структурные логи с trace_id/span_id | Loki `{service_name=~"messenger-.+"} \| request_id="<id>"` | API `http.request` и worker `job.processed` одного upload — один `trace_id` | `trace_retry_chain.txt` |
| Импортируемый dashboard | `infra/grafana/dashboards/messenger.json` + provisioning | загружается при старте Grafana, папка Messenger | — |
| Нет секретов/тел сообщений в telemetry | grep выгрузки spans/logs | 0 совпадений `Authorization`, `Bearer `, `password`; SQL без параметров | — |
| Уровень 4: W3C через broker, producer/consumer, retry, S3/DB | upload `fault-transient-until-3.png` при `WORKER_FAULTS=true` | SERVER → PRODUCER → CONSUMER(retry) → PRODUCER → CONSUMER(retry) → PRODUCER → CONSUMER(succeeded) → S3.PutObject×4, SQL — одна трасса из 76 spans | `trace_retry_chain.txt`, `trace_upload_chain.txt` |
| p50/p95/p99, ошибки, queue depth/age, DB pool, saturation worker | dashboard «Messenger lab6» | панели с единицами (s, percentunit, reqps, bytes) | `messenger.json` |
| SLI/SLO и окно; alert error rate | `make incident-db` + `make alerts-watch` | lock 180 с: pending +60 с, **firing +120 с**, **resolved** через 21 с после снятия lock | `alerts_db_lock_180s.txt` |
| Alert queue lag | `make incident-worker` + `make alerts-watch` | queued растёт, `QueueLagGrowing` pending → **firing** → **resolved**; 22 upload'а готовы через 8.7 с после старта worker | `alerts_queue_lag_and_db_short.txt`, `incident_worker_stop.jsonl` |
| Медленная БД отличима от медленного handler | `make incident-db` | 503 только на `/messages`; CLIENT span `INSERT` 5.01 с `QueryCanceled` | `db_lock_span.txt` |
| Collector memory limiter/batch, недоступный backend | `make incident-telemetry` (`SERVICES=otel-collector` и `SERVICES=tempo,loki`) | API 0 ошибок, ~300 RPS; RSS API 135.0→135.4 MiB; Collector пик 234 MiB, очередь 20/20, потери посчитаны | `telemetry_outage.txt` |
## Эксперименты и отказы
Локальная песочница: 1 реплика API (без LB), 1 worker (2 потока), нагрузка `tests/load.py` (closed loop, POST сообщений, 2–4 потока), ~300 успешных RPS. **Docker-стенд**: Windows 10, Ryzen 5 7500f, 32 GB; доказательства в корне `evidence/`.
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
| --- | --- | --- | --- |
| Worker остановлен 110 с, upload каждые 5 с | 202 продолжаются; queue depth и oldest age растут; QueueLagGrowing firing | queued до 22, age > 90 с, firing; API без ошибок | старт worker → все 22 ready за 8.7 с, alert resolved; потерь нет |
| `LOCK TABLE messages` 180 с под нагрузкой | 503 на `/messages` после `statement_timeout` 5 с; ApiHighErrorRate firing; trace показывает SQL | доля 5xx = 100% на маршруте; firing через 120 с; SQL span 5.01 с `QueryCanceled` | resolved через 21 с после снятия lock; запросы с 503 не записаны (клиент повторяет с тем же Idempotency-Key) |
| Collector остановлен 45 с | API работает, RAM не растёт, телеметрия за период теряется | 0 ошибок, 303 RPS; RSS 135.0 → 135.4 MiB | после старта экспорт возобновился; spans/логи/метрики за 45 с потеряны (SDK отбрасывает) |
| Tempo + Loki остановлены 120 с (Collector жив) | очередь Collector заполняется и ограничена; потери считаются | queue 20/20; `enqueue_failed_spans` 131083, `..._log_records` 22016; пик RSS 234 MiB; API 0 ошибок | после старта backend очередь → 0, новые trace/логи видны; потеря — посчитанное число |
Детекция ошибок не мгновенная: `rate(...[1m])` первую минуту «разбавлен» трафиком до инцидента (при closed-loop нагрузке RPS падает в сотни раз), поэтому pending наступает примерно через 60 с, firing — ещё через `for: 1m`. Инцидент короче ~2 мин до firing не доходит (наблюдалось на lock 100 с — только pending). Это осознанный компромисс против ложных срабатываний; для быстрой детекции нужны burn-rate alerts с короткими окнами (трек 5, не заявлен).
## Ограничения и следующие шаги
- Весь стенд на одном Docker-host; Collector, Prometheus, Loki, Tempo — по одному экземпляру без репликации. Потеря host = потеря телеметрии и приложения.
- При недоступном Collector телеметрия за этот период теряется (SDK держит только ограниченную очередь в памяти) — так сделано намеренно: приложение важнее телеметрии.
- Метрики очереди публикуют API-реплики: если упадут все API, метрика пропадёт (alert на отсутствие данных не настроен).
- Sampling 100% (кроме фоновых сиротских SQL) — на учебной нагрузке приемлемо; цену наблюдаемости и tail sampling не исследовал (трек 5 не заявлен).
- Метрики `process_*` — RSS/CPU процесса, а не cgroup контейнера; для контейнеров можно добавить cAdvisor.