forked from mtusi2026/mtusi2026lab6
137 lines
23 KiB
Markdown
137 lines
23 KiB
Markdown
# Отчёт — лабораторная 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.
|