32 KiB
Отчёт — лабораторная 6
- Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 1 «Цена наблюдаемости»
- Commit/PR: ветка
solution/bpi2302-kushnarenkoв своём форке; текущие проверки от 12.11.2026 - Использованные источники, библиотеки и помощь ИИ: Python 3.12, OpenTelemetry Python SDK 1.45.0 (traces/metrics/logs, OTLP/HTTP), uvicorn, asyncpg, aiobotocore, aio-pika, Pillow; OpenTelemetry Collector contrib 0.161.0, Prometheus 3.15.0, Loki 3.7.8, Tempo 2.9.0, Grafana 13.2.3; RabbitMQ 4.1.8, SeaweedFS 4.48, PostgreSQL 17, Valkey 8, HAProxy 3.0. Код lab5 перенесён, бизнес-API не менялся. ИИ-ассистенты Claude/Codex использовались для помощи с кодом, тестами и оформлением; результаты ниже получены реальными запусками
Запуск из чистого clone
Prerequisites: Docker Compose v2+ (выделить Docker не менее 7 ГиБ RAM; сумма лимитов контейнеров ≈6.1 ГиБ), bash (Git Bash на Windows), Python ≥ 3.9 для публичных тестов, Python ≥ 3.11 для исследований; на Windows PYTHONUTF8=1.
Версии всех образов закреплены тегом и digest в compose.yaml; зависимости — requirements.txt (включая opentelemetry-*==1.45.0).
sh scripts/init-secrets.sh # secrets/*: БД, S3, RabbitMQ, пароль Grafana (secrets/grafana_admin_password)
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180
curl http://127.0.0.1:8080/health/ready # API
# Grafana: http://127.0.0.1:3000 пользователь admin, пароль — secrets/grafana_admin_password
python3 -m pip install -r research/requirements.txt -r requirements-dev.txt
python3 scripts/check_contract.py # make check
python3 scripts/validate_openapi.py # make validate
python3 tests/smoke.py --base-url http://127.0.0.1:8080 # make test (телеметрия включена)
python3 -m unittest discover -s student-tests -p test_observability.py -v # метрики, логи, трассы, связь API -> worker, отсутствие секретов
python3 student-tests/test_observability_retry.py # все попытки задания в одной трассе
mkdir -p evidence/my-run
python3 research/incidents.py --out evidence/my-run
python3 research/obs_cost.py --out evidence/my-run --profiles off on100 head10 tail --repeat 2
python3 research/plot_obs_cost.py --out evidence/my-run
Windows: scripts/restart.cmd, scripts/stop-one.cmd. Остановка с сохранением данных — docker compose --env-file .env stop; намеренное удаление учебных данных — docker compose --env-file .env down -v (volumes pgdata, valkeydata, seaweeddata, rabbitmqdata, promdata, lokidata, tempodata, grafanadata).
Профиль без телеметрии: OTEL_ENABLED=0; head-sampling: OTEL_TRACES_SAMPLER_ARG=0.1; tail-sampling в Collector: COLLECTOR_CONFIG=/etc/otelcol/collector-tail.yaml.
Архитектура и решения
API ×2 ─┐ ┌─▶ Prometheus (метрики, retention 7 д, volume promdata)
├─OTLP/HTTP─▶ OTel Collector ─┼─▶ Tempo (трассы, retention 7 д, volume tempodata)
worker ─┘ (memory_limiter, batch, └─▶ Loki (логи, retention 7 д, volume lokidata)
scrub, tail_sampling*) ▲
traceparent: API ─▶ outbox ─▶ RabbitMQ ─▶ worker Grafana (127.0.0.1:3000) читает все три источника
| Роль | Сервис | Версия | Порты | Volume | Зачем |
|---|---|---|---|---|---|
| Collector | otel-collector |
contrib 0.161.0 | OTLP 4317/4318, метрики 8888/8889 — только сеть backend | — | единая точка приёма, ограничение RAM, удаление чувствительных атрибутов, маршрутизация сигналов; это не хранилище |
| Метрики | prometheus |
3.15.0 | не публикуется | promdata |
временные ряды, SLI/recording rules, alert rules, firing/resolved |
| Логи | loki |
3.7.8 | не публикуется | lokidata |
структурные логи API и worker (OTLP), поиск по trace_id |
| Трассы | tempo |
2.9.0 | не публикуется | tempodata |
распределённые трассы, TraceQL |
| UI | grafana |
13.2.3 | 127.0.0.1:3000 |
grafanadata |
datasources/dashboard из Git (provisioning), анонимный доступ выключен, пароль — secret |
Что хранит что. Grafana ничего не хранит из сигналов: это интерфейс запросов (PromQL, LogQL, TraceQL) и provisioning. Collector — маршрутизатор/обработчик (не БД). Метрики — Prometheus, логи — Loki, трассы — Tempo. Конфигурации (infra/otel, infra/prometheus, infra/loki, infra/tempo, infra/grafana) и dashboard JSON лежат в Git; провижининг datasources и dashboard автоматический.
Сигналы и соответствие contracts/observability.md
| Сигнал контракта | Реализация (SDK) → имя в Prometheus / место |
|---|---|
| HTTP requests; HTTP duration (s) | http.server.request.duration (histogram, секунды, buckets 5 мс…10 с) → http_server_request_duration_seconds_{bucket,sum,count}{http_request_method, http_route, http_response_status_code}; число запросов = _count (отдельный счётчик не дублируется) |
| Jobs processed/failed; duration | `messenger.jobs.processed{job_type,outcome=ready |
| End-to-end time to ready | messenger.job.time_to_ready (от приёма до ready) → messenger_job_time_to_ready_seconds_* |
| Queue depth / oldest job age | messenger.queue.depth, messenger.queue.oldest_job_age → messenger_queue_depth, messenger_queue_oldest_job_age_seconds (считает API, т. е. метрика живёт и при остановленном worker) |
| DB pool used/waiting | db.client.connections.usage{state}, db.client.connections.waiting → db_client_connections_usage, db_client_connections_waiting |
| Worker busy/capacity | messenger_worker_busy, messenger_worker_capacity |
| CPU/RAM процессов | process_memory_rss_bytes, process_cpu_time_seconds_total (счётчик CPU-времени процесса) |
| Логи API и worker | структурный JSON в stdout и OTLP: ts, level, service.name, msg(event), trace_id, span_id (при активном спане), request_id; resource: service.name (messenger-api/messenger-worker), service.version, service.instance.id, deployment.environment.name=lab |
| Трассы API и worker | server-спан запроса (HTTP POST /api/v1/…), db.connection, s3.put_object/get_object, producer-спан attachment.process publish, consumer-спан attachment.process process — реальные, не статичные |
| Связь upload → publish → consume → S3/DB | W3C traceparent/tracestate: контекст запроса сохраняется в outbox (миграция 0006), relay кладёт его в поля сообщения (jobs.schema.json) и заголовки AMQP; worker продолжает ту же трассу (consumer — потомок producer; producer — потомок server-спана) |
Низкая кардинальность. user_id/chat_id/message_id/attachment_id/request_id/filename не используются как labels метрик (проверяет test_no_high_cardinality_or_secret_labels); маршрут — шаблон /api/v1/chats/{chat_id}/messages. В логах/спанах допустимы технические ID синтетических данных. Секреты не экспортируются: токены, пароли, Authorization, тела сообщений, изображения, SQL-текст, query-строки — не попадают ни в атрибуты, ни в логи; дополнительно Collector удаляет http.request.header.authorization, db.statement, url.query и т. п. (attributes/scrub). Проверка test_secrets_and_message_bodies_are_not_exported: уникальный текст сообщения, токен и пароль не находятся ни в Loki, ни в трассе, ни в метриках.
Health-проверки LB (раз в секунду) не порождают спанов и access-логов (метрики остаются, исключены из SLI фильтром http_route!~"/health.*"); фоновые опросы БД (relay, sweeper) — без корневых спанов (child_span).
Dashboard и SLI/SLO
Dashboard Messenger: API, очередь, worker (infra/grafana/dashboards/messenger.json, генератор build_dashboard.py): RPS по маршрутам и кодам, доля 5xx, p50/p95/p99 (histogram_quantile из sum by (le) гистограмм всех реплик — не среднее p95), задержки по маршрутам, DB pool (занято/простаивает/ожидают), задания по исходам, p50/p95 длительности обработки и времени до ready, глубина очереди, возраст старейшей задачи, saturation worker (busy/capacity), RSS/CPU, очередь и отказы экспорта Collector, логи ошибок (Loki), список алертов, последние трассы. Единицы и запросы описаны в подсказках панелей.
- SLI доступности: доля бизнес-запросов (все маршруты кроме
/health) без ответа 5xx. Числитель — 5xx, знаменатель — все запросы без/health; 4xx (неверный пароль, чужой чат) в отказ сервиса не входят. - SLO: 99.5 % за окно 30 суток (бюджет ошибок 0.5 %); для демонстрации на локальном стенде окна алертов короткие (rate по 1 мин,
for15–20 с). - Дополнительные SLI: p95 задержки (порог 0.5 с), доля 5xx на маршруте загрузки (малообъёмный, но критичный — общий SLI его деградации не заметит), p95 времени до ready.
Alert rules (infra/prometheus/rules/messenger.yml, runbook — docs/runbooks.md)
| Алерт | Условие / окно | Для чего |
|---|---|---|
HighHttpErrorRate |
5xx > 5 % при ≥ 0.5 RPS, for 20s, rate[1m] |
общий отказ сервиса |
HighUploadErrorRate |
5xx на маршруте загрузки > 20 %, for 15s |
отказ S3/очереди |
HighLatencyP95 |
p95 > 0.5 с, for 20s |
медленная БД/обработчик |
QueueLagGrowing |
старейшая задача > 30 с, for 20s |
остановка/перегрузка worker |
WorkerSilent |
absent(messenger_worker_capacity), for 30s |
worker не шлёт метрики |
TelemetryExportFailing |
отказы экспорта Collector > 0, for 15s |
сбой хранилищ телеметрии |
Alerts вычисляет Prometheus; состояние (pending/firing/resolved) видно в Prometheus и на панели «Алерты» dashboard. Внешняя доставка не требуется и не настроена.
Collector: ограничение ресурсов и поведение при backpressure
memory_limiter (limit 280 MiB при лимите контейнера 384 MiB, spike 60 MiB; при приближении данные отклоняются, SDK отбрасывает пакет, приложение продолжает работать), batch (1024/2 с), экспортёры с ограниченной очередью (sending_queue 500) и повторами до 30 с, затем отбрасывание; SDK: очередь спанов/логов 2048, таймаут экспорта 3 с, отказ Tempo/Loki не нарушил работу API в воспроизведённом сценарии ниже. metric_expiration: 20s настроен в exporter. В текущем опыте остановки worker серия capacity оставалась видимой, поэтому диагноз основан на росте возраста очереди и нулевой скорости ready, а не на WorkerSilent.
Перенос предыдущей работы и воспроизводимость
Перенесён собственный мессенджер из ЛР5: PostgreSQL — пользователи, чаты, сообщения, сессии, идемпотентность, metadata/outbox; Valkey — вспомогательный кэш; приватный SeaweedFS S3 — оригиналы и варианты; RabbitMQ — durable очередь; worker — асинхронная обработка изображений; HAProxy и две API-реплики. Загрузка по-прежнему возвращает 202, текстовое сообщение без вложений допустимо. Бизнес-контракт ЛР6 не меняется.
| Компонент | CPU / RAM | Постоянные данные / готовность |
|---|---|---|
| API ×2 | каждому 1 CPU / 256 MiB | stateless; HTTP /health/ready |
| worker | 1 CPU / 768 MiB | состояние в БД/S3/broker; heartbeat |
| PostgreSQL 17.11 | 1 CPU / 512 MiB | pgdata; pg_isready, миграции отдельным одноразовым сервисом |
| Valkey 8.1.10 | 0.5 CPU / 128 MiB | valkeydata; ping |
| SeaweedFS 4.48 | 1 CPU / 768 MiB | seaweeddata; bootstrap создаёт приватный bucket и проверяет ограниченные права API |
| RabbitMQ 4.1 (digest) | 1 CPU / 512 MiB | rabbitmqdata; diagnostics ping |
| HAProxy 3.0 (digest) | 1 CPU / 128 MiB | HTTP health; опубликован только 127.0.0.1:8080 |
| Collector / Prometheus / Loki / Tempo / Grafana | каждому 1 CPU; 384 / 512 / 512 / 1024 / 512 MiB | volumes и назначение выше; реальную доступность сигналов проверяют собственные тесты |
Секреты и .env создаются локально, в Git не входят. init-secrets.sh идемпотентен; .gitattributes сохраняет LF у shell-скриптов при Windows clone. Внешние зависимости не нужно поднимать отдельно. Workflow .github/workflows/application.yml собирает приложение и запускает публичный сценарий; его наличие не означает успешного запуска CI на сервере Gitea.
Выделенные исправления базы ЛР5: HAProxy не повторяет потенциально выполненный upload и сохраняет JSON-ответ приложения при отказе БД; reconciler защищает варианты, staging и незавершённые операции от удаления. Добавлены уже использованные в ЛР5 проверки TTL, зависимостей и reconciler; исправлено имя S3-сервиса в сценарии отказа. Версии и архитектура телеметрии сохранены.
Доказательства критериев (12.11.2026)
| Проверка | Наблюдаемый результат | Доказательство |
|---|---|---|
| Контракт, полная OpenAPI-валидация и public smoke при включённой телеметрии | PASS | вывод |
| Собственные проверки | 66 уникальных тестов OK: 12 API, 9 idempotency, 11 attachments, 6 topology, 9 pipeline, 5 observability, 1 retry trace, 2 reconcile, 7 resilience, 2 expiry, 2 dependencies | команды, вывод |
| Реальные metrics/logs/traces, trace/span IDs, отсутствие секретов и высококардинальных labels | 5 observability-тестов OK; после исследования повторены | вывод |
| Upload → producer → consumer → S3/DB; повторные попытки | 3 consumer-спана и 2 reschedule в одной трассе, parent-child проверен | вывод |
| Перезапуск всего стенда | 13 контейнеров перезапущены, volumes сохранены, сессии и подтверждённые данные доступны | lifecycle, повторная проверка |
| Отказ API-реплик по очереди | обе разные реплики остановлены; 120 и 119 успешных записей, 0 неуспешных попыток | failover, вывод |
| S3 bootstrap ×2 | повторный запуск успешен, anonymous 403, создание чужого bucket запрещено | вывод |
| Grafana provisioning | 3 источника, dashboard messenger-overview, 22 панели, provisioned=true |
ответ API |
Чистый clone 6d87f54 |
новые секреты и пустые volumes, build/up, public smoke и provisioning успешны; отдельный проект, порты 18080/13000 | вывод, override портов |
| Инциденты, alerts firing → resolved | все 4 воспроизведены | JSON, разбор ниже |
| Трек 1 | 4 профиля × 2 повтора | исходные замеры, ресурсы |
На Windows установлен Borland make, поэтому выполнены точные Python-команды целей make check, make validate, make test из Makefile, а не GNU make. Публичные tests/, contracts/, README, COURSE и CONTRIBUTING совпадают с исходным skeleton 470d9d6.
Первый persistence-запуск завершился таймаутом recovery hook после успешных 66 тестов. Полный обход S3 не успевал за 45 с на накопленных ~58 тыс. вложений даже при исправном backend. Hook теперь читает первый байт до 16 последних готовых оригиналов; это ограниченная проверка готовности, а не аудит всех исторических объектов. После исправления публичная проверка сохранности и оба failover пройдены. Исходный неуспешный вывод сохранён, повторный — отдельно в recovery_checks.txt.
Контролируемые инциденты
Нагрузка: 4 цикла отправки сообщений с паузой 0.1 с и 10 циклов загрузки PNG с паузой 0.3 с. Реальная интенсивность зависит от задержки/отказа. research/incidents.py записывает метрики каждые ~3 с и локальные состояния Prometheus. Времена включают окно rate[1m] и for правила.
| Воздействие | Алерт | До firing, с | От команды восстановления до resolved, с |
|---|---|---|---|
| Остановлен worker | QueueLagGrowing |
68.3 | 21.8 |
| DB: pg_sleep(0.8) | HighLatencyP95 |
67.7 | 43.5 |
| Остановлен S3 | HighUploadErrorRate |
84.1 | 39.3 |
| Остановлены Tempo и Loki | TelemetryExportFailing |
69.1 | 67.5 |
Диагностика по сохранённым наблюдениям (строки diagnosis в JSON — шаблоны скрипта; ниже учтены фактические поля, в том числе присутствующая capacity и нулевое ожидание DB pool):
- Worker. Возраст старейшего задания 60.7 с, скорость завершения ready 0.0/с; серия capacity присутствует:
True. Сочетание роста возраста и отсутствия обработки указывает на worker. После восстановления алерт снят. - Медленная БД. p95 = 782.8 мс; ожидающих в DB pool: 0.0. Поиск обнаружил 20 трасс с
db.connection >300msи 20 медленных HTTP POST сообщений (лимит поиска 20). Задержка видна в спане БД; рост ожидания пула не требуется для этого диагноза. - S3. 5xx на upload = 100.0 %, общая доля = 1.1 %. Найдены 20 ошибочных трасс и 37 строк
s3_put_failed. Локализация по маршруту, операциям S3 и логам отделяет этот отказ от общего отказа API. - Tempo/Loki. API: 62.6 RPS, 5xx = 0.0 %; очередь Collector = 32.0, send-failed spans ≈62.9/с, RSS = 239.0 MiB при лимите 384 MiB. Продолжающиеся бизнес-запросы и ошибки экспортёра показывают отказ пути телеметрии. Prometheus в этом сценарии доступен. Счётчик неуспешных экспортов включает повторы и не равен числу окончательно потерянных уникальных спанов; точное число потерянных логов/трасс этим опытом не установлено.
Трек 1: цена наблюдаемости
Гипотеза: инструментирование добавляет CPU/RAM; head 10 % уменьшает ingest, но теряет большинство редких проблемных трасс. Tail policy сохраняет ошибки и задержки >500 мс, отправляя в Tempo лишь 10 % остальных трасс.
Методика: 8 процессов-клиентов, 64 одновременных запроса; общие 40 синтетических пользователей и 40 чатов на всю серию, 90 % POST сообщений и 10 % GET. Каждый профиль: прогрев 5 с, замер 30 с, 25 с дозаписи, 2 повтора; перед профилем пересозданы API/worker/Collector. Во всех профилях одинаковая инъекция: 2 % запросов → 500, 2 % → +0.6 с. RPS, ошибки и latency в таблице относятся к POST-сообщениям; успешные RPS исключают внедрённые ошибки. Для off отключены сигналы API/worker, но контейнеры хранилищ остаются запущены.
Машина: i9-12900KS (16 ядер / 24 потока), 95.8 ГиБ RAM, Windows/Docker Desktop (WSL2); Docker доступны 24 CPU и 46.9 ГиБ RAM. Клиент Python 3.11.9, приложение Python 3.12.12. Лимиты контейнеров одинаковы во всех профилях (таблица выше); другой Docker-проект оставался в фоне. Накопленные данные не очищались. Размеры БД после серии: {'users': 739, 'chats': 425, 'messages': 1610549, 'attachments': 68898}; отдельный счётчик сообщений до серии не снимался. Размер набора, хэши исходников и среда.
Среднее двух прогонов; RAM — максимальный пик из двух. CPU API — на одну реплику, 100 % соответствует одному ядру.
| Профиль | Успешные RPS (min–max) | Ошибки, % | p50 / p95 / p99, мс | CPU API, % | RAM API, MiB | CPU / RAM Collector |
|---|---|---|---|---|---|---|
| Без телеметрии | 1368 (1348–1388) | 2.05 | 16.7 / 73.0 / 618.1 | 50.2 | 76.4 | 0.1 % / 45.1 MiB |
| Head 100 % | 1245 (1239–1251) | 2.01 | 24.6 / 100.3 / 629.7 | 79.5 | 83.2 | 3.3 % / 75.0 MiB |
| Head 10 % | 1220 (1137–1303) | 1.98 | 23.9 / 101.5 / 626.8 | 68.5 | 83.7 | 1.9 % / 68.9 MiB |
| SDK 100 % + tail | 1291 (1282–1300) | 2.07 | 23.5 / 90.2 / 628.6 | 77.4 | 75.5 | 4.0 % / 108.4 MiB |
Объём — среднее за измерительное окно с дозаписью; logs и metric points считаются отдельно от spans.
| Профиль | Принято spans | Отправлено spans | Logs | Metric points | Найдено error / внедрено 500 | Найдено slow / медленных у клиента |
|---|---|---|---|---|---|---|
| Без телеметрии | 0 | 0 | 0 | 0 | 0 / 873 | 0 / 856 |
| Head 100 % | 89886 | 89886 | 44324 | 396 | 864 / 780 | 876 / 772 |
| Head 10 % | 8898 | 8982 | 43176 | 396 | 85 / 750 | 86 / 736 |
| SDK 100 % + tail | 91882 | 13138 | 45226 | 396 | 916 / 828 | 858 / 768 |
Результат. Средний CPU API: off 50.2 %, on100 79.5 %, head10 68.5 %, tail 77.4 %. Изменение on100 относительно off: 29.3 п. п. Head sampling сокращает число спанов, но логи и метрики остаются; поэтому снижение CPU не обязано быть пропорционально sampling rate. При tail SDK продолжает формировать 100 % спанов, а Collector отбирает их перед Tempo: отправлено на 85.7 % меньше, чем принято. Это экономия ingest спанов, не прямое измерение дискового объёма.
Потери и выбор конфигурации. Head 10 % сохраняет около 11.3 % ошибочных и 11.8 % медленных трасс по приближённому сопоставлению окон. Tail сохраняет значительно больше проблемных трасс при меньшем ingest, поэтому выбран как проверенная сбалансированная конфигурация: SDK 100 %, collector-tail.yaml, все ERROR, все >500 мс, 10 % остальных. Цена — CPU SDK и память Collector для ожидания решения. Для демонстрации/тестов по умолчанию восстановлен on100 без инъекции отказов.
Сумма receiver_refused_spans / exporter_send_failed_spans по двум повторам: off 0/0, on100 0/0, head10 0/0, tail 0/0. Tempo discarded_spans_total до/после серии: null / null. null означает отсутствие ряда, а не измеренный ноль. Эти счётчики описывают наблюдавшиеся отказы приёма/экспорта; сами по себе не доказывают отсутствие любых потерь на SDK.
На графике RPS усреднены по двум прогонам, CPU/ingest/отношения взяты из второго; отношения визуально ограничены 100 %. В таблицах выше приведены средние и исходные количества, подробные результаты каждого повтора — в JSON.
Ограничения методики: два коротких повтора на одном ПК с фоновыми задачами, без доверительных интервалов; различия RPS могут быть обычным разбросом. Данные накапливаются, профили идут в фиксированном порядке. Tempo-поиск включает 5 с прогрева, поэтому числитель иногда больше знаменателя: это приближённое сопоставление, не точная вероятность сохранения или доказательство 100 % сохранности. Поиск ограничен 5000 трассами (для всех HTTP лимит достижим); точное число потерянных уникальных спанов SDK не измерено. Размер volumes не используется для вывода: compaction и flush искажают короткие замеры.
Ограничения решения
- Один Docker-host; БД, LB, broker, worker и каждое хранилище телеметрии — по одному экземпляру. Отказ host/volume не покрывается.
- Проверена остановка Tempo/Loki; отдельная остановка Collector/Prometheus в текущем исследовании не выполнялась. Ограниченные очереди допускают потери телеметрии при длительном простое.
- Recovery hook проверяет недавние готовые оригиналы; публичная persistence-проверка отдельно проверяет созданные ею данные. Это не проверка каждого исторического объекта S3.
- SLO 99.5 % за 30 суток задан как цель; короткие эксперименты не доказывают выполнение месячного SLO. Алерты локальные, без внешней доставки.
- Исторические
evidence/incidents.json,evidence/obs_cost.jsonи графики от октября оставлены как архив; все выводы текущей сдачи опираются наevidence/recheck_2026-11-12/.

