28 KiB
Отчёт — лабораторная 6
- Автор, группа: Березин Герман / БВТ2304
- Целевая оценка: 4
- Commit/PR: после публикации
- Использованные источники, библиотеки и помощь ИИ: Go 1.26, OpenTelemetry Go SDK 1.47 (
otel,sdk,sdk/metric,sdk/log, экспортёры OTLP/HTTP, мостotelslog0.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; processorsmemory_limiter(проверка 1 с, лимит 160 MiB, spike 40 MiB; контейнер 256 MiB) иbatch; exportersotlphttpв Prometheus (/api/v1/otlp) и Loki (/otlp),otlpgRPC в 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 spanattachments.jobs publish(родитель — запрос) и кладёт новыйtraceparentв сообщение (поля разрешеныjobs.schema.json). Worker извлекает контекст и создаёт consumer spanattachments.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, нагрузка загрузками.
Диагностика только по сохранённым данным:
- Alert
QueueLagGrowingперешёл в firing через 60 с, возраст старейшей задачи 58 с,queue_depth57. - Панели «Jobs per second by outcome» и «Worker saturation»:
jobs_processed_totalне растёт (0 задач/с),worker_busyравен 0. - Loki: за последнюю минуту нет ни одной записи
job readyworker. - 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 с, нагрузка сообщениями.
Диагностика:
ApiHighErrorRateв firing через 52 с, доля 5xx 0.47.- Метрики по маршрутам: 5xx только у
/api/v1/chats/{chat_id}/messages. p99 ≈ 4.9 с. - Tempo,
{ status = error }: server span 3006 мс, единственный долгий дочерний spandb INSERT2997 мс (≈ 100%) со статусом error. Время тратится в запросе к PostgreSQL (таймаут 3 с вdbCtx), а не в обработчике. - 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 нужны для чтения процессами контейнеров, это допустимо только для локального стенда.