Files
mtusi2026lab6/REPORT.md
T

21 KiB
Raw Blame History

ЛР6 — наблюдаемость API и фонового pipeline

Автор: Белоусов Анатолий Фахраддинович, БПИ2303. Целевая оценка: 5, трек2 — SLO и обнаружение инцидентов. Учебный single-host стенд, synthetic data, эксперименты 20–21 ноября 2026. Итоговую оценку выставляет преподаватель после демонстрации и объяснения.

Происхождение и воспроизводимость

Skeleton 470d9d6f1e4fe4f594e37c2ba59550ee5ca54fc1, сохранены текущие README/COURSE/contracts/публичные tests. База — собственная ЛР5 (a9203f6): общие sessions/PG, Valkey profile cache, HAProxy/две API, идемпотентные messages, private S3, durable staging/outbox, persistent Streams broker, versioned worker/retry/fencing/replay. Исходники, миграции и конфиги находятся здесь; соседние лабораторные при запуске не нужны.

make up
make check
make test
make test-race
python3 student-tests/observability.py

Bootstrap создаёт случайные credentials вне Git, сохраняет существующие. API http://localhost:8086, Grafana http://localhost:3006, provisioned dashboard Messenger: API and image pipeline / Highload labs. Все опубликованные порты —loopback. QUICKSTART.md описывает запуск/отказы; DEFENSE.md —рассказ, схемы и все вопросы README; PIPELINE.md —сохранённые гарантии ЛР5; RUNBOOK.md —диагностика по сигналам.

Среда: Docker Desktop Linux/aarch64,14 virtual CPU,8 217 473 024 bytes VM RAM, Docker28.1.1 / Compose2.35.1-desktop.1. Ресурсы разделяются с другими локальными задачами. API: по1CPU/768MiB; worker1CPU/1024MiB с одним slot; PG2CPU/512MiB; S3 1CPU/512MiB; broker1CPU/256MiB. Каждый telemetry backend и Collector/Grafana: .5CPU/256MiB. Данные хранятся на named volumes, контракты не требуют HA этой VM.

Версии в compose/Dockerfile/go.mod: Go1.24.4-alpine3.22/Alpine3.22.1; PG17.6; Valkey8.1.3; HAProxy3.2.6; MinIO RELEASE.2025-09-07T16-13-09Z; Collector contrib0.128.0; Prometheus3.4.1; Loki3.5.1; Tempo2.8.0; Grafana12.0.2; OTel Go trace/metric/sdk1.36.0, log/sdk/exporter0.12.2, otelslog0.11.0, semantic conventions schema1.32.0 (custom logical metric names сопоставлены ниже). Образы не latest. Временные download caches нужны только для загрузки публичных закреплённых зависимостей, не для работы приложения.

Архитектура и privacy

API/worker/dispatcher → OTLP HTTP/protobuf → отдельный Collector. Metrics экспортируются через Prometheus endpoint Collector и scrapes, logs —native Loki OTLP endpoint, traces —Tempo OTLP. Grafana запрашивает хранилища, не заменяет их. Prometheus/Loki/Tempo/Grafana имеют persistent volumes и24h retention для учебной истории (Prometheus ещё512MB size cap).

Resource attrs: service.name=messenger-api/messenger-worker/messenger-dispatcher, service.version=6.1.0, service.instance.id=container hostname, deployment.environment.name=lab. Метрики имеют только method/route template/status class и job_type/outcome; неизвестные HTTP methods нормализованы. Нет user/chat/message/attachment/request IDs, filename, raw URL или body в labels. SQL spans имеют ограниченное operation name, без SQL text/args. Логи содержат timestamp/severity/service/event, request_id и trace_id/span_id при context. Job ID в logs —ограниченный технический correlation key synthetic эксперимента, не metric label. Пароли, Bearer/Basic headers, session tokens, тексты и изображения не экспортируются.

HTTP trace context извлекается по W3C. Upload сохраняет traceparent/tracestate в PG job/outbox. Dispatcher извлекает сохранённый context, начинает producer span и сериализует новый context в job. Consumer извлекает его, выполняет реальные DB, transform и S3 spans. Retry остаётся в той же причинной цепочке, с отдельным producer/consumer и job.attempt. Завершающий SQL COMMIT использует bounded WithoutCancel context, сохраняя trace context при независимом commit budget. Новый trace не означает новую business job.

Отображение observability contract

Логический сигнал Prometheus name / смысл
HTTP count http_server_requests_total; method, route, status_class
HTTP duration http_server_duration_seconds_bucket/count/sum; seconds
Jobs success/failure messenger_jobs_total; job_type и outcome, управляемые claimed attempts, не уникальные delivery IDs
Processing duration messenger_job_duration_seconds_bucket; claimed attempt до устойчивого результата/retry
End-to-end ready messenger_attachment_ready_duration_seconds_bucket; seconds от PG acceptance timestamp до ready COMMIT
Queue depth / oldest messenger_queue_depth / messenger_queue_oldest_age_seconds; authoritative unfinished jobs, включая processing
DB pool messenger_db_pool_used / limit / waiting; waiting —незавершённые acquire calls, включая краткое получение свободного соединения; waits_total —cumulative empty acquire events, rate показывает wait event frequency
Worker saturation messenger_worker_busy / capacity; bounded slots
Parent process resources process_memory_usage_bytes / process_cpu_time_seconds_total
Whole container resources container_memory_usage_bytes / container_cpu_time_seconds_total, cgroupv2, включая transform/cwebp children
Deadline readiness SLI messenger_attachment_sli_total / messenger_attachment_sli_bad_total; matured PG cohorts

Percentiles вычисляются histogram_quantile(q,sum by(le)(rate(..._bucket[60s]))) дляq=.5/.95/.99; buckets объединяют реплики до вычисления percentile. Границы0.005…120s включают5s target. Это bucket approximation, не точный raw percentile. Pool waits —счётчик событий ожидания, не мгновенное число goroutines. Queue age не равно processing duration. Глобальные queue/SLI экспортирует dispatcher, поэтому остановка worker не прекращает их обновление. При DB error callback не выдаёт ложный0, а пропускает observation.

Dashboard JSON содержит24 панели: RPS/errors/latency percentiles, jobs, durations, queue/deadline SLI, pool/waits, saturation, parent/cgroup resources, Collector failed exports, logs и alerts. Datasources и dashboard provisioning импортируются без ручных действий. Tempo и Loki связаны по trace_id; X-Request-Id из ошибки даёт поиск request в Loki.

SLI/SLO и исследовательская гипотеза

Гипотеза: multi-window burn alerts и комбинация независимых сигналов позволят отличить короткий всплеск от длительной деградации и локализовать причину (worker outage / DB lock), не скрывая незавершённые задачи из readiness SLI.

Локальный rolling10m SLO: API99% non-5xx business HTTP responses на HAProxy ingress (health направлены в отдельный backend и исключены, denominator=все business responses backend replicas,4xx не server outage). SLI использует haproxy_backend_http_responses_total и включает503, созданные самим LB; SDK HTTP metrics отдельно описывают обработанные API запросы. Readiness95% принятых job versions ready≤5s. Измерительная точка acceptance —job.created_at внутри committed upload transaction; она предшествует COMMIT на небольшой SQL interval и даёт консервативную оценку. Общий PG clock используется для acceptance/ready/lease.

Readiness cohort учитывается только после возраста5s, один раз: ready_at≤created_at+5s —good; failed/unfinished/late ready —bad. Это устойчивые cumulative counters из PG, поэтому остановленный worker не «улучшает» SLI отсутствием завершений. Completed-latency histogram отдельно нужен для percentiles.

Fast burn: bad ratio >6×allowed в обоих10s/60s окнах, for10s; API slow burn >2× в30s/120s, for20s. Отдельно APIHighErrorRate:5xx>10% в30s, for6s; QueueLag: oldest>5s и depth>0, for6s. Правила лежат в infra/prometheus/alerts.yaml, local firing/resolved доступны через Prometheus API, внешней отправки сообщений нет. При равномерном потоке6× расходует10m budget примерно за100s,2× —за300s. Малые окна выбраны для воспроизводимой лабораторной, это не production30d SLO.

Методика воспроизведения

student-tests/observability.py создаёт уникальных синтетических пользователей/чат. Сначала контролируемый upload с известным W3C trace context, получение ready и проверка сохранённой цепочки/логов. Затем последовательно:

  1. Остановить worker, продолжать uploads, измерять queue/deadline SLI/alerts. Вернуть worker, дождаться ready и byte identity всех принятых файлов, resolved.
  2. Генерировать равномерно ограниченный closed-loop message traffic. Удержать table lock chats3s как краткий spike, затем45s как длительную деградацию. Сохранить alert timeline и реальный failed HTTP trace; причина должна проявиться в SQL child span около lock_timeout=1s (отдельный statement_timeout=2s), а не быть «угадана» по команде остановки.
  3. Остановить Tempo и Loki под message traffic, сохранить business success/error count, Collector memory и failed telemetry export counter. Восстановить backends, проверить новые сигналы.

Фазы можно повторять отдельно trace/worker/db/backend. Не подделываются timestamps, spans или firing. Диагностика и запросы для другого студента —RUNBOOK.md. Времена detection/resolution берутся из реального Prometheus polling с шагом около1s; scrape/SDK export/evaluation добавляют задержку.

Ограниченная буферизация и независимость бизнес-пути

SDK: async queues1024 spans/log records, max batch128, export deadline1s; metric periodic export2s,1s timeout. Collector: memory_limiter180MiB/spike40MiB в cgroup256MiB, batch max256, export queues64 batches/2consumers на backend, retries max elapsed15s. Container stdout logs ротируются10MiB×3. Отказ telemetry не входит в API readiness; критичны PG/S3, optional cache допускает PG fallback. При недоступности telemetry exporters возможны потери, не бесконечный RAM buffer. Failed export counter —число неуспешно экспортированных items, не универсальная exactly-once оценка уникальных trace IDs.

Ограничения и источники

Single host и одиночные PG/S3/broker/LB/telemetry stores остаются SPOF. Named volume не backup. Sampling parent-based с100% новых roots не гарантирует полную доставку всех spans; remote sampling и bounded queues могут их убрать. История24h, локальный synthetic closed-loop traffic с coordinated omission; выводов о максимальном RPS/production SLA нет. Runbook и проверка причин по сохранённым сигналам не являются независимым слепым исследованием второй команды.

Использованы собственные ЛР4/5, контракты преподавателя и Codex для реализации/проверок/объяснений. Первичные материалы: Collector configuration, W3C Trace Context, Loki native OTLP, Prometheus histograms, Grafana provisioning. Автор должен уметь объяснить решение и менять его на защите.

Финальный encoder различает invalid image (child exit65) и временную аварию/kill/deadline: последняя проходит bounded retry, а не маркирует корректный файл invalid_image. EXIF обрабатывается для JPEG APP1 и PNG eXIf, перед resize. Финальные race/PG проверки актуальных исходников, включая PNG EXIF и аварии subprocess, — evidence/race-final.txt. Для проверки использован уже скачанный совместимый Go1.24.4/GCC/cwebp test toolchain с read-only bind текущих cmd/internal (в ЛР6 также текущие go.mod/go.sum); публичный make test-race сам собирает такой toolchain из Dockerfile, соседняя лабораторная для запуска/проверки не требуется.

Измеренные результаты

Сценарий Наблюдение
Worker остановлен, 32 принятых uploads QueueLag firing через 15.527s, ReadyBudgetFastBurn через 19.666s; после actual worker StartedAt очередь пуста через 2.901s, alerts resolved через 5.958s / 12.077s. Все 32 original побайтно совпали.
Краткий DB lock 3s 8 ошибочных из 292 HTTP, 0 наблюдавшихся ложных fast-burn firing. Это результат одного опыта, не оценка вероятности ложных тревог.
Длительный DB lock 45s Fast burn обнаружен через 24.329s. Реальный error trace содержит db.SELECT 1001.005ms: lock_timeout=1s. После первого coordinator poll после освобождения lock fast/high-error/slow alerts resolved через 11.188 / 23.429 / 29.524s.
Tempo и Loki остановлены 1908 подтверждённых messages, 0 бизнес-ошибок; failed span exports +1323, RAM Collector 70.15–71.09MiB при cap256MiB. Новая полная цепочка после восстановления найдена. Счётчик экспорта не равен числу уникальных потерянных traces.
Оба API остановлены Ingress вернул503, HAProxy business 5xx counter вырос178→179 за1.009s: SLI учитывает отказ перед SDK. API восстановлены, прежний токен работает.
Нагрузка, telemetry включена 4 closed-loop clients, без warmup, 15.019s: 18832 success / 0 errors, 1253.888 success RPS; p50/p95/p99 успехов 2.999/4.515/6.298ms.
Failover одного API 128 успешных writes / 1 failed attempt, первое восстановление0.834s; подтверждённые данные и session сохранены.

Raw timelines и границы времени: evidence/incidents.json, incident-worker-summary.json, incident-db-summary.json. У worker anchor — actual Docker StartedAt, у DB — первый poll после завершения lock process; наблюдение с шагом≈1s ограничивает точность. Worker summary поле recovery_observation_seconds описывает длительность старого общего цикла наблюдения, точные anchors/queue/alert resolution приведены отдельно и выше. Результаты поддерживают гипотезу для этих двух локальных отказов; независимая слепая диагностика другим студентом не проводилась.

Полное измерение нагрузки: evidence/load.json и load-resources.json. PG messages8478→27310; это growing dataset. Максимальный наблюдённый sample одной API:0.507 CPU core и205496320 bytes RAM; это не сумма двух API и не максимум всей системы. Первый запуск wrapper завершился ошибкой сбора Docker stats, public load продолжил работу:4971 success /8errors; raw load-first.json сохранён, причины восьми ошибок не классифицированы. Этот неполный опыт нельзя сравнивать с завершённым измерением или использовать как тест цены telemetry. Исправленный wrapper читает реальные cgroup metrics через Prometheus, сохраняет все ошибки; публичный tests/load.py не изменён. Closed-loop/coordinated omission, без warmup и общая VM ограничивают выводы о capacity.

Проверки

  • make check, полный OpenAPI validator и публичный smoke с telemetry — PASS (check.txt, openapi.txt, smoke-final.txt).
  • Реальный PG + Go race detector текущих исходников — PASS (race-final.txt); concurrent HTTP/idempotency, Unicode KDF, image sizing/alpha/JPEG и PNG EXIF, transient child failure. go vet ./... выполнен.
  • make test-persistence ACTION_SCRIPT=scripts/restart.sh — PASS: прежняя session и подтверждённые сообщения/файлы после restart API, PG/cache/S3/broker и telemetry stores (persistence.txt).
  • Prometheus promtool проверил5 alert rules (alert-rules-check.txt); HAProxy проверил config (haproxy-config.txt).
  • Реальные producer/consumer/DB/S3 spans и Loki correlation найдены в обычном, retry и восстановленном запросах (trace-chain*.json); label audit (metric-labels.json).
  • Проверки инцидентов, ingress503 и ограниченной Collector memory выполнены. Remote CI не заявляется выполненным.

Финальный implementation commit bd2c7f7 проверен из настоящего чистого клона: новые credentials/volumes, автоматический provisioning, public smoke и старый токен после перезапуска API, PG/cache/S3/broker/worker/dispatcher и Prometheus/Loki/Tempo/Grafana/Collector — PASS. Для каждого процесса сверены actual StartedAt; API работают non-root и PID1. Вывод — evidence/clean-clone-final.txt, before/after — persistence-processes.json. Удалён только уникальный временный проект. Импортированные24 панели и версии работающей Grafana дополнительно подтверждены provisioning.json.