forked from mtusi2026/mtusi2026lab6
73 lines
11 KiB
Markdown
73 lines
11 KiB
Markdown
# Отчёт — лабораторная 6
|
||
|
||
- Автор, группа: Ромашко Владимир, БВТ2301.
|
||
- Целевая оценка: **4**.
|
||
- Источники: [контракт](contracts/observability.md), [OpenTelemetry](https://opentelemetry.io/docs/collector/configuration/), [Loki OTLP](https://grafana.com/docs/loki/latest/send-data/otel/). Библиотеки: FastAPI, SQLAlchemy, Redis, boto3, Pillow, OpenTelemetry SDK, psutil. Codex использовался для реализации, проверок и оформления.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker с Compose и Python 3.9+ на хосте; свободные порты 8080, 3000, 9090, 3100, 3200. В контейнерах Python 3.12.8; PostgreSQL 17.4, Redis 7.4.2, Nginx 1.28.0; MinIO закреплён digest. Телеметрия: SDK 1.38.0 / semantic conventions 0.59b0, Collector 0.136.0, Prometheus 3.6.0, Loki 3.5.7, Tempo 2.9.0, Grafana 12.2.0.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
# Задать свои POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD,
|
||
# S3_SECRET_ACCESS_KEY и GRAFANA_ADMIN_PASSWORD.
|
||
docker compose config --quiet
|
||
docker compose up -d --build
|
||
curl http://127.0.0.1:8080/health/ready # дождаться 200 {"status":"ok"}
|
||
python -X utf8 scripts/check_contract.py
|
||
python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080
|
||
python -X utf8 student-tests/observability.py --scenario all
|
||
python -X utf8 tests/load.py --base-url http://127.0.0.1:8080 --duration 30 --concurrency 4 --output evidence/load.json
|
||
docker compose down # безопасная остановка, volumes остаются
|
||
```
|
||
|
||
Миграции (включая 008 с trace context) и создание S3 bucket выполняются автоматически. Grafana: http://localhost:3000, `admin`, пароль из `.env`; dashboard **Lab 6 / Messenger / Lab 6** импортируется автоматически. Python-команды check/smoke эквивалентны `make check` / `make test`; на проверявшемся Windows-хосте make отсутствует. Для **намеренного удаления всех учебных данных**: `docker compose down -v` (при проверках не выполнялось).
|
||
|
||
## Архитектура и решения
|
||
|
||
Из lab5 сохранены Nginx → две API-реплики, PostgreSQL, Redis для сессий/кеша, S3, durable Redis Streams, outbox/dispatcher и worker. PostgreSQL — источник истины для заданий; attachment и outbox фиксируются одной транзакцией после записи staging, ack выполняется после устойчивого результата.
|
||
|
||
Добавлены API/worker/dispatcher → OTLP → Collector → Prometheus (метрики), Loki (логи), Tempo (трассы) → Grafana. История хранится в volumes, retention 72 часа. W3C context сохраняется в outbox и переносится через broker в worker и image process; retry остаётся в той же трассе. Экспортируются шаблоны маршрутов и технические поля, без SQL-параметров, токенов и содержимого сообщений.
|
||
|
||
Метрики: `http_requests_total` и `jobs_processed_total` — счётчики; `http_duration_seconds`, `job_duration_seconds`, `attachment_time_to_ready_seconds` — histogram в секундах; `queue_depth`, `db_pool_used/waiting`, `worker_busy/capacity` — количества; `queue_oldest_age_seconds` — секунды; `container_memory_bytes` / `container_cpu_seconds_total` — память/CPU. Точные имена, labels и запросы: [описание сигналов](infra/otel/README.md#сигналы), [dashboard JSON](infra/grafana/dashboards/messenger.json).
|
||
|
||
Переменные `.env.example` подставляются в Compose: пароли — соответствующим сервисам, `MAX_*`, `JOB_*`, `WORKER_CONCURRENCY` — приложению, `APP_PORT` — Nginx. `OTEL_SDK_DISABLED=false` включает телеметрию; service.name и внутренние адреса заданы отдельно по ролям.
|
||
|
||
SLI = 1 − 5xx / все запросы без health за **30 минут**, SLO ≥ **99%**. `ApiHighErrorRate`: >5% ошибок за 2m, минимум 20 запросов, `for: 20s`. `QueueLagHigh`: возраст queued >30s при свежем sample, `for: 15s`. Правила и [инструкции диагностики](infra/otel/README.md#queue-lag) сохранены в репозитории.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Структура и публичный smoke | Команды check/smoke выше | PASS при включённой телеметрии | [verification.txt](evidence/verification.txt) |
|
||
| Минимум lab5 и общий стенд | `docker compose up -d --build`; smoke | API, upload 202, ready, оригинал и thumbnail работают; хранилища имеют volumes | [compose.yaml](compose.yaml), verification.txt |
|
||
| OTLP: метрики, логи, трассы API/worker | `observability.py --scenario smoke` | Все обязательные метрики найдены; связанные логи трёх сервисов | [observability.json: smoke](evidence/observability.json) |
|
||
| Импортируемый dashboard и безопасные атрибуты | Provisioning; сценарий smoke | 18 панелей, 3 datasource; проверены labels и отсутствие приватных входных данных | [provisioning](infra/grafana/provisioning), observability.json |
|
||
| Корреляция HTTP/job → log/trace | Сценарий smoke | Найдены request_id, trace_id и parent-связи до S3/DB | observability.json: smoke |
|
||
| W3C propagation, включая retry | `observability.py --scenario retry` | Попытки 1 и 2 в одной трассе, tracestate сохранён | observability.json: retry |
|
||
| p50/p95/p99, очередь, DB pool, worker, CPU/RAM, time-to-ready | Сценарий smoke; dashboard | Метрики существуют; percentile вычисляется по сумме histogram buckets | dashboard JSON, observability.json |
|
||
| SLI/SLO и два проверенных алерта | `--scenario queue`, `--scenario database` | Оба алерта firing → resolved после восстановления | [alerts.yaml](infra/otel/alerts.yaml), observability.json |
|
||
| Ограниченная буферизация и отказ telemetry backend | `--scenario backend` | API продолжает работу; очередь ≤32 batches, RSS ≤199.03 MiB | [collector.yaml](infra/otel/collector.yaml), observability.json |
|
||
|
||
Здесь `observability.py` — `python -X utf8 student-tests/observability.py`. Сценарии останавливают реальные контейнеры текущего Compose-проекта и восстанавливают их в `finally`; volumes не удаляют.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Проверки 16.11.2026. Гипотеза: телеметрия показывает причину отказа, а её backend не блокирует бизнес-операции. Docker Desktop: 8 CPU, 7.76 GiB RAM; лимиты API — по 1 CPU/512 MiB, worker — 2 CPU/2 GiB, Collector — 0.5 CPU/256 MiB.
|
||
|
||
Нагрузка: один прогон closed-loop POST сообщений, 4 клиента, 30 секунд, без отдельного прогрева и автоматических retry. **2389 успешных запросов, 0 ошибок, 79.219 RPS; p50/p95/p99 = 40.784/99.520/129.314 ms**. Исходная сводка: [load.json](evidence/load.json). Это локальная проверка, не исследование предельной производительности; CPU во время прогона отдельно не фиксировался, RSS Collector измерен в сценарии отказа ниже.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановить worker | Рост возраста очереди и QueueLagHigh | Depth=1, возраст 55s; producer есть, consumer появляется после запуска; затем ready, depth=0 | firing → resolved: 20.3s; принятое вложение сохранено |
|
||
| Остановить PostgreSQL | 503 и ApiHighErrorRate | Error ratio 42.6%; в trace `db.acquire`/`OperationalError` и связанный лог — отказ БД, а не медленный handler | После запуска запросы успешны; firing → resolved: 109.1s с учётом окна 2m |
|
||
| Временно остановить S3 | Retry без потери задания | Первая попытка failed, вторая ready, общий trace | Задание успешно завершено |
|
||
| Остановить Tempo на 60s | Приложение работает, буферы ограничены | 165 записей и обработка вложения успешны; очередь ≤32, RSS 198.52–199.02 MiB; после запуска новая трасса найдена | Потеря 808 принятых Collector spans, бизнес-операции успешны |
|
||
|
||
Порядок диагностики: dashboard → лог по request_id/trace_id → ошибочный или отсутствующий span зависимости → восстановление сервиса → проверка ready/успешных запросов и resolved. Для Tempo потеря рассчитана как Δaccepted − Δsent после опустошения очереди; повторы отправки не считаются отдельными потерянными spans. Подробные timestamps и ID — в [observability.json](evidence/observability.json).
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Один локальный узел, без HA и TLS; алерты только локальные. SDK ограничивает очереди 512 записями, Collector использует memory limiter/batch и retry до 15s: длительный отказ может терять телеметрию. Потери до приёма Collector указанной дельтой не измеряются. История удаляется по retention; метрики не заменяют журнал транзакций. При недоступной БД API возвращает 503, после восстановления работает снова. Треки оценки 5 не реализовывались.
|