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

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-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 создаётся из примера и не коммитится:

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) только для локального синтетического стенда.

Сборка и запуск:

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 допустимы только на локальном учебном стенде с синтетическими данными.