Files
mtusi2026lab6-fork/REPORT.md

23 KiB
Raw Permalink Blame History

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

  • Автор — Любченко Никита, БПИ2303.
  • Целевая оценка — 4. Трек 5 не заявлен.
  • Использованы Python 3.12, OpenTelemetry SDK 1.38.0, semantic conventions 0.59b0, Collector contrib 0.123.0, Prometheus 3.2.1, Loki 3.4.2, Tempo 2.7.2, Grafana 11.6.0 и компоненты lab5. ИИ использован при разработке и проверке реализации.
  • Ссылку на PR добавляет автор после публикации. Результаты проверок приведены в evidence/.

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

Требуются Docker Engine с Compose, Make и Python 3.9+ для публичных проверок. Первая сборка обращается к реестрам образов, PyPI и исходникам MinIO. Приложение работает на Python 3.12. Изображения обрабатываются Pillow. Go используется при сборке MinIO и mc из исходников.

cp -n .env.example .env
python3 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env build
docker compose --env-file .env up -d --no-build
python3 scripts/manage.py status
python3 scripts/wait_ready.py
make check
make test
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
make test-observability

API доступен через Nginx на http://localhost:18083. Grafana — http://localhost:13000, логин admin. Пароль читается из secrets/grafana_password. Prometheus — http://localhost:19090. Loki и Tempo имеют loopback HTTP-порты 13100 и 13200 для воспроизводимых проверок. OTLP и внутренние API-порты на хост не опубликованы. Dashboard Messenger и три источника данных подключаются provisioning автоматически.

Bootstrap создаёт локальные secrets с ограниченными правами, сохраняет уже существующие значения и не печатает их. .env, secrets/ и .venv/ исключены из Git. Безопасная остановка — docker compose down. Намеренное удаление всех учебных данных текущего проекта — docker compose down -v.

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

Перенесены Nginx, две API-реплики, PostgreSQL, Redis, приватный MinIO, RabbitMQ, publisher, worker и cleaner из lab5. PostgreSQL остаётся источником истины. API сохраняет исходник в S3 и фиксирует queued, job и outbox одной транзакцией перед ответом 202. Издатель использует publisher confirms. Воркер сохраняет три варианта, фиксирует ready, затем подтверждает сообщение брокеру. Lease, retry/backoff, fencing по attempt, replay и очистка сохранены.

Добавлен путь API/publisher/worker → OTLP/gRPC → Collector → Prometheus/Loki/Tempo → Grafana. Prometheus хранит числовые временные ряды, Loki — структурные логи, Tempo — трассы. Grafana выполняет запросы к этим источникам. У хранилищ собственные volumes, retention сигналов составляет 72 часа. Collector обрабатывает и экспортирует данные.

Миграция 0006 добавляет trace_context jsonb в attachment_jobs. Контекст сохраняется вместе с заданием. Издатель создаёт producer span с родителем из сохранённого контекста и передаёт traceparent/tracestate в AMQP headers. Consumer продолжает этот контекст. Повторные попытки имеют общий исходный trace и отдельные producer/consumer spans. Старые задания получают пустой контекст и обрабатываются обычным способом.

Ресурсы содержат service.name (messenger-api, messenger-publisher, messenger-worker), service.version, service.instance.id и deployment.environment.name=lab. Логи включают timestamp, severity, event, request_id и trace_id/span_id при активном span. HTTP возвращает X-Request-Id и дополнительный X-Trace-Id. SQL-тексты, значения параметров, Authorization, пароли, signed URL, тела сообщений и изображения в инструментацию не передаются. OTLP bridge отбрасывает полный текст исключений и traceback. Технический job.id допустим для синтетических traces/logs. В metric labels его нет.

Сигналы и запросы

Сигнал Реальное имя в Prometheus Единица
HTTP count messenger_http_requests_total запросы
HTTP duration messenger_http_duration_seconds_bucket секунды, histogram
Jobs messenger_jobs_processed_total попытки, outcome success/error/stale
Processing duration messenger_job_duration_seconds_bucket секунды одной попытки
Accepted-to-ready messenger_attachment_time_to_ready_seconds_bucket секунды до фиксации ready
Backlog messenger_queue_depth queued + processing, включая outbox/retry
Broker ready messenger_queue_broker_ready ожидающие доставки сообщения RabbitMQ
Oldest age messenger_queue_oldest_age_seconds возраст старейшего незавершённого задания
Backlog freshness messenger_queue_observed_at_seconds Unix timestamp последнего опроса
DB pool messenger_db_pool_used, messenger_db_pool_waiting, messenger_db_pool_capacity соединения / запросы на получение
Pool exhaustion messenger_db_pool_exhausted_total отказы получения соединения
Pool acquisition messenger_db_pool_acquire_seconds_bucket секунды
Worker messenger_worker_busy, messenger_worker_capacity занятые / доступные обработчики
Memory messenger_process_memory_bytes текущий RSS процесса, байты
CPU messenger_process_cpu_seconds_total накопленное процессорное время, секунды

HTTP labels содержат method, route template и status_class. Health исключён из бизнес-счётчиков. Неизвестные маршруты сводятся к unmatched. Histogram boundaries — 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 30, 60, 120 секунд и +Inf. Pool waiting измеряет поток во время вызова getconn. Пул psycopg2 немедленно отказывает при исчерпании ёмкости, длительного ожидания свободного соединения в нём нет.

Time to ready начинается с clock_timestamp при регистрации задания после PUT исходника, непосредственно перед COMMIT принятия, и заканчивается после COMMIT ready. Начальная точка приближает границу durable acceptance с точностью до оставшейся части транзакции. Метрика записывается только после успешного COMMIT результата. При аварии процесса сразу после COMMIT отдельное наблюдение может отсутствовать. Бизнес-состояние восстанавливается из PostgreSQL.

Запросы dashboard сохранены в infra/grafana/dashboards/messenger.json. Например, p95 всех реплик вычисляется из объединённых buckets.

sum by (method, route) (rate(messenger_http_requests_total[1m]))
histogram_quantile(0.95, sum by (le) (rate(messenger_http_duration_seconds_bucket[1m])))
rate(messenger_process_cpu_seconds_total[1m])
messenger_queue_oldest_age_seconds

p50 и p99 отличаются аргументом histogram_quantile. Метрика CPU rate выражена в занятых ядрах. Backlog, processing duration и end-to-end time показывают разные части обработки. Логи ищутся в Loki запросом {service_name=~"messenger-.*"} |= "<trace_id>". Tempo принимает поиск по trace ID и TraceQL {resource.service.name = "messenger-worker"}.

SLI, SLO и алерты

SLI — доля бизнес-запросов без 5xx за скользящие 5 минут. SLO ≥99%. 4xx входят в знаменатель и не считаются отказом сервера. При отсутствии запросов SLI не оценивается. Этот SLI отражает запросы, дошедшие до API. Ошибки самого Nginx и отсутствие входящего трафика требуют внешнего probe.

HighApiErrorRate срабатывает при доле 5xx >1% за 1 минуту, for 6 секунд. QueueLagGrowing срабатывает при oldest age >15 секунд и backlog >0, for 6 секунд. QueueObservationStale показывает, что publisher перестал обновлять состояние очереди. Правила сохранены в infra/prometheus/alerts.yaml. Runbook находится в infra/runbook.md. Локальные firing/resolved проверяются через Prometheus API.

Ограничение памяти и отказ телеметрии

У SDK очереди до 256 spans и 256 logs на процесс, batch 64, export timeout 1 секунда. Метрики экспортируются каждые 3 секунды. SDK передаёт телеметрию фоновыми потоками.

Collector применяет memory_limiter 128 MiB со spike 32 MiB, batch до 512 записей, очереди Loki/Tempo до 128 batches каждая, два consumer на экспортёр. Retry ограничен 10 секундами, timeout отдельного экспорта 2 секунды. Контейнер ограничен 192 MiB. При недоступности backend часть наблюдений может теряться. Prometheus забирает данные pull-запросами, остановка Prometheus создаёт пробел в истории scrape. Для логов и трасс проверяется отказ push backend Tempo.

Внутренние accepted/sent/send_failed/enqueue_failed counters Collector позволяют увидеть деградацию экспорта. send_failed показывает отказ экспорта. Потери в контролируемом окне дополнительно подсчитываются по dropped_items в журнале Collector. Точное число уникальных потерь во всей цепочке по одному counter не вычисляется.

Проверки и эксперименты

Файлы stage1-* относятся к переносу основы до включения полного стека наблюдаемости. Итоговые доказательства приведены ниже.

Критерий Сценарий / результат Доказательство
Структура и схема API make check, make validate evidence/check.txt, evidence/validate.txt
Бизнес-API с телеметрией make test evidence/smoke.txt
Метрики, логи и реальные traces API/worker make test-observability, проверены имена сигналов и логи трёх процессов evidence/observability-smoke.json
W3C propagation и связь S3/DB Parent-child spans, сохранён tracestate, внешний traceparent принят API evidence/observability-smoke.json
Retry в исходном trace Две consumer-попытки, ready после восстановления S3 evidence/observability-retry.json
Dashboard и datasources Provisioning 14 панелей, проверены все PromQL и поиск Tempo через Grafana evidence/observability-smoke.json, infra/grafana
Percentiles, backlog, oldest age, DB pool, worker saturation, CPU/RAM Histogram buckets и gauge/counters, единицы указаны выше infra/grafana/dashboards/messenger.json
SLI/SLO и локальные alerts promtool, firing/resolved для error rate и queue lag evidence/alert-config.txt, evidence/observability-worker-stop.json, evidence/observability-db-outage.json
Остановка worker Алерт firing через 30,1 с, после восстановления задание ready, алерт resolved evidence/observability-worker-stop.json
Задержка PostgreSQL 8 запросов получили 503, client span показывает ошибку БД, алерт firing/resolved evidence/observability-db-outage.json
Отказ Tempo 138 успешных сообщений, вложение ready, потеря 248 spans по dropped_items, без OOM/рестартов evidence/observability-backend-outage.json
История сигналов после перезапуска Сохранены исходная trace, логи трёх процессов и historical metric sample evidence/telemetry-persistence.json
Сохранность бизнес-данных и отказ реплики Публичные persistence/failover evidence/persistence.txt, evidence/failover.txt
Полная HTTP duration Регрессионная проверка включает отправку тела evidence/http-timing.txt

Нагрузка

Docker Engine 29.5.3, Compose 5.1.4, aarch64, 10 доступных CPU и около 7,75 GiB RAM в VM. Лимиты API — по 0,5 CPU/256 MiB, worker — 1 CPU/768 MiB, Collector — 0,5 CPU/192 MiB. Параметры среды сохранены в evidence/environment.json.

make load выполнял closed-loop POST сообщений 30 секунд, concurrency 4, без автоматических повторов. Выполнено 14 048 успешных запросов, ошибок 0, 467,941 RPS. Клиентские latency успешных запросов — p50 5,119 ms, p95 33,476 ms, p99 81,147 ms. Это один прогон, отдельного прогрева не было. Percentiles клиента охватывают только успехи и подвержены coordinated omission. Они дополняют histogram dashboard. Результат не заявляется как максимальная пропускная способность. Raw summary — evidence/load-output.txt.

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

При продолжающемся приёме upload возраст незавершённого задания превысил 15 секунд, backlog оставался положительным. QueueLagGrowing перешёл в firing примерно через 30,1 секунды после загрузки. По метрикам видно ожидание обработки, producer span опубликован, consumer появляется после запуска worker. После восстановления job достигла ready, backlog уменьшился, алерт resolved. Диагностика выполняется по сохранённым возрасту/глубине очереди, состоянию alert и связанной trace. Сценарий — python3 student-tests/observability.py worker-stop.

Инцидент 2. Ожидание PostgreSQL

Сценарий удерживает ACCESS EXCLUSIVE lock таблицы users 35 секунд. Восемь GET /users/me завершились 503 вследствие statement_timeout. В trace длительный postgresql.transaction имеет error status, что локализует задержку в БД. HighApiErrorRate перешёл в firing, после снятия блокировки запросы восстановились, alert resolved. Сценарий — python3 student-tests/observability.py db-outage.

Во время разработки выявлено, что retry HTTP 503 в Nginx временно исключал обе реплики при общем тайм-ауте БД и приводил к 502. Теперь Nginx передаёт 503 клиенту. Переключение при сетевых ошибках и active readiness сохранено и проверено публичным failover. Старая и новая серии gauge после рестарта publisher различаются по service.instance.id. Dashboard и alerts используют freshness, чтобы устаревший экземпляр не создавал ложный queue alert.

Недоступность telemetry backend

Tempo был остановлен на время последовательной записи сообщений и обработки изображения. SDK/Collector продолжили ограниченный экспорт с retry и drops. Успешно записано 138 сообщений, изображение стало ready. Collector зарегистрировал 248 dropped spans. Это число явно отброшенных записей данного exporter за окно, общая оценка уникальных потерь по всей системе не заявляется. Send-failed сравнивался до/после отказа.

Наблюдаемый RSS Collector находился примерно в пределах 92–97 MiB при лимите 192 MiB, API — около 74–76 MiB, worker — около 63 MiB, publisher — около 34 MiB. Контейнеры работали без OOM и автоматических перезапусков. Измерение длилось около 40 секунд и подтверждает поведение данного сценария. Конфигурация задаёт конечные очереди и memory limiter для более длительной недоступности. После запуска Tempo найдены новые связанные trace и логи. Сценарий — python3 student-tests/observability.py backend-outage.

Воспроизведение

make test-observability
docker compose exec -T api-a python - < student-tests/http_timing.py
python3 student-tests/observability.py worker-stop
python3 student-tests/observability.py db-outage
python3 student-tests/observability.py retry
python3 student-tests/observability.py backend-outage
python3 student-tests/telemetry_persistence.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 scripts/manage.py restore

Fault-сценарии выполняются по одному. Для проверки retry worker запускается через docker start, чтобы Compose не поднял остановленный S3 как dependency. PostgreSQL lock освобождается по завершении ограниченного pg_sleep. Все проверки используют синтетические данные.

Ограничения

Стенд учебный, single-node. PostgreSQL, MinIO, RabbitMQ и telemetry backend представлены одиночными экземплярами. Авторизация Grafana локальная, TLS относится к следующей лабораторной. Sampling по умолчанию 100%, исследовательские треки на 5 не заявлены. Старые вспомогательные student-tests предыдущих лабораторных могут требовать специальных условий, например остановленного worker. Для lab6 использовать make test и student-tests/observability.py.

Источники

Соответствие переменных окружения

Compose задаёт служебные адреса и пути secrets внутри контейнеров. PUBLIC_PORT и JOB_MAX_ATTEMPTS читаются из локального .env. API использует SESSION_STORE=redis. DATABASE_URL_FILE, CACHE_URL_FILE, CURSOR_SECRET_FILE и S3_*_FILE указывают на secrets. Издатель и worker получают RABBITMQ_PASSWORD_FILE, подключаются к rabbitmq:5672 под локальным пользователем lab6. BROKER_URL_FILE из исходной заготовки заменён этой настройкой.

В данной реализации один worker-процесс обрабатывает одно задание с prefetch 1. WORKER_CONCURRENCY=1 описывает эту ёмкость. Тайм-аут попытки фиксирован на 20 секундах, lease на 60 секундах. MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS и STAGING_RETENTION_SECONDS соответствуют константам перенесённого приложения. Изменять эти поля .env отдельно от кода не следует. OTEL_SERVICE_NAME и endpoint задаются Compose отдельно для каждого процесса, используется grpc на 4317. Параметры SDK/Collector приведены выше и закреплены в коде и YAML.