Files
mtusi2026lab6/REPORT.md
T

155 lines
28 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
- Автор, группа: [ФИО], [группа]
- Целевая оценка; выбранный трек 5, если нужен: **5**, трек 1 «Цена наблюдаемости»
- Commit/PR: локальный коммит ветки `solution/lab6`; PR — после публикации
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, OpenTelemetry Python SDK 1.45.0 (traces/metrics/logs, OTLP/HTTP), uvicorn, asyncpg, aiobotocore, aio-pika, Pillow; OpenTelemetry Collector contrib 0.161.0, Prometheus 3.15.0, Loki 3.7.8, Tempo 2.9.0, Grafana 13.2.3; RabbitMQ 4.1.8, SeaweedFS 4.48, PostgreSQL 17, Valkey 8, HAProxy 3.0. Код lab5 перенесён, бизнес-API не менялся. Использование ИИ: [заполняется автором]
## Запуск из чистого clone
Prerequisites: Docker Compose v2 (≈ 4 ГБ свободной RAM для всего стенда), bash (Git Bash на Windows), Python ≥ 3.9; на Windows `PYTHONUTF8=1`.
Версии всех образов закреплены тегом и digest в `compose.yaml`; зависимости — `requirements.txt` (включая `opentelemetry-*==1.45.0`).
```sh
sh scripts/init-secrets.sh # secrets/*: БД, S3, RabbitMQ, пароль Grafana (secrets/grafana_admin_password)
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl http://127.0.0.1:8080/health/ready # API
# Grafana: http://127.0.0.1:3000 пользователь admin, пароль — secrets/grafana_admin_password
python3 tests/smoke.py --base-url http://127.0.0.1:8080 # make test (телеметрия включена)
python3 -m unittest discover -s student-tests -p test_observability.py -v # метрики, логи, трассы, связь API -> worker, отсутствие секретов
python3 student-tests/test_observability_retry.py # все попытки задания в одной трассе
python3 research/incidents.py --out evidence # 4 инцидента, алерты firing -> resolved (~10 мин)
python3 research/obs_cost.py --out evidence # трек 1 (~15 мин)
```
Windows: `scripts/restart.cmd`, `scripts/stop-one.cmd`. Остановка с сохранением данных — `docker compose --env-file .env stop`; **намеренное удаление учебных данных** — `docker compose --env-file .env down -v` (volumes `pgdata`, `valkeydata`, `seaweeddata`, `rabbitmqdata`, `promdata`, `lokidata`, `tempodata`, `grafanadata`).
Профиль без телеметрии: `OTEL_ENABLED=0`; head-sampling: `OTEL_TRACES_SAMPLER_ARG=0.1`; tail-sampling в Collector: `COLLECTOR_CONFIG=/etc/otelcol/collector-tail.yaml`.
## Архитектура и решения
```
API ×2 ─┐ ┌─▶ Prometheus (метрики, retention 7 д, volume promdata)
├─OTLP/HTTP─▶ OTel Collector ─┼─▶ Tempo (трассы, retention 7 д, volume tempodata)
worker ─┘ (memory_limiter, batch, └─▶ Loki (логи, retention 7 д, volume lokidata)
scrub, tail_sampling*) ▲
traceparent: API ─▶ outbox ─▶ RabbitMQ ─▶ worker Grafana (127.0.0.1:3000) читает все три источника
```
| Роль | Сервис | Версия | Порты | Volume | Зачем |
| --- | --- | --- | --- | --- | --- |
| Collector | `otel-collector` | contrib 0.161.0 | OTLP 4317/4318, метрики 8888/8889 — **только сеть backend** | — | единая точка приёма, ограничение RAM, удаление чувствительных атрибутов, маршрутизация сигналов; это не хранилище |
| Метрики | `prometheus` | 3.15.0 | не публикуется | `promdata` | временные ряды, SLI/recording rules, alert rules, firing/resolved |
| Логи | `loki` | 3.7.8 | не публикуется | `lokidata` | структурные логи API и worker (OTLP), поиск по `trace_id` |
| Трассы | `tempo` | 2.9.0 | не публикуется | `tempodata` | распределённые трассы, TraceQL |
| UI | `grafana` | 13.2.3 | `127.0.0.1:3000` | `grafanadata` | datasources/dashboard из Git (provisioning), анонимный доступ выключен, пароль — secret |
**Что хранит что.** Grafana ничего не хранит из сигналов: это интерфейс запросов (PromQL, LogQL, TraceQL) и provisioning. Collector — маршрутизатор/обработчик (не БД). Метрики — Prometheus, логи — Loki, трассы — Tempo. Конфигурации (`infra/otel`, `infra/prometheus`, `infra/loki`, `infra/tempo`, `infra/grafana`) и dashboard JSON лежат в Git; провижининг datasources и dashboard автоматический.
### Сигналы и соответствие `contracts/observability.md`
| Сигнал контракта | Реализация (SDK) → имя в Prometheus / место |
| --- | --- |
| HTTP requests; HTTP duration (s) | `http.server.request.duration` (histogram, секунды, buckets 5 мс…10 с) → `http_server_request_duration_seconds_{bucket,sum,count}{http_request_method, http_route, http_response_status_code}`; число запросов = `_count` (отдельный счётчик не дублируется) |
| Jobs processed/failed; duration | `messenger.jobs.processed{job_type,outcome=ready|failed|retried|noop}` → `messenger_jobs_processed_total`; `messenger.job.duration` → `messenger_job_duration_seconds_*` |
| End-to-end time to ready | `messenger.job.time_to_ready` (от приёма до ready) → `messenger_job_time_to_ready_seconds_*` |
| Queue depth / oldest job age | `messenger.queue.depth`, `messenger.queue.oldest_job_age` → `messenger_queue_depth`, `messenger_queue_oldest_job_age_seconds` (считает API, т. е. метрика живёт и при остановленном worker) |
| DB pool used/waiting | `db.client.connections.usage{state}`, `db.client.connections.waiting` → `db_client_connections_usage`, `db_client_connections_waiting` |
| Worker busy/capacity | `messenger_worker_busy`, `messenger_worker_capacity` |
| CPU/RAM процессов | `process_memory_rss_bytes`, `process_cpu_time_seconds_total` (счётчик CPU-времени процесса) |
| Логи API и worker | структурный JSON в stdout **и** OTLP: `ts, level, service.name, msg(event), trace_id, span_id` (при активном спане), `request_id`; resource: `service.name` (`messenger-api`/`messenger-worker`), `service.version`, `service.instance.id`, `deployment.environment.name=lab` |
| Трассы API и worker | server-спан запроса (`HTTP POST /api/v1/…`), `db.connection`, `s3.put_object/get_object`, producer-спан `attachment.process publish`, consumer-спан `attachment.process process` — реальные, не статичные |
| Связь upload → publish → consume → S3/DB | W3C `traceparent/tracestate`: контекст запроса сохраняется в `outbox` (миграция 0006), relay кладёт его в поля сообщения (`jobs.schema.json`) и заголовки AMQP; worker продолжает ту же трассу (consumer — потомок producer; producer — потомок server-спана) |
**Низкая кардинальность.** `user_id/chat_id/message_id/attachment_id/request_id/filename` не используются как labels метрик (проверяет `test_no_high_cardinality_or_secret_labels`); маршрут — шаблон `/api/v1/chats/{chat_id}/messages`. В логах/спанах допустимы технические ID синтетических данных. **Секреты не экспортируются**: токены, пароли, `Authorization`, тела сообщений, изображения, SQL-текст, query-строки — не попадают ни в атрибуты, ни в логи; дополнительно Collector удаляет `http.request.header.authorization`, `db.statement`, `url.query` и т. п. (`attributes/scrub`). Проверка `test_secrets_and_message_bodies_are_not_exported`: уникальный текст сообщения, токен и пароль не находятся ни в Loki, ни в трассе, ни в метриках.
**Health-проверки** LB (раз в секунду) не порождают спанов и access-логов (метрики остаются, исключены из SLI фильтром `http_route!~"/health.*"`); фоновые опросы БД (relay, sweeper) — без корневых спанов (`child_span`).
### Dashboard и SLI/SLO
Dashboard `Messenger: API, очередь, worker` (`infra/grafana/dashboards/messenger.json`, генератор `build_dashboard.py`): RPS по маршрутам и кодам, **доля 5xx**, **p50/p95/p99** (`histogram_quantile` из `sum by (le)` гистограмм всех реплик — не среднее p95), задержки по маршрутам, DB pool (занято/простаивает/ожидают), задания по исходам, p50/p95 длительности обработки и **времени до ready**, глубина очереди, **возраст старейшей задачи**, saturation worker (busy/capacity), RSS/CPU, очередь и отказы экспорта Collector, логи ошибок (Loki), список алертов, последние трассы. Единицы и запросы описаны в подсказках панелей.
- **SLI доступности**: доля бизнес-запросов (все маршруты кроме `/health`) без ответа 5xx. Числитель — 5xx, знаменатель — все запросы без `/health`; 4xx (неверный пароль, чужой чат) в отказ сервиса не входят.
- **SLO**: 99.5 % за окно 30 суток (бюджет ошибок 0.5 %); для демонстрации на локальном стенде окна алертов короткие (rate по 1 мин, `for` 15–20 с).
- Дополнительные SLI: p95 задержки (порог 0.5 с), доля 5xx **на маршруте загрузки** (малообъёмный, но критичный — общий SLI его деградации не заметит), p95 времени до ready.
### Alert rules (`infra/prometheus/rules/messenger.yml`, runbook — `docs/runbooks.md`)
| Алерт | Условие / окно | Для чего |
| --- | --- | --- |
| `HighHttpErrorRate` | 5xx > 5 % при ≥ 0.5 RPS, `for 20s`, rate[1m] | общий отказ сервиса |
| `HighUploadErrorRate` | 5xx на маршруте загрузки > 20 %, `for 15s` | отказ S3/очереди |
| `HighLatencyP95` | p95 > 0.5 с, `for 20s` | медленная БД/обработчик |
| `QueueLagGrowing` | старейшая задача > 30 с, `for 20s` | остановка/перегрузка worker |
| `WorkerSilent` | `absent(messenger_worker_capacity)`, `for 30s` | worker не шлёт метрики |
| `TelemetryExportFailing` | отказы экспорта Collector > 0, `for 15s` | сбой хранилищ телеметрии |
Alerts вычисляет Prometheus; состояние (pending/firing/resolved) видно в Prometheus и на панели «Алерты» dashboard. Внешняя доставка не требуется и не настроена.
### Collector: ограничение ресурсов и поведение при backpressure
`memory_limiter` (limit 280 MiB при лимите контейнера 384 MiB, spike 60 MiB; при приближении данные отклоняются, SDK отбрасывает пакет, приложение продолжает работать), `batch` (1024/2 с), экспортёры с **ограниченной очередью** (`sending_queue` 500) и повторами до 30 с, затем отбрасывание; SDK: очередь спанов/логов 2048, таймаут экспорта 3 с, **ошибки экспорта не влияют на ответы API** (проверено). `metric_expiration: 20s` — остановившийся источник метрик быстро исчезает (алерт `WorkerSilent`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Весь минимум lab5 работает с включённой телеметрией | `tests/smoke.py`; `student-tests/test_pipeline.py` | PASS; 9 тестов OK | `evidence/checks.txt` |
| Collector, 3 хранилища и Grafana в стенде, конфиги в Git, volumes | `docker compose up -d`; `infra/**` | стенд поднимается одной командой; datasources и dashboard импортируются provisioning-ом | `evidence/grafana_provisioning.txt` |
| Метрики RPS/errors/duration API; jobs ok/failed и duration worker | `test_observability.py::test_metrics_for_http_jobs_queue_pool_worker` | все 12 серий имеют данные | `evidence/checks.txt` |
| Структурные логи и реальные трассы API и worker, связь запрос ↔ лог, job ↔ лог | `test_one_trace_spans_…`, `test_logs_are_structured_and_linked_by_trace_id` | одна трасса содержит спаны `messenger-api` и `messenger-worker`; в Loki по `trace_id` находятся логи обоих сервисов, `span_id` у каждой записи | `evidence/checks.txt` |
| Низкая кардинальность, нет секретов | `test_no_high_cardinality…`, `test_secrets_and_message_bodies_are_not_exported` | OK | `evidence/checks.txt` |
| W3C trace context API → broker → worker (parent-child), цепочка до S3/DB, включая retry | `test_one_trace…`; `test_observability_retry.py` | server → producer → consumer; `s3.put/get_object`, `db.connection` в той же трассе; 3 попытки задания — 3 consumer-спана одной трассы, 2 лога `job_rescheduled` | `evidence/checks.txt` |
| Dashboard: p50/p95/p99, error ratio, queue depth/age, DB pool, saturation worker | `infra/grafana/dashboards/messenger.json` | импортируется автоматически (`/api/search` возвращает dashboard) | `evidence/grafana_provisioning.txt` |
| SLI/SLO, alert rules, firing → resolved на искусственных отказах | `research/incidents.py` | см. «Инциденты» | `evidence/incidents.json`, `incidents.png` |
| Collector с memory limiter/batch; остановка хранилища телеметрии не ломает API | инцидент 4 | API без ошибок (ratio 0.0, RPS ≈ 67), очередь Collector ограничена (≈23–28), RSS Collector ≈ 247 MiB < лимита 384 MiB | `evidence/incidents.json` |
| Два+ инцидента с диагностикой | см. ниже | 4 инцидента | отчёт и `evidence/incidents.json` |
| **Трек 1** | `research/obs_cost.py` | см. ниже | `evidence/obs_cost.json` |
## Инциденты (диагностика только по сохранённым наблюдениям)
Фоновая нагрузка: ≈32 запроса/с сообщений и ≈25 загрузок/с (мелкие PNG). `research/incidents.py` — оркестрация и запись состояний алертов.
| № | Воздействие | Алерт (время обнаружения от воздействия) | Разрешён после восстановления | Как найдена причина |
| --- | --- | --- | --- | --- |
| 1 | остановка worker | `QueueLagGrowing` через 64 с (порог 30 с + `for 20 s` + шаг rate); также `WorkerSilent`; каскад: переполнение очереди → backpressure 503 на загрузке → `HighHttpErrorRate`/`HighUploadErrorRate` | через 24 с (очередь рассосалась) | возраст старейшей задачи растёт (56.7 с) при **нулевой** скорости `messenger_jobs_processed_total`, серия `messenger_worker_capacity` исчезла → остановлен worker, а не медленная БД; логи API показывают 503 «Очередь обработки заполнена» |
| 2 | медленная БД (триггер `pg_sleep(0.8)` на вставку сообщений) | `HighLatencyP95` через 72 с (p95 = 0.80 с) | через 46 с | p95 растёт, а в TraceQL `{ name = "db.connection" && duration > 300ms }` и `{ name =~ "HTTP POST.*messages" && duration > 300ms }` найдено по 20 трасс: почти всё время запроса в спанах БД, CPU процессов не растёт → медленная БД, а не обработчик |
| 3 | остановка S3 | `HighUploadErrorRate` через 88 с (доля 5xx на загрузке 32 %; **общая** доля 0.8 % — общий SLI не заметил бы) | через 78 с | `{ status = error }` — спаны `s3.put_object` с ошибкой, 139 логов `s3_put_failed` с `trace_id`; остальные маршруты без ошибок → недоступен S3 |
| 4 | остановка Tempo и Loki | `TelemetryExportFailing` через 49 с | через 85 с | бизнес-метрики API без ошибок (ratio 0.0, RPS ≈ 67), растёт `otelcol_exporter_send_failed_spans` (≈66/с), очередь экспорта ограничена (23), RSS Collector 247 MiB → сбой хранилищ телеметрии, не приложения; метрики Prometheus не потеряны (путь Collector → Prometheus независим), трассы/логи за простой потеряны |
График: `evidence/incidents.png` (возраст очереди, p95, доля 5xx, состояние алертов; серые линии — воздействие, зелёные — восстановление). Время обнаружения включает окно `rate[1m]` — для более быстрой реакции нужны более короткие окна/burn-rate (трек 2, не выбран).
## Эксперименты (трек 1): цена наблюдаемости
**Гипотеза.** Телеметрия имеет измеримую цену в CPU API (SDK: спаны, метрики, логи), которая слабо зависит от head-sampling (логи и метрики остаются), но head-sampling теряет редкие ошибки и медленные запросы пропорционально доле выборки; tail-sampling в Collector сохраняет их почти полностью, перенося цену из хранилища в Collector.
**Методика** (`research/obs_cost.py`, график `evidence/obs_cost.png`). Одинаковая нагрузка во всех профилях: 8 процессов-клиентов, 64 одновременных, 90 % `POST` сообщений + 10 % `GET`, прогрев 5 с, замер 30 с, **2 повтора**; перед профилем пересоздаются Collector, API и worker. В API внедрены отказы (одинаково для всех профилей): 2 % запросов → 500 и 2 % → задержка 0.6 с (`API_FAULT_INJECTION=http500:0.02,slow:0.02:0.6`) — это «редкие ошибки и медленные запросы»; после каждого прогона 25 с на дозапись, затем TraceQL в Tempo считает сохранённые ошибочные (`status = error`) и медленные (`duration > 500ms`) трассы. Число внедрённых отказов считается на стороне клиента. Объём телеметрии — счётчики Collector (`otelcol_receiver_accepted_*`, `otelcol_exporter_sent_spans`). Docker Desktop (WSL2), 2 реплики API по 1 CPU, Collector 384 MiB.
| Профиль | RPS | p95, мс | CPU API (на реплику) | CPU % / пик RAM MiB Collector | спаны: SDK → Tempo | логи (записей) | сохранено ошибочных трасс | сохранено медленных трасс |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| off (`OTEL_ENABLED=0`) | 1340 | 74 | 53 % | 0.1 / 39 | — | — | — | — |
| on: head 100 % | 1324 | 72 | 87 % | 3.1 / 70 | 96 тыс. → 96 тыс. | 47 тыс. | ≈100 % | ≈100 % |
| on: 100 %, очередь SDK 65 536 / пакет 2048 | 1384 | 75 | 84 % | 2.9 / 72 | 96 тыс. → 96 тыс. | 47 тыс. | ≈100 % | ≈100 % |
| on: head 10 % | 1400 | 67 | 77 % | 1.7 / 71 | 9 тыс. → 10 тыс. | 49 тыс. | 13 % | 9 % |
| on: SDK 100 % + tail-sampling в Collector | 1399 | 67 | 85 % | 4.0 / 110 | 101 тыс. → 14 тыс. | 49 тыс. | ≈100 % | ≈100 % |
(RPS и p95 — среднее двух прогонов; различия RPS/p95 между профилями ≤ ±5 % — в пределах разброса между повторами; p99 ≈ 0.62 с во всех профилях определяется внедрённой задержкой 0.6 с. Объём — за окно 30 с нагрузки + дозапись. «Сохранено» считается как число трасс с ошибкой/медленных в Tempo к числу внедрённых: значение ≈100 % означает, что потерь не обнаружено; точное отношение немного >100 % из-за 5 с прогрева, попавших в окно поиска.)
**Результаты и выводы.**
1. **Цена в CPU.** Включение телеметрии поднимает CPU API с **53 % до 87 %** одного ядра при той же пропускной способности (+34 п. п., ≈ +60 % CPU на запрос); пропускная способность и p95 на этом профиле не изменились в пределах погрешности, потому что запас CPU у реплик (лимит 100 %) не исчерпан — на насыщенной системе цена перешла бы в потерю RPS. RSS API +≈12 MiB; Collector — 3–4 % CPU и 71 MiB RAM (110 MiB при tail-sampling: буфер трасс).
2. **Объём.** 100 %: ≈96 тыс. спанов и ≈48 тыс. записей логов за окно. **Head 10 %** сокращает спаны на 90 % (9.9 тыс.), но **логи (≈49 тыс.) и метрики не меняются**, поэтому CPU API снижается лишь до 77 % (−10 п. п.): большая часть цены — логи и метрики, а не трассы. **Tail-sampling**: SDK по-прежнему шлёт 100 % спанов (CPU API 85 %), но в Tempo уходит ≈15 тыс. из 101 тыс. (−85 % хранения).
3. **Потери редких событий.** Head 10 % сохраняет лишь **≈13 % ошибочных и ≈9 % медленных** трасс (ровно доля выборки): 87–91 % редких ошибок и медленных запросов невидимы в Tempo (метрики и логи при этом их фиксируют). 100 % и tail-sampling сохраняют ≈100 % ошибочных и медленных трасс; tail выигрывает по хранилищу при почти той же цене в API.
4. **Увеличение очереди SDK** (65 536 / пакет 2048) не изменило ни объём, ни долю сохранённых трасс: потерь спанов на стороне SDK в этой нагрузке не было.
5. **Находка по дороге.** В первом прогоне «100 %» сохранялось только ≈57 % ошибочных трасс: Tempo с настройками по умолчанию **отбрасывал ≈29 % спанов** (`tempo_discarded_spans_total{reason="live_traces_exceeded"}`: 224 тыс. из 767 тыс.) из-за лимита «живых» трасс (10 000 на тенанта). Лимиты подняты в `infra/tempo/tempo.yaml` (`overrides.defaults.ingestion`), повторные прогоны — без потерь; цена — память Tempo: при лимите контейнера 512 MiB он был убит OOM (код 137) на тестах после нагрузки, поэтому `mem_limit` Tempo увеличен до 1 GiB. Вывод: потери надо искать метриками самих хранилищ, а не только Collector.
**Сбалансированная конфигурация (проверена):** SDK 100 % + **tail-sampling** в Collector (все ошибки, все запросы >500 мс, 10 % остальных): редкие проблемные трассы сохраняются полностью, хранилище трасс экономится на 85 %, цена — CPU SDK как при 100 % и ≈ +40 MiB RAM Collector. Если CPU API критичен — снижать объём логов (access-log без health уже отключён) и использовать head-sampling только для трасс успешных запросов.
**Ограничения методики.** Единичный ноутбук; 2 прогона на профиль; запас CPU API не исчерпан (RPS не падает) — цена показана в CPU, а не в RPS; доля сохранённых трасс оценивается TraceQL-поиском с лимитом 5 000 результатов (для «всех HTTP-трасс» лимит достигнут, для ошибочных/медленных — нет); размер дисковых томов Tempo/Loki не используется как метрика: он меняется компакцией и flush-ом и недостоверен на таких интервалах.
## Ограничения и следующие шаги
- Выдерживается: недоступность Tempo/Loki/Collector без влияния на API (данные трасс/логов за простой теряются, метрики — нет). Не выдерживается: потеря volume хранилищ телеметрии; Prometheus/Loki/Tempo — по одному экземпляру.
- Алерты локальные (без доставки наружу); окна коротки для демонстрации — для production нужны burn-rate по нескольким окнам.
- Логи в stdout остаются в docker json-file (ротация 10 МБ × 3) и дублируются в Loki; `trace_id` присутствует в обоих.
- Подтверждено экспериментами: связность трасс через очередь, алерты firing/resolved на 4 отказах, цена телеметрии. Гипотеза без доказательства: поведение при >2 репликах API и при нагрузке порядка тысяч RPS на одном Collector.