28 KiB
Отчёт — лабораторная 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
traceparentspan загрузки (jobs.enqueue). Relay создаёт PRODUCER span «send attachments» дочерним к нему и кладёт в сообщение уже свойtraceparent. Worker создаёт CONSUMER span «process attachments.process» дочерним к PRODUCER. Повтор пишет в outboxtraceparentspan обработки, поэтому следующая попытка — в той же трассе. Без активного 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. Диагностика только по сохранённым наблюдениям:
- Панель «Возраст старейшего задания» растёт линейно, «Глубина очереди» (ready) растёт. Значит, задания не забирают.
- «Задания по исходу» — 0 доставок в секунду. При этом RPS и ошибки API в норме: проблема не в API.
- Логи worker: последнее событие
worker.stopped, новых нет. - Трасса загрузки, сделанной во время отказа: между
send attachmentsиprocess attachments.processдесятки секунд, сама обработка < 1 с. Задание ждало в очереди, медленной обработки нет. - Причина — worker не работает. После
docker compose start workerbacklog уходит, alert resolved.
Инцидент 2: «сообщения отправляются с ошибкой» (медленная БД против медленного кода)
Симптом: HighErrorRate firing или рост p95.
- Панель «Ошибки: вход и приложение»: 5xx есть у приложения, значит ошибки отдаёт код API, реплики живы.
- «p95 по маршрутам»: медленный POST
/chats/{chat_id}/messages. - Лог с 5xx (
event=http.request, severity WARNING) → кнопка «Открыть трассу». - В трассе SQL INSERT длится ~5 с со статусом ERROR и занимает почти весь server span. Пул: заняты соединения. Это медленная БД, а не код.
- Для сравнения медленный код: server span ~1.5 с, все SQL-спаны по миллисекунде, 5xx нет. Время уходит внутри обработчика.
- Причина — блокировка таблицы (
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.