Files
mtusi2026lab6-fork/REPORT.md

28 KiB
Raw Permalink Blame History

Отчёт — лабораторная 6

  • Автор, группа: Березин Герман / БВТ2304
  • Целевая оценка: 4
  • Commit/PR: после публикации
  • Использованные источники, библиотеки и помощь ИИ: Go 1.26, OpenTelemetry Go SDK 1.47 (otel, sdk, sdk/metric, sdk/log, экспортёры OTLP/HTTP, мост otelslog 0.21), pgx, go-redis, minio-go; OpenTelemetry Collector contrib 0.116.1, Prometheus 3.1.0, Loki 3.3.2, Tempo 2.7.0, Grafana 11.3.0; документация OTel Collector configuration, OTel propagation, W3C Trace Context, Prometheus histograms, Grafana provisioning из README; код lab5 перенесён за основу; ИИ-ассистент использован при разработке

Запуск из чистого clone

Требуются Docker 29 с Compose v2 и Python 3.9+. Для tests/variants.py нужен Pillow.

cp .env.example .env
sh scripts/mksecrets.sh
docker compose --env-file .env up -d --build --wait
make check && make test

mksecrets.sh создаёт секреты в ./secrets (вне Git), в том числе пароль Grafana: cat secrets/grafana_admin_password, пользователь admin. Существующие файлы не перезаписываются.

Порядок старта: postgres, valkey, broker, s3, prometheus, loki, tempo → migrate → s3-init, otel-collector, grafana → api × 2, worker, janitor → lb. Публичный адрес API: http://localhost:8080. Интерфейсы на 127.0.0.1: Grafana :3000, Prometheus :9090 (alerts: /alerts), Loki :3100, Tempo :3200. Dashboard и datasources подключаются автоматически из infra/grafana/, вручную ничего набирать не нужно. После первого старта S3 принимает запись через 10–30 с.

Остановка без потери данных: docker compose --env-file .env stop. Намеренное удаление учебных данных: docker compose --env-file .env down -v.

Проверки (стенд запущен):

python3 tests/dashboard.py
python3 tests/observability.py
python3 tests/incidents.py --only worker
python3 tests/incidents.py --only database
python3 tests/incidents.py --only storage
python3 tests/telemetry_persistence.py
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 tests/scenario.py --mode failover-each --output evidence/failover-each.json
python3 tests/scenario.py --mode rolling --output evidence/rolling.json
python3 tests/variants.py
python3 tests/queue_recovery.py
python3 tests/faults.py
python3 tests/worker_load.py --output evidence/worker-load.json
python3 tests/attachments.py
python3 tests/s3_checks.py
python3 tests/upload_memory.py --output evidence/upload-memory.json
python3 tests/idempotency.py
python3 tests/session_revocation.py

incidents.py, observability.py, faults.py, queue_recovery.py, worker_load.py сами останавливают и пересоздают сервисы и возвращают их. После make test-failover реплику возвращают командой docker compose --env-file .env up -d --wait api. Операторские команды worker и разбор alerts: infra/runbook.md.

Архитектура и решения

клиент → HAProxy → api ×2 ──OTLP──┐
                    │ trace context в jobs.traceparent → outbox → сообщение broker
                    ▼                                      │
          PostgreSQL / S3 / broker                         ▼
                                              worker ──OTLP──┤
                                                             ▼
                                         otel-collector (memory_limiter, batch, очереди)
                         метрики ─→ Prometheus   логи ─→ Loki   трассы ─→ Tempo
                                                             ▼
                                         Grafana (datasources и dashboard из Git)

Бизнес-API, PostgreSQL, S3, broker, outbox, worker и retry перенесены из lab5 без изменения смысла (подробности в CHANGES.md). Изменено: добавлена телеметрия, миграция 0005_trace_context.sql, сервисы наблюдаемости.

Роль Сервис Образ Готовность Volume Сеть Назначение
collector otel-collector otel/opentelemetry-collector-contrib:0.116.1@sha256:d0ebf652… запуск после готовности хранилищ нет backend, telemetry принимает OTLP, ограничивает память, батчит, раздаёт сигналы
метрики prometheus prom/prometheus:v3.1.0@sha256:6559acbd… /-/ready prometheus_data telemetry, 127.0.0.1:9090 хранит метрики (OTLP receiver), считает alert rules
логи loki grafana/loki:3.3.2@sha256:8af2de1a… /ready loki_data telemetry, 127.0.0.1:3100 хранит структурные логи, ищет по trace_id
трассы tempo grafana/tempo:2.7.0@sha256:12e904cc… /ready tempo_data telemetry, 127.0.0.1:3200 хранит трассы, поиск TraceQL
интерфейс grafana grafana/grafana:11.3.0@sha256:a0f88123… /api/health grafana_data telemetry, 127.0.0.1:3000 dashboard и запросы к трём источникам, сам данные не хранит
api ×2, worker, postgres, valkey, broker, s3, lb как в lab5 образ приложения mtusi-messenger:lab6 как в lab5 как в lab5 backend, storage см. REPORT lab5

Bootstrap: migrate применяет migrations/*.sql; provisioning Grafana читается при старте из infra/grafana/provisioning; Prometheus, Loki и Tempo стартуют из конфигов в infra/. Повторный запуск up -d безопасен. Пароль Grafana передаётся файлом secret (GF_SECURITY_ADMIN_PASSWORD__FILE).

  • Collector (infra/otel/collector.yaml): receivers OTLP gRPC/HTTP; processors memory_limiter (проверка 1 с, лимит 160 MiB, spike 40 MiB; контейнер 256 MiB) и batch; exporters otlphttp в Prometheus (/api/v1/otlp) и Loki (/otlp), otlp gRPC в Tempo. У каждого экспортёра очередь sending_queue на 100 батчей и повтор до 20 с (retry_on_failure), после чего данные отбрасываются. Collector не хранит данные на диске.
  • Приложение. SDK экспортирует по OTLP/HTTP: батч трасс (очередь 2048 spans, таймаут 5 с), метрики раз в 10 с, батч логов (очередь 2048, интервал 1 с); повтор каждого экспорта не дольше 8 с. Недоступный Collector не блокирует запросы: полная очередь отбрасывает записи, ошибки экспорта считает telemetry.export.errors.
  • Распространение контекста. Входящий traceparent запроса извлекается. Upload сохраняет контекст server span в jobs.traceparent/tracestate в той же транзакции, что и задачу. Relay берёт его из строки задачи, создаёт producer span attachments.jobs publish (родитель — запрос) и кладёт новый traceparent в сообщение (поля разрешены jobs.schema.json). Worker извлекает контекст и создаёт consumer span attachments.jobs process с родителем producer span. Повторы, reaper и replay публикуют сообщение из той же строки, поэтому все попытки лежат в одном trace, у каждой свой producer и consumer span.
  • Spans: server span на запрос (имя METHOD route template), db <операция> на каждый запрос pgx (текст SQL без параметров), s3 put/get/remove, image render. Spans создаются только внутри существующего trace: фоновые опросы (relay, reaper, чтение stream) не порождают отдельных trace.
  • Логи. JSON в stdout и тот же лог по OTLP в Loki. Поля: время, уровень, service.name, event, trace_id, span_id при активном span, технические поля события. Resource attributes: service.name (messenger-api / messenger-worker), service.version, service.instance.id (id контейнера), deployment.environment.name=lab.
  • Что не попадает в телеметрию. Заголовок Authorization, токены, пароли, тела сообщений, содержимое изображений, URL с параметрами (в spans только http.route — шаблон), значения параметров SQL. В labels метрик нет user_id, chat_id, message_id, attachment_id, request_id, filename, raw URL. В логах и spans есть технические request_id, job_id, attachment_id (синтетические учебные данные): по ним находится нужный trace.
  • Хранилища и сохранность. Prometheus, Loki и Tempo хранят данные 7 суток на своих volumes (Loki с WAL и сбросом при остановке). Историю после перезапуска проверяет tests/telemetry_persistence.py.

Соответствие .env.example

Переменная Где используется
OTEL_SERVICE_NAME api: messenger-api; worker: messenger-worker (задаётся в compose)
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL compose, api и worker; SDK читает стандартные переменные
OTEL_RESOURCE_ATTRIBUTES deployment.environment.name, SDK читает стандартную переменную
остальные как в lab5 (API_REPLICAS, S3_*, WORKER_CONCURRENCY, JOB_*, CLEANUP_*, STAGING_RETENTION_SECONDS, *_FILE)

Сигналы и соответствие контракту

Имена OTel и их вид в Prometheus (единицы в имени добавляет трансляция OTLP → Prometheus). Для каждого сигнала один инструмент, дублей нет.

Контракт Инструмент OTel (единицы) В Prometheus Измерения
HTTP requests http.server.requests (counter) http_server_requests_total method, route template, класс статуса (2xx…)
HTTP duration http.server.request.duration (histogram, с) http_server_request_duration_seconds_bucket method, route, класс статуса; buckets 0.005–10 с
Jobs processed / failed jobs.processed (counter) jobs_processed_total job.type, outcome: ready, retry, failed, skipped, lease_lost
Job duration job.processing.duration (histogram, с) job_processing_duration_seconds_bucket job.type, outcome
Time to ready job.time_to_ready (histogram, с) job_time_to_ready_seconds_bucket от durable acceptance (jobs.created_at) до COMMIT ready
Queue depth / oldest age queue.depth ({job}), queue.oldest_job_age (с) queue_depth, queue_oldest_job_age_seconds queue; из PostgreSQL (jobs в статусе queued), возраст от next_attempt_at
DB pool db.pool.connections, db.pool.max_connections, db.pool.empty_acquires, db.pool.acquire.wait (с) db_pool_connections{state}, db_pool_max_connections, db_pool_empty_acquires_total, db_pool_acquire_wait_seconds_total state used/idle
Worker saturation worker.busy, worker.capacity worker_busy, worker_capacity
CPU / RAM process.cpu.time (с), process.memory.usage (байт) process_cpu_time_seconds_total, process_memory_usage_bytes процесс (api, worker)
Потери телеметрии telemetry.export.errors; метрики Collector otelcol_exporter_* (scrape Prometheus) telemetry_export_errors_total, otelcol_exporter_send_failed_*, otelcol_exporter_queue_size
Логи, трассы OTLP logs, OTLP traces Loki (service_name, structured metadata), Tempo trace_id, span_id

Метрики очереди публикует каждая API-реплика (одно значение из PostgreSQL), на dashboard и в alert применяется max, чтобы данные не пропадали при остановке worker.

SLI и SLO

Цель SLI SLO
Доступность API доля бизнес-запросов без ответа 5xx: 1 − sum(rate(http_server_requests_total{status_class="5xx"})) / sum(rate(http_server_requests_total)); health-запросы не учитываются, 4xx (ошибки клиента, например неверный пароль) не считаются отказом 99% за скользящие 30 суток
Время до ready доля вложений с job_time_to_ready_seconds ≤ 10: increase(…_bucket{le="10"}) / increase(…_count) 95% за 30 суток

Alert rules (infra/prometheus/rules/alerts.yml, runbook infra/runbook.md) — быстрые проверки расхода бюджета на коротких окнах, чтобы воспроизводить их на стенде:

Alert Условие Окно / for Что означает
ApiHighErrorRate доля 5xx > 5% 1 мин / 20 с бюджет доступности расходуется быстрее допустимого
QueueLagGrowing max(queue_oldest_job_age_seconds) > 20 — / 20 с worker не успевает или остановлен, SLO времени до ready под угрозой

Окно 30 суток на стенде не накапливается: показаны SLI за выбранный интервал dashboard и alerts, проверенные на коротком окне. Burn-rate с несколькими окнами не реализован (это трек 5).

Dashboard «Messenger observability»

Файл infra/grafana/dashboards/messenger.json, импортируется provisioning'ом. Все 28 панелей и 34 запроса выполняются без ошибок (tests/dashboard.py). Ключевые панели:

Панель Запрос Единица
RPS по маршрутам sum by (http_route) (rate(http_server_requests_total[$__rate_interval])) запросов/с
Доля ошибок (sum(rate(…{http_response_status_class="5xx"}[$__rate_interval])) or vector(0)) / sum(rate(http_server_requests_total[$__rate_interval])) доля (0–1)
Latency p50/p95/p99 histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket[$__rate_interval]))) с
Jobs по outcome sum by (outcome) (rate(jobs_processed_total[$__rate_interval])) задач/с
Job duration p50/p95/p99 histogram_quantile(0.95, sum by (le) (rate(job_processing_duration_seconds_bucket[…]))) с
Time to ready p50/p95/p99 histogram_quantile(…, sum by (le) (rate(job_time_to_ready_seconds_bucket[…]))) с
Queue depth max by (queue) (queue_depth) задач
Oldest queued job age max by (queue) (queue_oldest_job_age_seconds) с
Worker saturation sum(worker_busy), sum(worker_capacity) слотов
DB pool sum by (instance) (db_pool_connections{state="used",job="messenger-api"}), max(db_pool_max_connections) соединений
DB acquire wait sum by (job) (rate(db_pool_acquire_wait_seconds_total[…])), rate(db_pool_empty_acquires_total[…]) с/с, ожиданий/с
CPU, RSS rate(process_cpu_time_seconds_total[…]), process_memory_usage_bytes ядра, байты
SLI доступности, SLI ready ≤ 10 с см. таблицу SLI доля
Collector: очередь, потери, память otelcol_exporter_queue_size, rate(otelcol_exporter_send_failed_*[…]), otelcol_process_memory_rss батчей, записей/с, байты
Логи warn/error, трассы с ошибкой Loki {service_name=~"messenger-.*"} | detected_level=~"warn|error", TraceQL { status = error }

Percentiles берутся из histogram buckets суммой по всем репликам (sum by (le)), средние p95 реплик не используются.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke при включённой телеметрии make check && make test PASS evidence/smoke.txt
Минимум lab5 сохранён tests/attachments.py, s3_checks.py, idempotency.py, session_revocation.py, variants.py, queue_recovery.py, faults.py, worker_load.py, upload_memory.py PASS; s3_checks.py допускает публикацию портов только на 127.0.0.1 и только у lb, Grafana, Prometheus, Loki, Tempo evidence/attachments.txt, s3-checks.txt, idempotency.txt, session-revocation.txt, variants.txt, queue-recovery.txt, faults.txt, worker-load.json, upload-memory.json
Restart всех stores и телеметрии с volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; времена запуска postgres, valkey, broker, s3, prometheus, loki, tempo, collector, grafana, api, lb, janitor, worker до и после evidence/persistence.txt
Failover API-реплик, rolling update make test-failover, tests/scenario.py PASS для обеих реплик, 0 неуспешных попыток в публичном тесте, запись восстанавливается за 3.5 с evidence/failover-1.txt, failover-2.txt, failover-each.json, rolling.json
Нагрузка tests/load.py --duration 30 --concurrency 4 11 666 успешных запросов, 387 RPS, 0 ошибок, p50/p95/p99 5.8 / 44.8 / 55.5 мс evidence/load.json
Метрики, логи, трассы API и worker; низкая кардинальность; нет секретов tests/observability.py 13 сигналов есть; в labels нет user_id/chat_id/message_id/attachment_id/request_id; route — шаблон; тело сообщения и токен отсутствуют в Loki и Tempo evidence/observability.txt
Запрос → trace → лог; job → worker trace → лог tests/observability.py по request_id лог API содержит trace_id/span_id; в Tempo trace из 30 spans; лог worker job ready с тем же trace_id evidence/observability.txt
W3C trace context API → broker → worker tests/observability.py server → producer (родитель — запрос) → consumer (родитель — producer) → s3 get, image render, 4×s3 put, db COMMIT, s3 remove в одном trace evidence/observability.txt
Цепочка по одному upload включая retry tests/observability.py S3 остановлен: 5 неуспешных попыток; после запуска S3 и replay попытка 6 → ready; 6 consumer и 6 producer spans в одном trace evidence/observability.txt
Provisioning, импорт dashboard tests/dashboard.py 3 datasources и dashboard из Git, 28 панелей, 34 запроса без ошибок evidence/dashboard.txt
Percentiles из histogram, доля ошибок, queue age, DB pool, saturation worker dashboard (запросы выше) панели показывают перечисленные величины раздел «Dashboard», evidence/dashboard.txt
SLI/SLO и alerts, проверка искусственным отказом инциденты 1 и 2 firing, затем resolved evidence/incident-worker.txt, incident-database.txt
Collector memory_limiter/batch, ограниченная буферизация, остановка хранилищ tests/incidents.py --only storage Prometheus, Loki, Tempo остановлены ≈ 80 с под нагрузкой: 942 сообщения 201 и 99 загрузок без 5xx; 3/3 вложения ready; RSS Collector 64 → 71 MiB; потери посчитаны evidence/incident-storage.txt
История телеметрии на volumes tests/telemetry_persistence.py после перезапуска Prometheus, Loki, Tempo trace, его лог и метрики на месте evidence/telemetry-persistence.txt

Эксперименты и отказы

Стенд: один хост, Docker 29, лимиты контейнеров из compose.yaml. Нагрузка — closed-loop клиент (3–4 потока, Idempotency-Key), в инцидентах плюс загрузка PNG раз в секунду. Числа ниже взяты из файлов evidence.

Инцидент 1. Остановлен worker

Действие: docker compose stop worker, нагрузка загрузками.

Диагностика только по сохранённым данным:

  1. Alert QueueLagGrowing перешёл в firing через 60 с, возраст старейшей задачи 58 с, queue_depth 57.
  2. Панели «Jobs per second by outcome» и «Worker saturation»: jobs_processed_total не растёт (0 задач/с), worker_busy равен 0.
  3. Loki: за последнюю минуту нет ни одной записи job ready worker.
  4. Tempo: trace свежей загрузки содержит server span API и producer span attachments.jobs publish и не содержит consumer span. Задача опубликована, её никто не забирает.

Вывод: причина в остановленном worker, а не в API или брокере. Восстановление: up -d worker; alert разрешился через 20 с, очередь опустела за 21 с, потерь нет.

Инцидент 2. Заблокированная БД

Действие: сессия psql держит lock table messages in access exclusive mode 45 с, нагрузка сообщениями.

Диагностика:

  1. ApiHighErrorRate в firing через 52 с, доля 5xx 0.47.
  2. Метрики по маршрутам: 5xx только у /api/v1/chats/{chat_id}/messages. p99 ≈ 4.9 с.
  3. Tempo, { status = error }: server span 3006 мс, единственный долгий дочерний span db INSERT 2997 мс (≈ 100%) со статусом error. Время тратится в запросе к PostgreSQL (таймаут 3 с в dbCtx), а не в обработчике.
  4. DB pool: ожидания соединения нет (0.01 с/с), пул не исчерпан. Значит причина не в нехватке соединений, а в одном долгом запросе.

Вывод: причина в блокировке таблицы messages в PostgreSQL. Медленный обработчик исключён: у него нет собственного долгого этапа. Восстановление: блокировка снята, alert разрешился через 40 с; за время опыта 52 запроса получили 503, 164 — 201.

Инцидент 3. Недоступны хранилища телеметрии

Prometheus, Loki, Tempo остановлены на ≈ 80 с под нагрузкой. API без ошибок (942 × 201, 99 загрузок), 3 новых вложения ready, сообщение создано. Collector не перезапускался и не убит по памяти, RSS 64 → 71 MiB при лимите контейнера 256 MiB. Потери посчитаны: otelcol_exporter_send_failed_* вырос на 2443 spans, 254 лога, 456 точек метрик. Данные за время недоступности потеряны (очередь 100 батчей и повтор до 20 с их не удерживают), данные до остановки сохранены, новые логи и метрики после запуска хранятся.

Порог memory_limiter (160 MiB) в этом опыте не достигался: ограничение обеспечили ограниченные очереди и отбрасывание.

Прочее

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
Отказ каждой API-реплики под нагрузкой запись продолжается 7 и 2 неуспешные попытки, 280 и 289 RPS против 448 до отказа возврат реплики ≈ 6.8 с, потерь нет
Rolling update без простоя 2 неуспешные попытки, 462 RPS старые реплики не отвечают
Restart всех stores и телеметрии данные и сессия сохраняются PASS потерь нет
Нагрузка worker 6×40 Мп + 20 малых не более 2 задач, память в лимите все ready за 13.1 с, пик RSS 608 MiB / 768 без OOM

Накладные расходы телеметрии не измерялись (трек 5 не заявлен).

Ограничения и следующие шаги

  • Collector, Prometheus, Loki, Tempo, Grafana, broker, PostgreSQL, S3 и HAProxy — единичные экземпляры. Остановка Collector приводит к потере телеметрии на время простоя (SDK держит не больше 2048 записей на сигнал и повторяет экспорт до 8 с).
  • Collector не имеет дисковой очереди. Данные за время недоступности хранилища теряются, потери видны в otelcol_exporter_send_failed_*.
  • Alerts проверены на коротких окнах (1 мин). Многооконный burn-rate (трек 5) не реализован, SLO за 30 суток на стенде не накапливаются.
  • Метрики очереди берутся из PostgreSQL, а не из длины stream брокера: stream не обрезается (XTRIM не реализован), его длина не равна глубине очереди.
  • service.instance.id — идентификатор контейнера: после пересоздания он меняется, старые ряды остаются в Prometheus до окончания retention.
  • Трассы не сэмплируются (записывается всё). Цену наблюдаемости не измеряли.
  • Порты Grafana, Prometheus, Loki, Tempo привязаны к 127.0.0.1; Prometheus, Loki и Tempo без аутентификации: допустимо только для локального стенда.
  • Секреты лежат в ./secrets вне Git. Права 644 нужны для чтения процессами контейнеров, это допустимо только для локального стенда.