forked from mtusi2026/mtusi2026lab6
146 lines
11 KiB
Markdown
146 lines
11 KiB
Markdown
# Отчёт — лабораторная 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 локально не нужен.
|
||
|
||
```sh
|
||
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](https://opentelemetry.io/docs/languages/go/exporters/),
|
||
[Loki native OTLP](https://grafana.com/docs/loki/latest/send-data/otel/),
|
||
[Collector configuration](https://opentelemetry.io/docs/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`).
|