Files
mtusi2026lab6-fork/REPORT.md
T
2026-11-17 17:18:53 +03:00

186 lines
12 KiB
Markdown

# Отчёт — лабораторная 6
- Автор, группа: Гадяцкий Л. Е., БПИ2302
- Целевая оценка: 3
- Commit/PR: solution/BPI2302-Gadiatskiy MR#40: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab6/pulls/40
- Использованные источники и библиотеки:
- контракт и семантика: `contracts/openapi.json`, `contracts/README.md`, `contracts/observability.md`, `contracts/attachment-states.md`, `README.md`, `COURSE.md`
- перенос из lab5: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, Nginx LB, идемпотентность, MinIO/S3, RabbitMQ, worker/thumbnails
- runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0, boto3 1.35.76, Pillow 11.0.0, pika 1.3.2
- OpenTelemetry: `opentelemetry-api/sdk/exporter-otlp-proto-http` 1.29.0, `opentelemetry-instrumentation-fastapi` 0.50b0
- PostgreSQL: `postgres:16-alpine`; LB: `nginx:1.27-alpine`; S3/MinIO: `alpine/minio:RELEASE.2025-10-15T17-29-55Z`; broker: `rabbitmq:3.13.7-alpine`
- telemetry: `otel/opentelemetry-collector-contrib:0.114.0`, `prom/prometheus:v2.54.1`, `grafana/loki:3.2.1`, `grafana/tempo:2.6.1`, `grafana/grafana:11.3.1`
- Помощь ИИ использована при переносе lab5, частично при настройке OTel/Collector/Grafana и при заполнении отчёта. Результаты подтверждаются сохранёнными запусками.
## Запуск из чистого clone
**Prerequisites:** Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (`make check` / `make test` / `tests/resilience.py`). Runtime приложения — внутри образа.
**Версии:**
- API/worker: базовый образ `python:3.12.8-slim-bookworm` → локальный `mtusi-messenger:lab6`
- PostgreSQL: `postgres:16-alpine`
- Nginx: `nginx:1.27-alpine`
- MinIO: `alpine/minio:RELEASE.2025-10-15T17-29-55Z`
- RabbitMQ: `rabbitmq:3.13.7-alpine`
- OTel Collector: `otel/opentelemetry-collector-contrib:0.114.0`
- Prometheus: `prom/prometheus:v2.54.1`
- Loki: `grafana/loki:3.2.1`
- Tempo: `grafana/tempo:2.6.1`
- Grafana: `grafana/grafana:11.3.1`
- зависимости: `requirements.txt`
**Конфигурация:** секретов в Git нет. Локальный `.env` создаётся из примера и не коммитится:
```sh
cp .env.example .env
```
Соответствие `.env.example`:
- `APP_HOST` / `APP_PORT` — bind uvicorn внутри контейнеров API
- `HOST_PORT` — порт LB на host (по умолчанию 8080; если занят — например 8086)
- `GRAFANA_PORT` — порт Grafana на host (по умолчанию 3000)
- `APP_ENV` — среда запуска (`lab`)
- `SESSION_TTL_SECONDS` — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)
- `SESSION_STORE=postgres` — сессии в PostgreSQL (общие для всех реплик)
- `DATABASE_URL` — строка подключения API/migrate/worker к PostgreSQL в compose-сети
(приложение также поддерживает `DATABASE_URL_FILE`)
- `IDEMPOTENCY_TTL_SECONDS` — срок хранения идемпотентных записей (по умолчанию 86400)
- `API_REPLICAS=2` — в `compose.yaml` зафиксированы сервисы `api1` и `api2`
- `S3_ENDPOINT` / `S3_REGION` / `S3_BUCKET` — доступ API/worker к MinIO в compose-сети
- `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` — учебные credentials MinIO (также `*_FILE`)
- `MAX_UPLOAD_BYTES=10485760`, `MAX_IMAGE_PIXELS=40000000` — лимиты загрузки/декодирования
- `BROKER_URL` — AMQP URL RabbitMQ (также `BROKER_URL_FILE`)
- `WORKER_CONCURRENCY` — prefetch consumer worker (по умолчанию 2)
- `JOB_MAX_ATTEMPTS=5` — лимит управляемых попыток обработки
- `JOB_TIMEOUT_SECONDS`, `STAGING_RETENTION_SECONDS` — параметры эксплуатации
- `OTEL_SERVICE_NAME` / `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_PROTOCOL` — экспорт OTLP в Collector; worker в compose задаёт `messenger-worker`
Учебные credentials compose (`messenger` / `messenger`, MinIO `minioadmin` / `minioadmin`, RabbitMQ `messenger` / `messenger`, Grafana `admin` / `admin`) только для локального синтетического стенда.
**Сборка и запуск:**
```sh
docker compose --env-file .env up -d --build
```
Миграции `migrations/*.sql` применяет one-shot сервис `migrate` до старта `api1`/`api2`/`worker`. Приватный bucket `S3_BUCKET` идемпотентно создают API и worker при старте. Grafana подхватывает datasources/dashboard из `infra/grafana/provisioning` без ручного импорта.
Готовность через LB (подставьте свой `HOST_PORT`):
```sh
curl -i http://127.0.0.1:8080/health/ready
```
Ожидается HTTP 200, тело `{"status":"ok"}`, заголовки `X-Request-Id` и `X-Instance-Id` (`api1` или `api2`). `/health/ready` требует доступности PostgreSQL, S3 (MinIO) и RabbitMQ.
Grafana: `http://127.0.0.1:3000` (dashboard **Messenger lab6 observability**, folder Messenger).
**Публичный smoke** (при уже запущенном стенде и включённой телеметрии):
```sh
python tests/smoke.py --base-url http://127.0.0.1:8080
# или: make test BASE_URL=http://127.0.0.1:8080
```
На Windows для публичных тестов задайте `PYTHONUTF8=1`.
**Проверка сохранности:**
```sh
# Unix:
chmod +x scripts/restart.sh
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
# Windows:
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
```
Hook выполняет `docker compose --env-file .env restart` для `postgres`, `s3`, `broker`, `api1`, `api2`, `worker`, `lb`, `otel-collector`, `prometheus`, `loki`, `tempo`, `grafana` **без** удаления volumes.
**Проверка отказа одной API-реплики:**
```sh
# Windows:
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080
```
**Остановка:**
```sh
docker compose --env-file .env down
```
Намеренное удаление учебных данных (volumes):
```sh
docker compose --env-file .env down -v
```
## Архитектура и решения
```
HTTP-клиент
→ lb (Nginx)
→ api1 / api2 (uvicorn + FastAPI + OTel SDK)
→ PostgreSQL / MinIO / RabbitMQ
→ OTLP HTTP → otel-collector
→ worker (OTel SDK)
→ OTLP HTTP → otel-collector
├─ metrics → Prometheus (:8889 scrape)
├─ logs → Loki (/otlp)
└─ traces → Tempo (OTLP)
→ Grafana (provisioned datasources + dashboard)
```
Назначение хранилищ сигналов:
- **Prometheus** — числовые метрики API/worker (RPS, ошибки, latency, jobs).
- **Loki** — структурные логи API/worker с корреляцией по trace context.
- **Tempo** — трассы HTTP (API) и consumer-span worker.
- **Collector** — единая точка приёма OTLP, batch/memory limiter, раздача по backend.
- **Grafana** — UI и импортируемый dashboard, не долговременное хранилище сигналов.
Соответствие сигналов `contracts/observability.md` (уровень 3):
| Сигнал | Имя в Prometheus / замечание |
| --- | --- |
| HTTP requests | `messenger_http_requests_total{http_request_method,http_route,http_response_status_class}` |
| HTTP duration | `messenger_http_request_duration_seconds_*` (histogram, секунды) |
| Jobs processed/failed | `messenger_jobs_processed_total{job_type,job_outcome}` (`success`/`error`/…) |
| Job duration | `messenger_job_duration_seconds_*` |
| Logs | OTLP → Loki; поля severity/body + resource `service.name`; в записи есть trace/span id при активном span |
| Traces | FastAPI server spans; worker span `worker.attachment.process` |
Resource attributes: `service.name` (`messenger-api` / `messenger-worker`), `service.version=1.6.0`, `service.instance.id`, `deployment.environment.name=lab`. В labels метрик нет `user_id`/`chat_id`/`message_id`; тела сообщений, пароли и токены в telemetry не экспортируются. Маршруты — шаблоны FastAPI (`/api/v1/chats/{chat_id}/messages`), не сырые UUID.
Источник истины для метаданных — PostgreSQL; байты — S3; в брокере только ID по `jobs.schema.json`. Compose: `lb` + `api1` + `api2` + `worker` + `postgres` + `s3` + `broker` + `migrate` + `otel-collector` + `prometheus` + `loki` + `tempo` + `grafana`; volumes `pgdata`, `miniodata`, `brokerdata`, `prometheusdata`, `lokidata`, `tempodata`, `grafanadata`.
Перенесено из lab5: auth Basic→Bearer, чаты/сообщения, LB, две реплики, идемпотентность, MinIO, upload `202`/worker/thumbnail.
Добавлено в lab6: OTel SDK, Collector, Prometheus/Loki/Tempo, Grafana provisioning/dashboard.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke при включённой телеметрии | `python tests/smoke.py --base-url http://127.0.0.1:8086` | `PASS: lab6 public API scenario...` | `evidence/smoke.txt` |
| Стенд: lab5-минимум + Collector + 3 сигнала + Grafana | `docker compose --env-file .env ps` | `lb`, `api1`, `api2`, `worker`, `postgres`, `s3`, `broker`, `otel-collector`, `prometheus`, `loki`, `tempo`, `grafana` | `evidence/compose-ps.txt` |
| Импортируемый dashboard | открыть Grafana → Messenger / Messenger lab6 observability | dashboard из provisioning, не только screenshot | `infra/grafana/dashboards/messenger-lab6.json` |
| Метрики API/worker в Grafana | dashboard panels RPS/errors/duration + jobs | ряды после smoke | `evidence/telemetry-notes.txt` |
| Логи и трассы API/worker | Loki `{service_name="messenger-api"}` / Tempo search | есть http_request и job_finished; server/consumer spans | `evidence/telemetry-notes.txt` |
## Эксперименты и отказы
Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены smoke на стенде с телеметрией и наличие сигналов в Grafana после него.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `make test` / smoke при работающих Collector/Prometheus/Loki/Tempo/Grafana | бизнес-сценарий PASS; в Grafana появляются метрики/логи/трассы | smoke PASS; сигналы видны на dashboard | потери бизнес-данных нет |
Локальная проверка автора выполнялась на `HOST_PORT=8086`, Grafana на `3000`. Аппаратный профиль: локальный Docker Desktop на Windows; без CPU/RAM limits на контейнерах.
## Ограничения и следующие шаги
- Traces API и worker видны отдельно; сквозная связь через broker в одном continuous trace не реализована.
- Queue depth, alerts/SLI и поведение при падении telemetry-backend не реализованы.
- Единственный PostgreSQL, MinIO, RabbitMQ, Nginx и telemetry-backend — SPOF; отказ host не выдерживается.
- Basic/Grafana admin по HTTP допустимы только на локальном учебном стенде с синтетическими данными.