Files
mtusi2026lab6/REPORT.md
T
2026-11-01 20:38:50 +03:00

28 KiB
Raw Blame History

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

  • Автор, группа: Гаджиев Нухбала, БВТ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: всё из lab5 и новое: OpenTelemetry Python SDK 1.45.2 и автоинструментация 0.66b2 (FastAPI, psycopg, botocore, system-metrics, logging), OpenTelemetry Collector contrib 0.140.1, Prometheus 3.7.3, Loki 3.5.8, Tempo 2.9.0, Grafana 12.2.1. Документация: OTel Collector configuration (memory_limiter, batch, sending_queue, retry_on_failure), OTel context propagation и W3C Trace Context, semantic conventions (HTTP, messaging, db.client.connection), Prometheus (OTLP receiver, histograms and summaries, alerting rules), Loki (OTLP ingestion, structured metadata), Tempo (TraceQL), Grafana provisioning. ИИ использовался только как вспомогательный ресурс: для оценки решения, написания комментариев к коду и составления текстовых документов.

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

Проверял на Windows 11 в Git Bash с Docker Desktop (WSL 2). Нужны Docker с Compose, Python 3 (только для тестов, стандартная библиотека) и GNU Make. Образы закреплены: всё из lab5 (python:3.12.8-slim-bookworm, haproxy:3.2.25-alpine, postgres:17.10-bookworm, valkey/valkey:8.1.9, chrislusf/seaweedfs:4.44, rabbitmq:4.2.9-alpine) и otel/opentelemetry-collector-contrib:0.140.1, prom/prometheus:v3.7.3, grafana/loki:3.5.8, grafana/tempo:2.9.0, grafana/grafana:12.2.1. Перед запуском остановить стенд lab5 (docker compose -p mtusi-lab5 down): заняты те же порты.

git clone https://gitea.privcloud.tech/ng14/mtusi2026lab6.git && cd mtusi2026lab6
git checkout solution/bvt2303-gadzhiev
cp .env.example .env
sed -i 's/\r$//' .env                  # только Windows: убрать \r из .env
sh scripts/init-secrets.sh             # secrets/: пароли PostgreSQL, Valkey, RabbitMQ, ключи S3, пароль Grafana
docker compose up -d --build --wait    # + otel-collector, prometheus, loki, tempo, grafana
make ps

make check PYTHON=python
make test PYTHON=python
make telemetry-check PYTHON=python     # запрос -> лог -> trace, upload -> worker в одной трассе
make dashboard-check PYTHON=python     # provisioning и запросы всех панелей

Grafana: http://127.0.0.1:3000, пользователь admin, пароль — secrets/grafana_admin_password. Dashboard «Messenger lab6: API, worker, очередь, SLO» (папка Messenger) и три источника данных импортируются при старте из infra/grafana, вручную ничего не создаётся. Alerts: http://127.0.0.1:9090/alerts или make alerts.

Сценарии уровня 4: make incident-worker, make incident-db, make incident-db-down, make telemetry-outage, make telemetry-persistence. Проверки прошлых лаб остались (make student-test, db-test, test-failover, test-persistence, check-stack и др.).

Безопасная остановка: make down (volumes остаются, в том числе promdata, lokidata, tempodata, grafanadata). Намеренное удаление учебных данных: docker compose down -v, затем rm -rf secrets и снова sh scripts/init-secrets.sh.

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

клиент -> lb (HAProxy, 127.0.0.1:8080) -> api x2 -> postgres / valkey / s3 / broker -> worker      (как в lab5)

api x2, worker --OTLP/HTTP :4318--> otel-collector --> prometheus (метрики, alert rules)  127.0.0.1:9090
  (SDK: трассы, метрики, логи)        memory_limiter --> loki       (логи)
                                      batch, очереди --> tempo      (трассы)
prometheus <-- scrape: otel-collector:8888 (метрики самого Collector), lb:8404/metrics (ответы клиентам)
grafana (127.0.0.1:3000) --> prometheus, loki, tempo      сети: telemetry (internal), ops (только порты)
Роль Сервис Зачем
Сборщик otel-collector принимает OTLP от API и worker, ограничивает память и буферы, удаляет чувствительные атрибуты, отправляет в хранилища. Сам ничего не хранит
Метрики prometheus (volume promdata, 15 дней) числа во времени: RPS, ошибки, гистограммы задержек, очередь, пул. Считает alert rules
Логи loki (volume lokidata, 7 дней) структурные записи событий: что случилось, с каким trace_id, request_id
Трассы tempo (volume tempodata, 7 дней) путь одного запроса или задания через процессы: какой шаг сколько длился и где ошибка
Интерфейс grafana (volume grafanadata) dashboard и поиск по трём хранилищам. Сама сигналы не хранит

Что перенесено из lab5: весь код, миграции 001–006, свои тесты, Dockerfile, конфиги, скрипты. Бизнес-API не менялся.

Что добавлено:

  • src/messenger/telemetry.py: SDK трассы, метрики и логи по OTLP; ресурс service.name (messenger-api / messenger-worker), service.version, service.instance.id (hostname контейнера), deployment.environment.name=lab; JSON-логи в stdout и OTLP с event, trace_id, span_id; автоинструментация FastAPI, psycopg, botocore, CPU/RAM процесса.
  • Связь через очередь: в строку outbox пишется W3C traceparent span загрузки (jobs.enqueue). Relay создаёт PRODUCER span «send attachments» дочерним к нему и кладёт в сообщение уже свой traceparent. Worker создаёт CONSUMER span «process attachments.process» дочерним к PRODUCER. Повтор пишет в outbox traceparent span обработки, поэтому следующая попытка — в той же трассе. Без активного span (истёк lease, replay) копируется traceparent прошлой строки.
  • Выборка трасс: все трассы с родителем сохраняются целиком. Отбрасываются только CLIENT-спаны без родителя: опрос outbox раз в секунду, продление lease, проверка S3 для readiness. Иначе это была бы трасса в секунду из одного SQL.
  • src/messenger/queuestats.py: глубина очереди и возраст старейшего задания из PostgreSQL. Считаются в API, а не в worker, чтобы при остановленном worker график рос, а не пропадал.
  • infra/otel/collector.yaml, infra/prometheus/ (конфиг, rules/alerts.yml, runbooks.md), infra/loki/loki.yaml, infra/tempo/tempo.yaml, infra/grafana/ (provisioning и dashboards/messenger.json). HAProxy отдаёт метрики на :8404/metrics.
  • Точка отказа api_slow_handler (медленный обработчик для инцидента 2) и свои проверки lab6 в student-tests/.

Новые переменные (.env.example):

Переменная Значение
OTEL_SERVICE_NAME messenger-api (у worker в compose — messenger-worker)
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL http://otel-collector:4318, http/protobuf
OTEL_RESOURCE_ATTRIBUTES deployment.environment.name=lab
OTEL_SEMCONV_STABILITY_OPT_IN http: новые имена HTTP-метрик (http.server.request.duration в секундах)
OTEL_PROPAGATORS tracecontext: только traceparent/tracestate, без baggage (его нет в jobs.schema.json)
OTEL_METRIC_EXPORT_INTERVAL 10000 мс
OTEL_EXPORTER_OTLP_TIMEOUT 5. Python SDK читает это значение в секундах, а не в миллисекундах, как в спецификации

Сигналы: логическое имя → реальное имя

Сигнал (contracts/observability.md) Имя в SDK → в Prometheus Единица Labels
HTTP requests http.server.request.duration (count) → http_server_request_duration_seconds_count запросы http_request_method, http_route (шаблон), http_response_status_code; класс кода — =~"5.." в запросе
HTTP duration та же гистограмма → ..._bucket, ..._sum секунды то же + le; buckets 5 мс … 10 с
Jobs processed / failed messenger.jobs.processed → messenger_jobs_processed_total доставки messenger_job_type, outcome (ready, retry, failed, skipped, lost, db_unavailable, invalid)
Job processing duration messenger.job.duration → messenger_job_duration_seconds_* секунды messenger_job_type, outcome; buckets 0.1 … 120 с
Queue depth / oldest age messenger.queue.depth, messenger.queue.oldest_age → messenger_queue_depth, messenger_queue_oldest_age_seconds задания / секунды queue, state (ready, delayed, processing)
Outbox messenger.outbox.pending, .oldest_age, .published сообщения / секунды queue
DB pool db.client.connection.count, .max, .pending_requests → db_client_connection_* соединения db_client_connection_pool_name, db_client_connection_state (used, idle)
Worker saturation messenger.worker.busy, messenger.worker.capacity задания —
CPU / RAM процесса process.cpu.time, process.memory.usage → process_cpu_time_seconds_total, process_memory_usage_bytes секунды CPU / байты type (user, system)
End-to-end time to ready messenger.attachment.time_to_ready → messenger_attachment_time_to_ready_seconds_* секунды messenger_job_type; buckets 0.5 … 1800 с
Ответы клиентам на входе HAProxy haproxy_frontend_http_responses_total ответы proxy, code (2xx, 4xx, 5xx…)
Логи API и worker Loki: labels service_name, service_instance_id, deployment_environment_name; structured metadata event, severity_text, trace_id, span_id, request_id — —
Трассы SERVER (HTTP), PRODUCER (relay), CONSUMER (worker), INTERNAL (jobs.claim, image.process, jobs.complete/retry/fail), CLIENT (SQL, S3) мс статус ERROR при 5xx, retry, failed

Ресурс: service.name → label job в Prometheus и service_name в Loki; service.instance.id → instance и service_instance_id.

Не labels метрик: user_id, chat_id, message_id, attachment_id, request_id, raw URL, filename, текст. Маршрут — шаблон /api/v1/chats/{chat_id}/messages. make telemetry-check проверяет имена labels всех серий приложения. В логах и трассах есть только технические ID синтетических данных (request_id, attachment_id, job_id): по attachment_id находится трасса загрузки, по request_id (заголовок X-Request-Id) — лог и trace HTTP-ошибки. Пароли, Authorization, токены, тексты сообщений, картинки и query-строки в телеметрию не попадают. В логе запроса только маршрут-шаблон, а не путь. Collector дополнительно удаляет url.query, url.full, http.target и заголовки авторизации.

SLI, SLO и alerts

Окно SLO — скользящий 1 час (учебный стенд). Recording rules в infra/prometheus/rules/alerts.yml.

SLO SLI (запрос) Цель
SLO-1 доступность messenger:edge_availability:ratio1h = 1 − 5xx / все ответы фронтенда api_in HAProxy за 1 ч ≥ 99%
SLO-2 задержка messenger:http_latency_p95:5m = histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket{job="messenger-api"}[5m]))) < 0.5 с
SLO-3 обработка messenger:time_to_ready_under_30s:ratio1h = bucket le=30 / count за 1 ч ≥ 95%

Доля ошибок. Числитель — ответы 5xx клиентам на входе HAProxy, знаменатель — все ответы входа. Так считаются и 503, которые HAProxy отдаёт сам, когда нет готовой реплики (БД недоступна). 4xx (неверный пароль, чужой чат) — ошибка клиента, а не отказ сервиса. Проверки /health от HAProxy — не запросы фронтенда. Для поиска причины на dashboard есть и доля 5xx приложения (без /health).

Перцентили считаются только из buckets гистограммы, сложенных по всем репликам (sum by (le)). Не из средних и не как среднее p95 реплик.

Alert Условие Окно / for Зачем
HighErrorRate messenger:edge_error_ratio:rate2m > 0.05 и трафик > 0.2 запроса/с 2 мин / 1 мин SLO-1: клиенты получают 5xx
QueueLagHigh max by (queue) (messenger_queue_oldest_age_seconds) > 60 — / 1 мин задание ждёт worker дольше минуты
TelemetryExportFailing ошибки отправки exporter Collector или очередь > 20 пачек 2 мин / 1 мин хранилище телеметрии недоступно

Runbook для каждого — infra/prometheus/runbooks.md.

Ограниченная буферизация

  • SDK в процессе: трассы и логи — очередь до 2048 записей на сигнал, лишнее отбрасывается. Одна отправка — не дольше 5 с. Отправка идёт в фоновых потоках, запросы не ждут Collector.
  • Collector: memory_limiter (400 МиБ кучи при лимите контейнера 512 МиБ) первым в каждом pipeline, batch, у каждого exporter очередь до 200 пачек, повторы 1…30 с не дольше 5 минут, потом отбрасывание. Потери считаются в otelcol_exporter_send_failed_*, видны на панели «Конвейер телеметрии».

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS при включённой телеметрии evidence/test.txt
Структура skeleton и контракт не изменены make check PASS evidence/check.txt
3: минимум lab5 работает make student-test; make db-test; make test-failover; make test-persistence все тесты OK; failover и persistence PASS evidence/student-test.txt, db-test.txt, failover.txt, persistence.txt
3: Collector, три хранилища и Grafana в общем стенде, конфиги и provisioning в Git, volumes make check-stack; make telemetry-persistence 5 сервисов с закреплёнными версиями, volumes; после перезапуска Prometheus, Loki, Tempo, Grafana — та же трасса, тот же лог, то же значение метрики в прошлом evidence/stack.txt, telemetry-persistence.txt
3: API и worker отдают OTLP; RPS/errors/duration API, jobs и duration worker в Grafana make telemetry-check; make dashboard-check метрики обоих сервисов есть; каждый запрос панелей возвращает данные evidence/telemetry-check.txt, dashboard-check.txt
3: структурные логи и реальные трассы API и worker make telemetry-check лог: event, severity, service.name, trace_id, span_id; трасса с SERVER/PRODUCER/CONSUMER и SQL/S3 evidence/telemetry-check.txt
3: импортируемый dashboard, не screenshot make dashboard-check источники данных и dashboard provisioned (readOnly), панели совпадают с JSON в Git evidence/dashboard-check.txt
3: низкокардинальные labels, trace/span в логах, нет секретов и тел make telemetry-check нет labels с ID, маршруты — шаблоны; текст, пароль и токен — 0 совпадений в Loki и в атрибутах спанов evidence/telemetry-check.txt
3: контролируемый запрос → trace и лог; job → worker trace и лог make telemetry-check X-Request-Id → лог → trace с тем же request_id; задание → логи worker job.retry, job.ready с тем же trace_id evidence/telemetry-check.txt
3: make test при включённой телеметрии; назначение хранилищ make test; раздел «Архитектура» PASS; таблица ролей evidence/test.txt
4: W3C trace context API → broker → worker; producer/consumer parent-child; цепочка до S3/DB с retry make telemetry-check; make db-test одна трасса: SERVER → PRODUCER → CONSUMER (попытка 1, retry, ERROR) → jobs.retry → PRODUCER → CONSUMER (попытка 2, ready) → 4× S3 PutObject, SQL под jobs.complete; связи проверены по span_id evidence/telemetry-check.txt, db-test.txt
4: p50/p95/p99, доля ошибок, queue depth и возраст, DB pool, saturation worker; запросы и единицы make dashboard-check таблица «панель — единица — запрос»; перцентили из histogram evidence/dashboard-check.txt
4: SLI/SLO и окно; alert rules на error rate и queue lag infra/prometheus/rules/alerts.yml 3 SLO (окно 1 ч), HighErrorRate, QueueLagHigh, TelemetryExportFailing evidence/dashboard-check.txt
4: alerts проверены искусственным отказом, firing → resolved make incident-worker; make incident-db; make incident-db-down QueueLagHigh firing через 165 с после остановки worker, resolved через 83 с после запуска; HighErrorRate firing через 140 с после блокировки БД, resolved через 90 с после снятия; при pause postgres firing через ~120 с, resolved через 136 с после unpause evidence/incident-worker.txt, incident-db.txt, incident-db-down.txt
4: memory limiter, batch, ограниченная очередь; остановка хранилища не ломает API и RAM make telemetry-outage 3 мин без Tempo и Loki: 1742 сообщения и 38 загрузок без ошибок, куча Collector до 47 МиБ (< 400), RSS до 175 МиБ, очередь до 85 из 200 пачек, отброшено 0; 60 с без Collector — 550 ответов без ошибок, RSS API 147 → 148 МиБ evidence/telemetry-outage.txt
4: разбор двух инцидентов и шаги диагностики раздел «Эксперименты и отказы» worker остановлен; медленная и недоступная БД против медленного обработчика evidence/incident-worker.txt, incident-db.txt, incident-db-down.txt
Выбранный трек 5 — не выбран —

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

Стенд: один ноутбук, Docker Desktop (WSL 2), лимиты контейнеров из compose.yaml (api 1 CPU / 512 МиБ, worker 1 CPU / 1 ГиБ, Collector 0.5 CPU / 512 МиБ, хранилища по 1 CPU / 512 МиБ). Нагрузка — student-tests/traffic.py: 3 потока пишут сообщения с паузой 0.2–0.3 с, один ещё загружает картинку раз в 5 с. Ошибки не повторяются прозрачно, считается каждый ответ. Метрики отправляются раз в 10 с, Prometheus считает правила раз в 15 с.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановлен worker (incident-worker) API отвечает, задания копятся, возраст растёт, QueueLagHigh firing 2442 сообщения и 52 загрузки — 201/202; возраст старейшего задания рос на 1 с/с до 170 с; firing через 165 с; в трассе загрузки разрыв send → process 123 с при обработке 2,2 с resolved через 83 с после запуска worker; все 52 загрузки ready, потерь нет
Медленный обработчик, БД здорова (incident-db, A) длинный server span, короткие SQL, 5xx нет server span 1510 мс, из них в SQL 1,9 мс; 5xx нет, пул свободен после снятия точки отказа — сразу
Медленная БД: LOCK TABLE messages (incident-db, B) SQL-спан ~5 с с ошибкой, 503, HighErrorRate INSERT 5002 мс ERROR (statement_timeout), server span 5012 мс, 503; p95 POST сообщений ~7 с; заняты 3 соединения пула; firing через 140 с resolved через 90 с после снятия блокировки; 78 запросов получили 503 (клиент может повторить с тем же Idempotency-Key)
БД недоступна: pause postgres (incident-db-down) 5xx только на входе, у приложения нет запросов готовых реплик 0, HAProxy отвечает 503 сам, у приложения 0 запросов/с; пул занят (10 из 10), ждут соединение до 108 запросов; firing через ~120 с после unpause реплики готовы за ~15 с, resolved через 136 с (окно 2 мин); подтверждённые записи не потеряны
Остановлены Tempo и Loki на 3 мин (telemetry-outage) API работает, память и очередь ограничены бизнес-запросы без ошибок, куча Collector до 47 МиБ, очередь до 85 из 200 пачек, TelemetryExportFailing firing через ~135 с очереди разгрузились за 45 с после запуска; лог и трасса загрузки из середины отказа доехали, отброшено 0
Остановлен Collector на 60 с API работает, SDK не копит без предела 538 сообщений и 12 загрузок без ошибок, RSS реплики API 147 → 148 МиБ телеметрия этих 60 с сверх очереди SDK (2048 записей) потеряна, Collector эту потерю не видит

Инцидент 1: «картинки не обрабатываются» (worker остановлен)

Симптом: QueueLagHigh firing. Диагностика только по сохранённым наблюдениям:

  1. Панель «Возраст старейшего задания» растёт линейно, «Глубина очереди» (ready) растёт. Значит, задания не забирают.
  2. «Задания по исходу» — 0 доставок в секунду. При этом RPS и ошибки API в норме: проблема не в API.
  3. Логи worker: последнее событие worker.stopped, новых нет.
  4. Трасса загрузки, сделанной во время отказа: между send attachments и process attachments.process десятки секунд, сама обработка < 1 с. Задание ждало в очереди, медленной обработки нет.
  5. Причина — worker не работает. После docker compose start worker backlog уходит, alert resolved.

Инцидент 2: «сообщения отправляются с ошибкой» (медленная БД против медленного кода)

Симптом: HighErrorRate firing или рост p95.

  1. Панель «Ошибки: вход и приложение»: 5xx есть у приложения, значит ошибки отдаёт код API, реплики живы.
  2. «p95 по маршрутам»: медленный POST /chats/{chat_id}/messages.
  3. Лог с 5xx (event=http.request, severity WARNING) → кнопка «Открыть трассу».
  4. В трассе SQL INSERT длится ~5 с со статусом ERROR и занимает почти весь server span. Пул: заняты соединения. Это медленная БД, а не код.
  5. Для сравнения медленный код: server span ~1.5 с, все SQL-спаны по миллисекунде, 5xx нет. Время уходит внутри обработчика.
  6. Причина — блокировка таблицы (pg_locks). После снятия ошибки прекращаются, alert resolved.

Вариант «БД недоступна»: 5xx есть только на входе, у приложения запросов почти нет, готовых реплик 0, в логах неудачные /health/ready, в пуле растёт число ожидающих соединения. Значит, реплики выведены из балансировки, причина — зависимость readiness (PostgreSQL).

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

  • Всё на одном Docker-хосте. Хранилища телеметрии в одном экземпляре без репликации, Collector один: если он упадёт, телеметрия сверх очереди SDK теряется. Потери на стороне SDK не считаются метрикой, только потери Collector.
  • Метрики очереди считаются из PostgreSQL: когда недоступна сама БД, они пропадают, и QueueLagHigh в это время ничего не покажет. Эту ситуацию ловит HighErrorRate.
  • Серии, пришедшие по OTLP, не получают отметку устаревания: после остановки процесса его последние значения видны в Prometheus ещё до 5 минут.
  • CPU и память worker — без дочерних процессов обработки картинок. Лимит контейнера ограничивает их вместе.
  • Время до ready считается от начала транзакции загрузки (attachments.created_at), а не от COMMIT. Разница — миллисекунды.
  • Выборка трасс 100%: для учебной нагрузки это дёшево, на большой нагрузке нужна выборка с сохранением ошибок и медленных (трек 5.1).
  • Alerts без доставки наружу (Alertmanager не нужен по заданию). OTLP и хранилища без TLS и аутентификации внутри сети telemetry — это lab7.