Files
mtusi2026lab6/REPORT.md
T

11 KiB
Raw Blame History

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

  • Целевая оценка: 3.
  • Автор/группа: Нурлыгаянова Екатерина, БПИ2302.
  • Commit/PR: публикация не выполнялась.
  • Основа: собственная реализация из ../mtusi2026lab5 (исходники Go API, Python worker, миграции, инфраструктура). Контракт и публичные tests взяты из lab6 без изменений.
  • Помощь ИИ: Codex — перенос, SDK-инструментация, конфигурации, dashboard, проверки и отчёт. Использованы библиотеки из app/go.mod и worker/requirements.txt.

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

Нужны Docker Engine с Compose v2, Python 3.9+, make. Go локально не нужен.

cp .env.example .env
sh scripts/init-secrets.sh
docker compose config --quiet
docker compose up -d --build --wait
make check
make test
python3 student-tests/observability.py
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
python3 student-tests/incidents.py

Внешние точки: API http://localhost:18086, Grafana http://localhost:3000, Prometheus http://localhost:19091, Loki http://localhost:3100, Tempo http://localhost:3200. Все опубликованные порты привязаны к loopback. В Grafana разрешён локальный anonymous Viewer. Dashboard уже находится в Dashboards → Lab6 → Messenger — Lab 6.

Подготовка: init-secrets.sh генерирует новые локальные ключи и пароли (вне Git). Compose запускает PostgreSQL, применяет все миграции через goose 3.26.0, готовит приватный S3 bucket, затем запускает две API-реплики, dispatcher и worker. Не переносить .env, secrets и volumes из пятой: lab6 использует свой проект mtusi-lab6. Имена переменных .env.example используются непосредственно API/worker либо Compose; SESSION_STORE=valkey, HISTORY_CACHE=off. Worker принудительно задаёт свой service.name в SDK. OTLP endpoint используется обоими приложениями; протокол HTTP/protobuf закреплён экспортёрами.

Остановка с сохранением истории: docker compose down. Повторный запуск: docker compose up -d --wait. Намеренное удаление всех учебных данных: docker compose down -v. Пароли в secrets нельзя менять при сохранённом PostgreSQL volume.

Архитектура

HAProxy → две Go API → PostgreSQL (источник истины), Valkey (сессии), SeaweedFS S3 (байты). API сохраняет attachment и durable job intent в одной транзакции PostgreSQL. Dispatcher публикует intent в Valkey Streams; worker читает job, делает thumbnail, пишет результат в S3 и БД, затем подтверждает доставку. Повторная доставка защищена advisory lock и терминальным состоянием. Сохранены идемпотентность сообщений и доступ участников чата.

API и worker → OTLP HTTP → Collector → Prometheus / Loki / Tempo → Grafana. Prometheus хранит метрики, Loki — структурные логи, Tempo — трассы. Collector принимает, ограничивает память и группирует данные; Grafana визуализирует их. Каждый backend и Grafana имеют отдельный persistent volume; retention сигналов 72 часа. Grafana provisioning, JSON dashboard и backend configs включены в Git.

Версии: Go 1.26.10, Python 3.13.9, Go OTel SDK 1.38.0 (logs 0.14.0), Python OTel 1.38.0, Collector contrib 0.137.0, Prometheus 3.5.0, Loki 3.5.5, Tempo 2.8.2, Grafana 12.2.0, PostgreSQL 17.6, Valkey 8.1.3, SeaweedFS 4.00, HAProxy 3.2.9. Образы закреплены в Dockerfile/compose.yaml; списки прямых зависимостей закреплены.

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

Полное соответствие имён и единиц — infra/otel/README.md.

Контракт Реализация
HTTP counter api_requests_total{method,route,status_class}
HTTP histogram api_duration_seconds_bucket
Job counter worker_jobs_total{job_type,outcome}
Job histogram worker_duration_seconds_bucket
Resource service.name, service.version, service.instance.id, deployment.environment.name=lab
Structured logs OTLP timestamp/severity/resource, event, trace_id/span_id; API добавляет request_id
Traces API SERVER span вокруг настоящего handler; worker CONSUMER span вокруг настоящей доставки

API возвращает X-Trace-Id и X-Request-Id. В Loki: {service_name="messenger-api"} | trace_id="ID". В Tempo вставить этот trace ID. Для worker: {service_name="messenger-worker"} | event="job.success", затем открыть его trace_id в Tempo. Контекст API → broker → worker передаётся в реализации; для оценки 3 достаточно реальных API и worker traces и связанных логов.

Dashboard показывает RPS, error ratio (5xx / все бизнес-запросы, без health), API p95, job counters по outcome, worker p95, логи и поиск traces. Процентили: histogram_quantile(0.95, sum by (le) (rate(..._bucket[1m]))). Latency — секунды, RPS/jobs rate — 1/с, ошибки — доля 0..1. Health исключён из API панелей. Job counter считает попытки доставки; retry/error — ошибки попытки, failed — терминальная ошибка, skipped — повторная/занятая доставка. Это не число уникальных файлов.

Labels метрик используют шаблоны маршрутов, а не UUID/raw URL; бизнес-идентификаторы и request_id не labels. OTLP события экспортируются по явному списку технических полей. Тела сообщений, картинки, HTTP headers, пароли, session tokens, signed URLs и exception messages не экспортируются. Sampling — все spans, очереди SDK ограничены 1024 записями; Collector ограничен 192 MiB и контейнером 256 MiB, очереди экспортёров — 256 batches, retry не дольше 30 с. Долгий отказ backend может привести к потере telemetry; это не durable event journal.

Доказательства

Результаты проверок и наблюдений сохранены в evidence/.

Проверка Результат Доказательство
make check PASS evidence/check.txt
make test с включённой телеметрией PASS evidence/smoke.txt
Go go test ./... в контейнере PASS evidence/go-tests.txt
API trace + связанный лог, worker trace + лог, четыре SDK-метрики PASS evidence/observability.txt, evidence/telemetry.json
Grafana provisioning Dashboard загружен, 8 панелей evidence/grafana.json
Остановка worker queued сохраняется, после запуска ready; 5,931 с evidence/incidents.json
Отказ S3 В trace ошибка s3.get_object / ConnectionClosedError, job retry; контрольный upload после восстановления ready; 32,063 с evidence/incidents.json
Перезапуск API и хранилищ Сообщения, файл и прежняя сессия сохранены evidence/persistence.txt, evidence/persistence-containers.txt

Нагрузка: closed-loop POST messages, 30 секунд, concurrency=4, 44 206 успешных запросов, 0 ошибок, 1473,386 RPS; p50=2,508 мс, p95=3,885 мс, p99=6,048 мс. Исходный замер: evidence/load.json. Это учебный замер, не предел производительности; перцентили относятся к успешным запросам, учитывают расходы клиента. Docker Desktop: 12 vCPU, 8 216 776 704 байт RAM; ресурсы разделяются с другими сервисами. Лимиты: API 1 CPU / 1 GiB на реплику, worker 1 CPU / 1 GiB, PostgreSQL 2 CPU / 1 GiB, Collector 0,5 CPU / 256 MiB; остальные — в Compose.

Диагностика первого отказа: API продолжает принимать upload (202), статус остаётся queued, обработка возобновляется после старта worker. Диагностика второго: worker consumer span имеет outcome=retry, дочерний S3 client span содержит error.type=ConnectionClosedError; это указывает на зависимость S3. Тела данных и credentials в сохранённых наблюдениях отсутствуют.

Ограничения

Один Docker-host, одна БД, один broker/S3/LB — единственные точки отказа. Уровни 4 и 5 не заявлены: SLO/alerts и исследовательского трека нет. Telemetry хранится локально, не предназначена для публичного доступа. Внешняя публикация, commit и PR не выполнялись. На защите нужно уметь объяснить конфиги и повторить запрос/задание с поиском соответствующих лога и трассы.

Источники: OTel Go exporters, Loki native OTLP, Collector configuration.

Дополнительные короткие проверки крайних случаев

python3 student-tests/corners.py — PASS, 24 сценария на запущенном стенде. Проверены неверные limit/cursor/UUID/JSON/Bearer, границы текста 4000/4001, повреждённое изображение, MIME, filename с обходом пути, upload >10 MiB, изоляция чужих вложений, дубли attachment IDs, cursor другого чата, неизвестный variant и восемь одновременных повторов одного Idempotency-Key через обе API-реплики. Подтверждено: повторы возвращают один message ID; другой body даёт 409. Вывод: evidence/corners.txt. Повторный публичный smoke также PASS (evidence/smoke.txt).