26 KiB
Отчёт — лабораторная 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 целиком не заявляется.
Повторяемые инциденты после запуска
- Запустить
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 показывает ожидание обработки в этом опыте. - Запустить
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 для этой оценки не требуется.
Первичные материалы
- https://opentelemetry.io/docs/collector/configuration/
- https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.128.0/exporter/prometheusexporter
- https://grafana.com/docs/loki/latest/send-data/otel/
- https://grafana.com/docs/grafana/latest/administration/provisioning/
- https://www.rabbitmq.com/docs/reliability