Files
mtusi2026lab6/REPORT.md
T
2026-11-20 17:52:56 +03:00

26 KiB
Raw Blame History

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

Автор — Дыханова Алина, БВТ2301. Целевая оценка — 3. Реализация: Python 3.12.10, FastAPI 0.115.12, OpenTelemetry SDK/exporter 1.33.1. Зависимости закреплены в requirements.txt; версии инфраструктуры — в compose.yaml.

Запуск

Требуются Docker Compose v2, запущенный Docker, Python 3.9+ и make. В каталоге репозитория:

sh scripts/bootstrap.sh
# .env создаётся один раз со случайными локальными паролями, в Git не входит.
docker compose config --quiet
docker compose up -d --build
# Дождитесь HTTP 200 от этой команды перед запуском тестов.
curl -fsS http://localhost:8080/health/ready
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover-repeatable
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json

Команда test-failover-repeatable сначала запускает обе реплики, ждёт их ответов через балансировщик и затем выполняет неизменённый публичный failover-тест. После завершения (в том числе при ошибке) обе реплики запускаются снова. Обычный test-failover намеренно оставляет выбранную реплику остановленной.

Миграции выполняются API/worker автоматически под PostgreSQL advisory lock. Одноразовый s3-init создаёт приватный bucket, не удаляя существующие объекты.

API: http://localhost:8080; Grafana: http://localhost:3000 (admin; пароль GRAFANA_PASSWORD из локального .env). Dashboard Messenger observability provisioning импортирует автоматически. Prometheus: http://localhost:9090; Loki: localhost:3100; Tempo: localhost:3200. Порты привязаны к loopback, внутренние API/БД/broker/S3 наружу не опубликованы. Не публиковать docker compose config без --quiet: вывод содержит пароли.

Безопасная остановка: docker compose down (volumes остаются). Намеренное удаление всех учебных данных: docker compose down -v. После прямого запуска make test-failover восстановить обе реплики командой docker compose start api1 api2.

Архитектура

HAProxy проверяет /health/ready, распределяет запросы между готовыми репликами api1 и api2 по round robin и обновляет их адреса через DNS Docker. PostgreSQL хранит пользователей, сессии (SHA-256 случайного токена), чаты, сообщения, метаданные, idempotency и transactional outbox. Пароли — scrypt с индивидуальной солью. API не хранит пользовательские данные на локальном диске. Сессии общие для реплик. Idempotency сериализован advisory lock; сообщение и его ответ фиксируются одной транзакцией. Keyset pagination по (created_at,id) не обеспечивает snapshot при конкурентных вставках.

S3 реализован через chrislusf/seaweedfs:3.85: master, volume, filer и S3 gateway работают в одном процессе. Filer LevelDB и объекты сохраняются в volume seaweed. scripts/bootstrap.sh создаёт конфигурацию ключей в secrets/seaweed-s3.json вне Git; анонимная identity не настроена. s3-init использует boto3 из образа приложения.

При upload сначала проверяется PNG/JPEG и сохраняется полный оригинал в SeaweedFS staging, затем в одной транзакции PostgreSQL сохраняются queued-метаданные и outbox. Только после COMMIT возвращается 202. Relay в отдельном потоке worker публикует persistent RabbitMQ message в durable queue с publisher confirm; затем отмечает outbox sent. Разрыв после publish до COMMIT даёт повторную доставку. Worker держит row lock, публикует оригинал и JPEG thumbnail по детерминированным ключам и атомарно сохраняет ready. Ack — после COMMIT. Повтор уже готовой job не меняет результат. Смерть worker откатывает транзакцию, RabbitMQ повторно доставляет unacked job. Ручной replay уровня 4 не заявлен. Thumbnail: EXIF transpose, вписывание в 256×256 без увеличения, alpha на белом, JPEG quality 85.

Readiness требует DB и S3: без них синхронный путь небезопасен. Broker/worker могут временно не работать: PostgreSQL outbox сохраняет намерение. Telemetry не участвует в readiness. Образы, конфиги и persistent volumes всех трёх сигналов находятся в Compose.

API и worker отправляют метрики, логи и трассы в Collector по OTLP/HTTP. Prometheus считывает метрики с Collector каждые 5 с. Collector отправляет логи в Loki по OTLP/HTTP, а трассы в Tempo по OTLP/gRPC. Grafana запрашивает эти три источника и хранит собственные настройки, а не сами сигналы. Collector применяет memory_limiter и batch. Для экспортёров Loki и Tempo заданы очереди по 512 и 30-секундный предел повторных попыток. SDK использует очереди по 2048 для логов и трасс и тайм-аут 3 с для каждого OTLP-экспортёра. При длительном сбое возможны потери telemetry; это не заявляется как экспериментально проверенная отказоустойчивость. Prometheus/Tempo хранят историю 7 дней; у Loki в учебном стенде автоматическое удаление не настроено.

Сигналы и поиск

SDK → Prometheus Тип / единица Измерения
http_requests → http_requests_total counter, запросы method, route, status_class
http_duration → http_duration_seconds_bucket/sum/count histogram, секунды те же
worker_jobs → worker_jobs_total counter, попытки jobs job_type, outcome
worker_job_duration → worker_job_duration_seconds_bucket/sum/count histogram, секунды те же

Counter не имеет unit suffix; histogram SDK unit=s переводится в seconds. У failed/retry попыток outcome=error; успешная попытка и безопасный duplicate no-op — success. Worker histogram включает задержку перед retry. Dashboard считает API p95 по histogram всех реплик, RPS и 5xx/s, worker success/error и p95. Пустая серия error до первой ошибки нормальна. API ошибки здесь — 5xx; 4xx не считаются серверным отказом. Health исключён из API графиков. Resource: service.name, service.version=1.0.0, service.instance.id, deployment.environment.name=lab. Идентификаторы пользователей/чата/сообщений, URL и filename отсутствуют в labels метрик.

Логи идут в OTLP с timestamp, severity, resource, event, trace_id/span_id активного span. Только выделенный application logger экспортируется; тела, auth headers, пароли, исключения с внутренними значениями и изображения не записываются. Технические request_id/job_id допустимы для корреляции синтетического опыта, но не являются labels метрик.

Фактическое поступление метрик, логов и трасс подтверждено скриншотами Grafana. API log связан с health trace, worker log — с полной трассой загрузки; идентификаторы и наблюдаемые значения приведены в разделе разбора скриншотов. W3C traceparent передаётся в разрешённых полях job. Spans: server HTTP, consumer attachment.process, S3 stage/read/publish и db.ready. Отдельный producer span уровня 4 не заявлен.

Для ручного поиска: в Grafana Explore выбрать Tempo, запросить trace ID из X-Trace-Id контролируемого upload; в Loki использовать:

{service_name=~"messenger-api|messenger-worker"} | trace_id="TRACE_ID"

Request ID из X-Request-Id находится в structured metadata API log. Для worker event=job.completed. Пример PromQL: sum by (outcome) (rate(worker_jobs_total[1m])).

Фактические результаты

Проверка Результат Доказательство
make check PASS, структура/ссылки/синтаксис локальная проверка
docker compose config --quiet PASS локальная проверка
docker compose ps -a Обе API healthy, DB/broker healthy, worker и все telemetry-сервисы Up; s3-init Exited (0) evidence/operator-results.md
make test PASS: lab6 public API scenario evidence/operator-results.md
make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: данные и существующая сессия сохранены evidence/operator-results.md
make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS: 2 реплики, 54 успешные записи, 4 неудачные попытки; восстановление записи 2.696 с evidence/operator-results.md
Нагрузка: 30 с, 4 клиента 12773 успешных запроса, 0 ошибок, 424.445 RPS evidence/load.json
Метрики, связанные логи и реальные traces Подтверждены dashboard, логами API/worker и трассами Tempo раздел «Что показала Grafana»
make test-failover-repeatable (20.11.2026) PASS: 2 реплики до отказа, 54 успешные записи, 4 неудачные попытки, первая успешная запись через 2,355 с от запуска hook evidence/operator-results.md
Отказ worker PASS: при остановленном worker вложение осталось queued, после запуска перешло в ready, оригинал совпал побайтно раздел «Наблюдения при остановке worker»
Диагностика отказов по телеметрии Для worker подтверждена связь запроса API и обработки по одному trace ID в Loki и Tempo. В Loki за интервал failover подтверждена успешная запись через api2 сценарии в разделе «Повторяемые инциденты после запуска»

Persistence hook перезапускает api1/api2, worker, PostgreSQL, S3, broker, Collector, Prometheus, Loki, Tempo, Grafana и LB без удаления volumes. Вывод теста подтверждает сохранность данных и сессии. Для отдельного подтверждения перезапуска PostgreSQL нужны значения StartedAt до и после теста.

Результаты нагрузки

Длительность по часам клиента — 30.093 с. p50 = 8.683 мс, p95 = 12.634 мс, p99 = 23.901 мс, error ratio = 0. Это closed-loop тест POST сообщений без retry, percentile относится только к успешным запросам. Один запуск не определяет максимальную производительность; CPU/RAM и повторные измерения не собирались.

Что показала Grafana

В наблюдениях ниже указано время, которое отображалось в Grafana. Данные относятся к сервисам messenger-api и messenger-worker.

Dashboard Messenger observability

На первом снимке видны RPS, API p95, worker success и часть нижних панелей. Второй снимок дополняет его целиком видимым worker p95 и панелью логов. Легенда RPS содержит api1/api2, кривые близки и местами перекрываются. Видны всплески нагрузки и успешной фоновой обработки. Worker серия имеет outcome=success; ошибочная попытка worker отдельным экспериментом не продемонстрирована.

API 5xx/s показывает No data. Это отсутствие результата запроса за выбранное окно, а не доказательство точного нулевого числа всех ошибок. В частности, ошибки соединения/ответы HAProxy во время остановки API не обязаны попадать в счётчик API. Число неудачных клиентских попыток измерено отдельно в failover-тесте.

API p95 и worker p95 на dashboard находятся примерно около 4.75 с, тогда как индивидуальные логи показывают десятки миллисекунд. Эти числа нельзя считать точным измерением p95: в текущем SDK используются стандартные границы histogram, слишком грубые для таких задержек. Интерполяция внутри широкого bucket может дать около 4.75 с даже для быстрых запросов. Следует подобрать границы histogram под миллисекундные операции и повторить измерение; на этих снимках подтверждены поступление histogram и построение графика, но не точность percentile. Клиентские p95/p99 нагрузки приведены отдельно в evidence/load.json.

Структурный лог API

Поле Наблюдаемое значение
event http.request
service_name / instance messenger-api / api2
method / route GET /health/ready
status_code / status_class 200 / 2xx
severity_text INFO
duration_seconds 0.023972624999942127, около 23.97 мс
request_id 4356468e1d0445369fc7a545391650f8
trace_id 0bfcaa8384a34151aee4ae0d4387441d
span_id efba4f6db4f921fa
service_version / SDK 1.0.0 / OpenTelemetry Python 1.33.1

Видны технические атрибуты, а также переход Tempo с тем же trace ID. В показанной записи нет Authorization, пароля, session token или тела сообщения. Это наблюдение по данной записи, а не исчерпывающая проверка всей истории логов.

Трасса API, найденная по логу

Tempo показывает trace 0bfcaa8384a34151aee4ae0d4387441d, один span messenger-api GET /health/ready, ответ 200, длительность 24.3 мс; отображённое начало — 16.11.2026 23:41:24.138. Идентификатор совпадает с приведённым выше логом API. Поэтому подтверждён поиск реальной трассы по структурному логу API. Различие 23.97 мс в логе и 24.3 мс в span допустимо: длительность span включает небольшую дополнительную работу внутри instrumentation после измерения handler. Health не порождает job, поэтому отсутствие worker здесь ожидаемо.

Поиск логов фоновой обработки

Запрос {service_name="messenger-worker"} |= "job.completed" за выбранный час вернул шесть записей уровня INFO. На снимке видны события в 23:21:36.777, 23:31:51.507, 23:32:25.454, 23:32:44.937, 23:32:51.303 и 23:36:07.536. Это подтверждает поступление логов отдельного worker в Loki, а не только логов API.

Структурный лог успешной job

Поле Наблюдаемое значение
event / service_name job.completed / messenger-worker
job_type attachment.process.v1
job_id a2423f62-c19f-440a-9bde-f3d430562449
attempt / outcome 1 / success
duration_seconds 0.028629083000168976, около 28.63 мс
severity_text INFO
trace_id 0dc6e36ad05603919332b5957929c909
span_id cd3240b3016bc139

Job ID используется для корреляции лога, не как label метрики. Переход Tempo содержит тот же trace ID. Подтверждены структурные поля, исход обработки и связь job с трассой.

Сквозная трасса upload → worker → S3/DB

В Tempo открыт trace 0dc6e36ad05603919332b5957929c909, совпадающий с идентификатором в логе worker. Начало — 16.11.2026 23:36:07.305, API вернул 202. В трассе семь spans:

Сервис / операция Длительность на снимке
messenger-api POST /api/v1/chats/{chat_id}/attachments 10.96 мс
s3.stage 4.78 мс
messenger-worker attachment.process 28.55 мс
s3.read_staging 9.93 мс
image.thumbnail 2.61 мс
s3.publish 7.25 мс
db.ready 255.96 мкс

Общая временная протяжённость trace — 231.67 мс. Это не длительность HTTP-ответа: в неё входит интервал между API и запуском фоновой обработки. Его нельзя напрямую объявлять метрикой глубины/возраста очереди. Вложенность worker под API показывает перенос trace context; длительности consumer log и span близки. Видны этапы чтения исходника, thumbnail, записи результата и публикации ready в БД. Повторная попытка (retry) в этом опыте отсутствует; уровень 4 целиком не заявляется.

Повторяемые инциденты после запуска

  1. Запустить python3 scripts/test-worker-outage.py. Скрипт останавливает worker, загружает PNG, проверяет статус queued и печатает trace ID. Затем он запускает worker, дожидается ready и сверяет загруженный оригинал байт в байт. В Tempo найдите HTTP span загрузки и последующий attachment.process по напечатанному trace ID. В Loki найдите http.request и job.completed по тому же идентификатору. Интервал между HTTP span и worker span показывает ожидание обработки в этом опыте.
  2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Hook останавливает именно реплику TARGET_INSTANCE_ID; тест проверяет запись через другую реплику и отсутствие дублей. По метрикам отдельных service_instance_id и логам определить исчезнувшую реплику. Восстановить docker compose start api1 api2. Сохранить результат и запросы наблюдений.

Наблюдения при остановке worker

Проверка прошла 20 ноября 2026 года с 17:31:25 до 17:31:37 МСК. API принял вложение в статусе queued при остановленном worker. После запуска worker скрипт дождался ready и подтвердил побайтовое совпадение скачанного файла с оригиналом.

В Loki запрос по trace_id=dc807159c626aaf72c9ae58641117383 вернул две записи:

Время UTC Сервис Событие
14:31:33.540 messenger-api http.request
14:31:34.694 messenger-worker job.completed

Между записями прошло 1,154 с. Интервал измерен от записи события HTTP до записи завершения задания и включает ожидание и обработку.

В Tempo та же трасса содержит семь spans. API принял загрузку с HTTP 202 за 16,07 мс, включая запись исходника в S3 staging за 5,61 мс. После запуска worker операция attachment.process заняла 79,61 мс. Внутри неё видны чтение исходника из staging (65,4 мс), создание миниатюры (4,26 мс), публикация в S3 (5,18 мс) и запись статуса ready в БД (240,54 мкс). Вся трасса заняла около 1,17 с, включая интервал между ответом API и началом фоновой обработки.

Наблюдения при отказе API-реплики

Повторная проверка прошла 20 ноября 2026 года с 17:41:06 до 17:41:32 МСК. До остановки api1 балансировщик обслуживал запросы через обе реплики. После остановки запись продолжилась через api2. За прогон получено 54 успешных записи и 4 неудачные клиентские попытки. Первая успешная запись после завершения hook зафиксирована через 2,355 с от его запуска. Тест подтвердил сохранность подтверждённых сообщений и существующей сессии. После завершения сценарий запустил api1. При проверке состояния api2 была healthy, а api1 ещё проходила проверку готовности (health: starting).

В Loki запрос ниже показал, что в 17:41:28.589 МСК реплика api2 успешно обработала создание сообщения с ответом HTTP 201 за 10,35 мс. Идентификатор трассы — 82a1d11fa18230512035ebcd76cb3a35.

{service_name="messenger-api"} |= "http.request" | method="POST" | route="/api/v1/chats/{chat_id}/messages" | status_code="201"

Ограничения

Один экземпляр DB/S3/broker/LB и один Docker host: их HA не обеспечено. Обработка изображения держит DB транзакцию; statement_timeout 10s, job deadline отдельно не реализован. Staging пока сохраняется для повторов без автоматического cleanup; STAGING_RETENTION_SECONDS из skeleton не реализован. Старые outbox/idempotency/session rows автоматически не чистятся; expiry проверяется при использовании. Диск следует освобождать осознанным сбросом учебного стенда. Не заявлены queue lag/pool metrics, SLO, alert rules, sampling research и прочие требования 4/5. Внешние credentials передаются контейнерам через локальный .env; интерфейс *_FILE поддерживается приложением, но Compose использует прямые переменные. Прочие переменные .env.example — варианты контракта skeleton, а не обещание реализации: APP_PORT фиксирован 8080, реплик ровно две, worker имеет один consumer, SESSION_STORE=PostgreSQL. Никакой Redis для этой оценки не требуется.

Первичные материалы