Files
mtusi2026lab6/REPORT.md

130 lines
21 KiB
Markdown
Raw Permalink 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
- Целевая оценка: **5**; трек 5: **трек 1 «Цена наблюдаемости»**
- Commit/PR: ветка `lab6`, коммиты `lab6: ...`; PR — после публикации
- Источники и помощь ИИ: код стенда и сценариев написан с помощью ИИ-агента (omp/Claude); первичные источники — документация Collector 0.128.0, Prometheus 3.4.1, Grafana 12.0.2, Loki 3.5.1, Tempo 2.8.1, OpenTelemetry JS SDK 2.0.1. Все числа ниже получены на этом стенде, старые цифры lab4/lab5 не использованы.
## Запуск из чистого clone
Prerequisites: Docker 29.9.2, Compose 5.6.1, Python 3.9+ (проверено 3.14.8), `openssl`, свободные порты 8080, 8404, 9090, 3000 (loopback). Хост: 8 логических ядер, 15 GiB RAM, один хост.
```sh
make init-env # .env и secrets/* (в т.ч. grafana_admin_password); существующие не перезаписываются
docker compose --env-file .env config --quiet
make stand-up # up -d --build --wait (миграции — one-shot migrate)
make wait-ready && make test
python3 scripts/lab6/verify.py ready --backend-only
make lab6-ready lab6-correlate lab6-signals lab6-redaction lab6-history
make lab6-incident-worker lab6-incident-db lab6-incident-telemetry lab6-track1
```
Grafana: `http://localhost:3000`, пользователь `admin`, пароль — в файле `secrets/grafana_admin_password` (значение не публикуется). Prometheus: `http://localhost:9090`. Остальные backend-порты наружу не публикуются.
Безопасная остановка: `make stand-down` (тома сохраняются). Намеренное удаление учебных данных: `docker compose --env-file .env down -v` (удаляет все named volumes, включая историю телеметрии).
Dashboard JSON генерируются `python3 scripts/lab6/gen_dashboards.py` (и лежат в Git); правила проверяются `promtool` (команды в `evidence/lab6/summary.md`).
Версии: Collector contrib `0.128.0@sha256:1ab0baba…`, Prometheus `v3.4.1@sha256:9abc6cf6…`, Loki `3.5.1@sha256:a7459453…`, Tempo `2.8.1@sha256:bc9245fe…`, Grafana `12.0.2@sha256:b5b59bfc…`, HAProxy `3.2-alpine@sha256:254e6370…` (3.2.26, `USE_PROMEX=1` подтверждён `haproxy -vv`), RabbitMQ `4.1.8-alpine` (плагин `rabbitmq_prometheus`). SDK: `@opentelemetry/sdk-trace-base|sdk-metrics|resources|core` 2.0.1, exporters/logs 0.203.0, api 1.9.0, semantic-conventions 1.45.0; app image `mtusi-messenger:lab6` (`sha256:825b6a72…`). Полные digest — `compose.yaml`.
## Архитектура и решения
API ×2 и worker → OTLP/HTTP (protobuf) → Collector (`memory_limiter` 204 MiB → `attributes/scrub` → `batch`) → Tempo (traces, OTLP gRPC), Loki (logs, OTLP), Prometheus (metrics, OTLP receiver) → Grafana. Collector не долговременное хранилище; каждое хранилище имеет named volume и retention 7 дней. Метрики API/worker приходят только по OTLP; HAProxy (PROMEX `:8404/metrics`), RabbitMQ (`:15692`), Loki, Tempo и сам Collector — scrape. Приложение **не зависит** от Collector (`depends_on` нет): `evidence/lab6/no-collector-start.txt`.
Изменения в коде приложения: (1) `trace_sampled` в stdout JSON и OTLP-атрибутах лога (из `traceFlags`), чтобы отличать намеренный sampling от потери; (2) `time_to_ready` теперь записывается в момент commit ready (до post-commit fault, ACK и cleanup) от `job.created_at` — транзакционной метки durable acceptance (остаточная погрешность — время до COMMIT; жёсткий crash по-прежнему может потерять неэкспортированную телеметрию). Спеки: `logger.spec.ts`, `job-processor.service.spec.ts`.
Найденные дефекты стенда: при отсутствующем Collector DNS-lookup `otel-collector` блокировал пул libuv на 5–7 с и давал 503 (исправлено `UV_THREADPOOL_SIZE=32` и `dns_opt timeout:1 attempts:1` у api/worker); `s3-init` убивался OOM на 128m (лимит 256m).
Соответствие `.env.example` → конфигурация: управляющие `OTEL_*`/`LOG_LEVEL` явно прокинуты в `api.environment`/`worker.environment` (OTEL_SERVICE_NAME — литералы `messenger-api`/`messenger-worker`); лимиты backend — `OTELCOL_*`, `PROMETHEUS_*`, `LOKI_*`, `TEMPO_*`, `GRAFANA_*`.
### Таблица сигналов (живой стенд, `evidence/lab6/signals.json`, `metric-names.txt`)
| Логический сигнал | Метрика | Labels | Unit |
| --- | --- | --- | --- |
| HTTP count/duration | `http_server_request_duration_seconds_{count,bucket,sum}` | `http_request_method`, `http_route`, `http_response_status_code` | s |
| Jobs | `messenger_jobs_processed_total` | `job_type`, `outcome` (succeeded/retry/failed/…) | {job} |
| Job duration | `messenger_job_duration_seconds_*` | `job_type`, `outcome` | s |
| Time to ready | `messenger_attachment_time_to_ready_seconds_*` | `job_type` | s |
| Queue depth / oldest age | `messenger_jobs_queue_depth`, `messenger_jobs_queue_oldest_age_seconds` | `state` / — | {job} / s |
| Outbox | `messenger_outbox_pending`, `messenger_outbox_oldest_age_seconds` | — | {message} / s |
| DB pool | `db_client_connection_count/max/pending_requests`, `db_client_connection_wait_time_seconds_*` | `db_client_connection_state`, `pool_name` | {connection} / s |
| DB операции | `db_client_operation_duration_seconds_*` | `db_operation_name`, `db_query_summary` | s |
| Worker | `messenger_worker_jobs_active`, `messenger_worker_jobs_capacity` | — | {job} |
| Broker publish | `messenger_broker_published_total` | `outcome` | {message} |
| Экспорт телеметрии | `messenger_telemetry_export_items_total` | `signal` (traces/logs), `outcome` (success/failed) | {item} |
| Process | `process_cpu_time_seconds_total`, `process_memory_usage_bytes`, `v8js_memory_heap_used_bytes`, `nodejs_eventloop_delay_p99_seconds` | `cpu_mode` | s / By |
Запрещённых labels (user/chat/message/attachment/request id, URL, filename) нет; route — шаблон `/api/v1/chats/{chat_id}/messages`. Buckets из `instruments.ts`: HTTP 5 мс…30 с (0.25 с — граница), jobs 0.05…120 с, time-to-ready 0.25…600 с. Границы измерений: queue age — возраст старейшей незавершённой задачи (PostgreSQL, snapshot обеих реплик, агрегируется `max`); time-to-ready — acceptance→commit ready.
Propagation: W3C `traceparent` в AMQP-заголовках; цепочка HTTP SERVER → DB CLIENT/`jobs.accept_upload` → PRODUCER `publish` → CONSUMER `process` (worker, parent = PRODUCER) → S3/DB CLIENT; retry — отдельные CONSUMER-spans в той же трассе с `messenger.job.attempt` 1,2,3… (`correlation-*.json`).
### SLI и alerts
SLI availability = (все бизнес-запросы − 5xx) / все бизнес-запросы, `job="messenger-api"`, `http_route!~"/health.*|/internal/.*"`, окно 5m, цель ≥99.5% (учебная). 4xx — good. Без трафика — N/A. Правила: `infra/prometheus/rules/{recording,alerts}.yml`, тесты `infra/prometheus/tests/alerts.test.yml` (SUCCESS). Alerts: `MessengerApiHighErrorRate` (>5% при >0.1 rps, for 30s), `MessengerJobsQueueLagGrowing` (max oldest age >30 s и max depth ready|delayed >0, for 30s). Runbooks: `docs/runbooks/MessengerApiHighErrorRate.md`, `…/MessengerJobsQueueLagGrowing.md`.
## Доказательства критериев
Evidence — под `evidence/lab6/`; навигация — `evidence/lab6/summary.md`.
| Критерий | Команда | Фактический результат | Файл |
| --- | --- | --- | --- |
| 3: smoke | `make test` | PASS (с телеметрией и без Collector) | `regression/check-validate-test.txt`, `no-collector-start.txt` |
| 3: Collector+3 хранилища+Grafana в стенде, конфиги в Git, volumes | `make stand-up`; `verify.py ready` | PASS; три datasource, 2 rules, 2 dashboard загружены provisioning | `ready.json` |
| 3: OTLP метрики/логи/трассы API и worker, RPS/errors/duration, jobs | `make lab6-signals` | PASS, 23 логических сигнала, оба сервиса | `signals.json`, `metric-names.txt` |
| 3: нет секретов/тел в telemetry | `make lab6-redaction` | PASS: 677 элементов просканировано, 0 утечек, coverage полный | `redaction.json/.txt` |
| 3: запрос → trace ↔ лог; job → worker trace и лог | `make lab6-correlate` | PASS | `correlation-http.json`, `correlation-upload.json` |
| 3: UI | Grafana в owned Chromium: dashboards, log→trace, trace→logs, DB span | 7 просмотренных скриншотов | `screenshots/` |
| 4: W3C context, retry, S3/DB | `make lab6-correlate` | attempts 1,2,3 разные span ID; failed — terminal | `correlation-retry.json`, `correlation-failed.json` |
| 4: p50/p95/p99, errors, queue, pool, saturation | dashboard `messenger-overview` | панели с запросами и units | `infra/grafana/dashboards/` |
| 4: SLI/SLO, 2 alerts | `promtool test rules` + incidents | firing→resolved в обоих инцидентах | `incident-worker.json`, `incident-db.json` |
| 4: memory_limiter/batch/очереди, outage backend | `make lab6-incident-telemetry` | PASS ×2 (Tempo, Collector) | `incident-telemetry-1/2.json` |
| 4: два инцидента + диагностика | `make lab6-incident-worker lab6-incident-db` | PASS | `incident-*.json` |
| 5: трек 1 | `make lab6-track1` | PASS, p25 выбран и провалидирован | `track1/` |
| История/persistence backend | `make lab6-history` | старые sample/log/trace читаются после restart | `history.json` |
| Регрессия lab1–5 | `make check validate test test-e2e test-dependencies test-persistence test-failover lab5-demo`; `npm test` | PASS: e2e 44 passed/9 skipped; dependencies 7/7; persistence (hook рестартует и postgres redis s3 broker api worker haproxy, и otel-collector prometheus loki tempo grafana); failover (0 failed attempts, recovery 3.3 s); lab5-demo; npm 89/89 | `regression/` |
| Холодный старт | отдельный clone коммита `d558148`, проект `lab6-cold`, порты 18080/18404/15432/16379/19000/19091/13000 (19090 занят чужим процессом) | `make stand-up`, `test`, `lab6-ready`, `lab6-correlate`, `lab6-signals` PASS; dashboards/datasources появились автоматически; проект удалён `down -v` только для `lab6-cold` | `cold-start/` |
## Эксперименты и отказы
### Инциденты (время UTC, `incident-*.json`)
| Воздействие | Ожидали | Наблюдали | Восстановление |
| --- | --- | --- | --- |
| Worker остановлен при 20 rps, 1 upload/s | рост возраста очереди, HTTP работает | возраст 75.8 с (пик), depth 66 на реплику (`max`=66, не 132); inject 20:05:22 → pending 20:06:17 → firing 20:06:47; HTTP 5xx=0; time-to-ready max 85 с против baseline | worker вернули сразу; drain 20:07:11, resolved 20:07:21 |
| Блокировка `attachments` (ACCESS EXCLUSIVE) при 2 upload/s | реальные 5xx, error alert | 88 из 161 запросов 5xx; inject 20:09:11 → firing 20:10:21; `INSERT attachments` p95 9.75 с (статут-таймаут 5 с); в трассе 5xx `INSERT attachments` 5000 мс, handler gap 1.5 мс; pool pending=0 (рост не ожидался) | lock снят 20:10:21; resolved 20:11:31 |
| Контроль handler-delay (20 uploads с `delay:500`) | задержка вне DB | сдвиг handler gap +500 мс (медиана), DB-время не изменилось (7.04→6.83 мс), все ключи потреблены, HTTP 202 | — |
| Tempo остановлен на 90 с (×2) | Collector retry/failures, API работает | `send_failed_spans` +720…758, queue max 82–83 ≤128, Collector RSS ≤214 MiB, logs/metrics продолжали идти, `make test` PASS внутри окна | трассы и логи вернулись (resume probe 10/10); потеря SERVER roots на probe 5–6 из 100 |
| Collector остановлен на 90 с (×2) | SDK ограничен, API работает | app export failed +10.8k items; stdout `http.request` писался без Loki; на probe 99 из 100 SERVER spans из окна потеряно (export timeout 5 с, затем drop); 15–16 сообщений SDK о диагностике очереди (учитываются отдельно) | все три сигнала возобновились; OOM/restart нет |
Объяснение: Collector down — SDK не буферизует долго (BSP очередь 2048, timeout 5 с): потеря телеметрии измерена, бизнес-ошибок нет. Tempo down — потери ограничены очередью Collector 128 export-requests и retry 30 с.
### Трек 1: «Цена наблюдаемости»
**Гипотеза.** Head sampling 25% при полных logs/metrics сокращает объём trace-ingest ≥2× (до ≤50% full), не ухудшает p95 более чем на 10% и сохраняет хотя бы по одной error- и slow-трассе в каждом повторе, но не гарантирует сохранение всех редких событий.
**Методика (заморожена в `scripts/lab6/track1.py`).** Один набор реплик (2 API + 1 worker, лимиты неизменны), режимы `off` (`OTEL_SDK_DISABLED=true`), `full` (ratio 1), `p25`, `p10`; stdout-логирование включено и в off. Open-loop генератор (`workload.py`): слот i в `t0+i/rate`, без догона; in-flight ≤64, `client_dropped` остаётся в знаменателе; 19 из 20 слотов — POST message (`lab6-track1`), каждый 20-й — upload sample.png; нет `traceparent` от клиента. Калибровка 20→10→5 rps: выбран первый, прошедший критерии — **20 rps**. Матрица 3 повтора × 4 режима в сбалансированном порядке; прогрев 60 с, замер 180 с; `docker stats` и `docker top` каждые 5 с; ingest — дельты cumulative counters Collector (spans / log records / metric points отдельно, deltas на completed операции). Диагностические cohorts отдельно от healthy: 40 slow uploads (`delay:500`, ключ потреблён, ожидаемо 202) и 40 app-error запросов (SQL lock на `messages`, 4 rps ×10 с, ожидаемо серверные 5xx), сверка stdout → Loki и stdout span_id → Tempo SERVER span. Классы: `intentional_unsampled`, `sampled_present`, `sampled_missing`, `missing_exported_logs`, неполные наблюдения — не потери. Логика — `measurement.py`, тесты `test_measurement.py` (18, stdlib).
**Результаты** (`track1/matrix.json`, медианы трёх повторов; все 12 runs protocol-valid, `configuration_failures` пусты; raw — `track1/runs/*/{summary.json,requests.jsonl,docker-stats.jsonl,cohorts.json}`):
| Режим | scheduled p95, мс | API CPU % (сумма реплик) | API container mem, MiB | spans/операцию | log rec/оп. | metric pts/оп. | kept error / slow (из 40, по run) |
| --- | --- | --- | --- | --- | --- | --- | --- |
| off | 15.27 | 7.78 | 239.5 | 0 | 0 | 0 | n/a |
| full | 13.38 | 6.04 | 282.7 | 4.90 | 1.05 | 0.524 | 40 / 40 |
| p25 | 12.66 | 5.54 | 282.4 | 1.23 (−74.9% к full) | 1.05 | 0.522 | 6–13 / 8–9 |
| p10 | 13.54 | 5.98 | 278.5 | 0.47 (−90.4% к full) | 1.05 | 0.535 | 4–5 / 4–6 |
Относительно off: full — API container mem +18.0%, RSS +20.6%; p25 +17.9% / +20.3%. **Latency и CPU в on-режимах ниже, чем в off** (−12…−17% p95): это не «выигрыш от телеметрии», а шум измерений при ~12–16 мс p95 и порядке прогонов на одном загруженном хосте (host/generator contention); вывод — на этой нагрузке измеримой цены по latency/CPU у телеметрии нет, различие статистически не разделено, цена видна по RAM (+≈43 MiB на API) и ingest. Потери export/enqueue/OOM/restart в healthy и cohorts — 0, `sampled_missing` и `missing_exported_logs` — 0 во всех режимах: **sampling не терял экспортированные логи, а ошибки/медленные запросы терялись только намеренно** (флаг `trace_sampled=false`).
Редкие события (модель независимого root sampling, не измерение): p25 при N=40 вероятность пропустить все `(0.75)^40 = 1.0e-5`; p10 `(0.9)^40 = 1.5%`. Фактически kept: p25 error 25/120, slow 25/120 (≈21% при ratio 0.25); p10 error 13/120, slow 15/120. Т.е. p25 сохраняет в каждом повторе несколько error/slow-трасс, но ~3/4 из них теряет намеренно.
**Выбор.** p25: критерии приёмки пройдены (`selected.json`: все 6 проверок True: valid-clean, ≥1 error и slow в каждом run, 0 missing, spans ≤50% full, p95 ≤110% full). Независимая проверка на свежем run (`track1/validation/p25`, `selected-validation.json`): PASS против **зафиксированного** full-reference (1.39 spans/op ≤ 50% от 4.9; p95 13.27 мс ≤ 110% от 13.38). Это компромисс, не гарантия: любую конкретную редкую ошибку p25 сохраняет с вероятностью ≈25%.
### Дефект, найденный регрессией
`make test-dependencies` (остановленный postgres/S3) сначала падал: из-за `dns_opt timeout:1 attempts:1` остановленный сервис давал `EAI_AGAIN`, который приложение отдавало 500 вместо 503. Исправлено добавлением `EAI_AGAIN` в `UNAVAILABLE_ERROR_CODES` (`api-exception.filter.ts`); после этого 7/7. Замеры трека 1 и инциденты сняты на образе до этой правки; она влияет только на путь недоступной зависимости, не на healthy-путь.
## Ограничения и следующие шаги
- Один хост (8 ядер, 15 GiB, занят другими контейнерами), фиксированный синтетический workload 20 rps, короткие окна 180 с, три повтора; p95 ~13 мс близок к шуму, поэтому различия latency/CPU между режимами не интерпретируются как эффект телеметрии.
- Stdout-логирование включено в off; ingest включает фоновую телеметрию (метрики каждые 10 с); потери SERVER-spans измерены только для корневых spans, не для всех дочерних; кросс-проверка Tempo при Collector-outage — выборка 100 запросов.
- Cohorts обогащены искусственно (40 slow, 40 error), это не оценка частоты в production. Tail sampling и burn-rate/длительное наблюдение ложных срабатываний не делались (вне трека 1).
- Hard crash процесса теряет ещё не экспортированную телеметрию; метрики не durable. Collector down: SDK теряет данные после 5 с timeout (измерено).
- Внешняя доставка alerts не реализована (не требуется). OTLP без TLS внутри compose-сети (lab7).