Files
mtusi2026lab6/REPORT.md
T

28 KiB
Raw Blame History

Отчёт — лабораторная 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 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
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.