12 KiB
Отчёт — лабораторная 6
- Автор, группа: Гадяцкий Л. Е., БПИ2302
- Целевая оценка: 3
- Commit/PR: solution/BPI2302-Gadiatskiy MR#40: mtusi2026/mtusi2026lab6#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-http1.29.0,opentelemetry-instrumentation-fastapi0.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 создаётся из примера и не коммитится:
cp .env.example .env
Соответствие .env.example:
APP_HOST/APP_PORT— bind uvicorn внутри контейнеров APIHOST_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иapi2S3_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) только для локального синтетического стенда.
Сборка и запуск:
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):
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 (при уже запущенном стенде и включённой телеметрии):
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.
Проверка сохранности:
# 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-реплики:
# Windows:
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080
Остановка:
docker compose --env-file .env down
Намеренное удаление учебных данных (volumes):
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 допустимы только на локальном учебном стенде с синтетическими данными.