Files
mtusi2026lab6/REPORT.md
T

16 KiB
Raw Blame History

Отчёт — лабораторная 6

  • Автор: Меркулова М. А., БВТ2303.
  • Целевая оценка: 4 — весь минимум и все пункты уровня 4 README. Трек 5 не заявлен.
  • Ветка: solution/BVT2303-Merkulova, создана от main skeleton lab6.
  • Основа: собственная реализация lab5. Бизнес-контракт, README задания, COURSE, Makefile, public tests и contracts сохранены.
  • Commit/PR заполняется при публикации. Использовалась помощь ИИ Codex при реализации, проверках и документации; источники перечислены ниже.

Запуск из чистого clone

Требования: Docker Desktop с Linux containers, Compose 2.22+ / BuildKit, Python 3.9+, make, OpenSSL и интернет для образов/Go modules/PyPI/исходников MinIO. На Windows — WSL2 с Docker integration; отдельная Windows-проверка не выполнялась. Локальный Go нужен только для Go unit/vet.

cd mtusi2026lab6
sh scripts/init-local.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
make check
make test

.env и secrets/ создаются локально, исключены из Git, не копируются из предыдущей лабы. Миграции выполняет migrate, приватный bucket и прикладные права — s3-init. Успешные init-контейнеры завершаются с exit 0. Отдельно установленный Redis/БД/MinIO не требуется. Локальные application images собираются из этого репозитория; worker использует build context application: service:migrate.

По умолчанию API опубликован на http://localhost:8080, Grafana — http://localhost:13000. В проверенном стенде API использует 18086, поскольку предыдущие лабы занимают 8080/18085. Для этого APP_PORT изменён только в локальном .env:

make test BASE_URL=http://localhost:18086
BASE_URL=http://localhost:18086 python3 student-tests/verify_observability.py
BASE_URL=http://localhost:18086 python3 student-tests/verify_incidents.py

Вход в Grafana: пользователь admin, пароль — содержимое локального secrets/grafana_admin_password. Пароль не вставляется в отчёт/команды PR. В папке MTUSI автоматически появляется dashboard MTUSI Messenger — lab6; вручную создавать datasource/panels не нужно. Explore: Prometheus / Loki / Tempo. При изменении GRAFANA_PORT тестам передать GRAFANA_URL=http://localhost:<port>.

up --wait проверяет readiness API/хранилищ основного приложения; доступность наблюдаемости дополнительно проверяет verify_observability.py через реальные backend API.

Проверки

make check
make test BASE_URL=http://localhost:18086
CGO_ENABLED=0 go test ./...
CGO_ENABLED=0 go vet ./...
BASE_URL=http://localhost:18086 python3 student-tests/verify_variants.py
BASE_URL=http://localhost:18086 python3 student-tests/verify_pipeline.py
BASE_URL=http://localhost:18086 python3 student-tests/verify_observability.py
BASE_URL=http://localhost:18086 python3 student-tests/verify_incidents.py
BASE_URL=http://localhost:18086 python3 student-tests/verify_resilience.py

Тесты изменяют только синтетические данные своего стенда. Сценарии остановки контейнеров запускать последовательно. verify_observability создаёт трассу с retry, verify_incidents — два обязательных инцидента и отказ Tempo; finally восстанавливает сервисы. verify_resilience использует публичные hooks и проверяет StartedAt, данные и сохранённую историю telemetry.

Остановка без удаления данных: docker compose --env-file .env down. Намеренный полный сброс учебных данных: docker compose --env-file .env down --volumes.

Архитектура

flowchart LR
    Client --> Nginx
    Nginx --> API1
    Nginx --> API2
    API1 --> PG[(PostgreSQL)]
    API2 --> PG
    API1 --> R[(Redis sessions)]
    API2 --> R
    API1 --> S3[(MinIO)]
    API2 --> S3
    PG --> Dispatcher
    Dispatcher --> Broker[(Redis Streams)]
    Broker --> Worker
    Worker --> S3
    Worker --> PG
    API1 -. OTLP .-> Collector
    API2 -. OTLP .-> Collector
    Dispatcher -. OTLP .-> Collector
    Worker -. OTLP .-> Collector
    Collector --> Prometheus
    Collector --> Loki
    Collector --> Tempo
    Grafana --> Prometheus
    Grafana --> Loki
    Grafana --> Tempo
  • Prometheus хранит временные ряды, histogram buckets, recording/alert rules.
  • Loki хранит структурные логи, принимает native OTLP через /otlp (устаревший Loki exporter не используется).
  • Tempo хранит реальные traces, WAL и blocks.
  • Collector принимает/пакетирует/экспортирует сигналы, не заменяет долговременное хранилище.
  • Grafana визуализирует источники; datasource/dashboard provisioning находится в Git.

Основной API по-прежнему использует PG + Redis sessions + MinIO. Broker/worker и telemetry backend не входят в синхронную readiness API. Принятие job защищено outbox/staging; недоступность telemetry не отменяет business COMMIT.

Изменения относительно lab5

  • internal/telemetry/: SDK providers, структурные OTLP logs, безопасные route labels, HTTP/jobs histograms, pool/queue/process/container metrics, DB/Redis tracers.
  • server.go: server span, X-Trace-Id, request/log correlation; нормализованный route вместо UUID/raw URL. Бизнес-поля ответа не менялись.
  • attachments.go, migration 005_trace_context.sql: W3C context и request_id сохраняются вместе с принятием job.
  • pipeline.go: producer/consumer spans, перенос context через JSON broker, сохранение связи при retry, worker outcome/duration/E2E и busy.
  • store.go: реальные S3 client spans; SQL acquire/query/COMMIT записываются QueryTracer, без SQL text/args.
  • main.go: SDK только для API/worker/dispatcher; ограниченный shutdown, register metrics и resource attributes.
  • compose.yaml, infra/otel/: Collector, три backend, Grafana, 4 persistent volumes, provisioning и alerts.
  • scripts/init-local.sh: локальный пароль Grafana. restart.sh: рестарт также пяти telemetry-сервисов.

Сквозной контекст

HTTP span извлекает W3C traceparent/tracestate. Upload сохраняет carrier в той же транзакции, что attachment/jobs/outbox. Dispatcher создаёт producer child исходного HTTP span и помещает его carrier в разрешённые поля job. Worker создаёт consumer child producer; S3/DB/image.process — дочерние операции consumer. Retry образует новую producer/consumer ветку того же trace. request_id хранится в PG для связи лога worker с исходным HTTP ответом, не становится metric label.

Время до ready — от created_at job в durable acceptance transaction до фиксации ready; включает queue wait и retry. Original/checksum, thumbnail/crop/WebP, ACL, sessions, idempotency, lease и replay lab5 сохранены.

Сигналы и dashboard

Полная схема: infra/otel/signals.md. Исполняемые PromQL/units: dashboard JSON.

Dashboard показывает RPS, 5xx/all business ratio, p50/p95/p99 HTTP, worker outcomes/duration, E2E p95 до ready, queued depth/oldest age, pool used/waiting/capacity, worker busy/capacity и heartbeat, container CPU/RAM, DB availability, SLI, alerts и Collector failures/queue.

Percentiles агрегируются из суммарных histogram buckets обеих реплик:

histogram_quantile(0.95,
  sum by (le) (rate(messenger_http_duration_seconds_bucket{service_name="messenger-api",route!~"/health/.*"}[1m])))

Все duration metrics экспортируются в секундах; logs duration_ms явно обозначены. Queue depth — jobs, age — seconds, RAM — bytes, CPU rate — CPU seconds/second (cores).

Metrics не содержат user_id/chat_id/message_id/attachment_id/request_id/filename/raw URL. В логах и traces допустимы синтетические request/job IDs для корреляции; Authorization, пароли, токены, body и изображение не экспортируются. Это проверено canary-значениями и анализом реальных сохранённых данных.

SLI, SLO и alerts

SLI = доля бизнес HTTP-запросов без 5xx за скользящие 5 минут; SLO ≥99%. Health исключены, клиентские 4xx не считаются отказом сервера. При искусственном отказе SLO может нарушаться — это ожидаемое воздействие теста.

  • MessengerHighErrorRate: 5xx/all >5% за 1m, for:10s.
  • MessengerQueueLag: oldest queued >10s и depth>0, for:10s.
  • Scrape 3s, rule evaluation 5s. Доставка наружу не настроена и не требуется: состояния firing/resolved проверяются локально в Prometheus.

Alert rules и runbook содержат точные запросы, единицы, пороги и шаги диагностики. Alert error ratio — оперативное 1m предупреждение, не burn-rate исследование трека 5.

Ограниченная буферизация

SDK: batch queue 256 spans/log records, batch 64, interval 500 ms, export timeout 2s, без SDK retry; periodic metrics 2s. HTTP handler не ждёт экспорта. Ошибки SDK считаются, payload ошибки не логируется.

Collector: memory limiter 128 MiB/spike32, hard container limit256 MiB, batch64/max128, по 32 batches в очередях traces/logs, 2 consumers, block_on_overflow=false, retry deadline5s. После исчерпания попыток telemetry теряется, а не блокирует мессенджер. Финальные dropped_items считаются по JSON-логам Collector; failed-send counter включает неуспешные отправки и не приравнивается к числу уникальных трасс.

Версии и ресурсы

Компонент Закреплённая версия CPU / RAM limit
Go API/dispatcher Go 1.26.8, builder digest в Dockerfile API: 0.5 / 1536 MiB; dispatcher 0.25 /128 MiB
Worker Python3.13.7, Pillow12.0.0 + Go binary 1 /1536 MiB; decoder RLIMIT_AS1GiB
PostgreSQL 17.6-alpine3.22 1 /512 MiB
Redis sessions / broker 8.2.1-alpine3.22 каждый 0.25 /128 MiB
MinIO RELEASE.2025-10-15T17-29-55Z, official source + checksum 1 /512 MiB
Nginx 1.29.1-alpine3.22 0.25 /64 MiB
Collector contrib 0.136.0 0.5 /256 MiB
Prometheus v3.7.0 0.5 /512 MiB
Loki 3.5.5 0.5 /384 MiB
Tempo 2.8.2 0.5 /384 MiB
Grafana 12.2.0 0.5 /384 MiB

SDK traces/metrics1.38.0, logs0.14.0, resource semantic schema1.37.0; собственная схема сигналов v1. Worker concurrency=1. Хранилища metrics/logs/traces имеют retention 24h и отдельные persistent volumes. Grafana state также в volume. Collector очередь in-memory и после его рестарта не восстанавливается; это не бизнес-очередь.

.env управляет APP_PORT/APP_HOST/APP_ENV, session/idempotency TTL, DB timeout/max connections, worker concurrency/attempts/timeout, staging retention, cleanup grace и GRAFANA_PORT. Внутренний порт API8080, 2 API-реплики, S3 endpoint/region/bucket и OTLP endpoint заданы Compose; ограничения bytes/pixels зафиксированы кодом. Справочные SESSION_STORE/API_REPLICAS/MAX_* из skeleton не переключают реализацию.

Доказательства критериев

Актуальные команды/наблюдения — evidence/lab6-results.md.

Критерий Проверка Доказательство
Минимум lab5, бизнес-контракт make test + verify_variants + verify_pipeline сохранность оригинала, variants, outbox/retry/replay
Три OTLP pipeline и реальные данные verify_observability.py observability-grade4.json
Server/consumer traces + структурные логи тот же тест trace-example.json, correlated-logs.json
W3C, producer/consumer, retry, S3/DB тот же тест минимум две consumer attempts, проверенные parent IDs
Низкая кардинальность и приватность тот же тест + go test labels/canary checks
Dashboard, percentiles, queue/pool/saturation provisioning + backend queries dashboard JSON, реальные metrics
SLI/SLO и два alerts verify_incidents.py incidents-grade4.json: firing/resolved
Два инцидента и диагностика worker stopped + PostgreSQL stopped queue/heartbeat, error ratio/DB spans
Backend telemetry down, bounded memory/queue Tempo stopped под нагрузкой drop counts, memory, business writes
Persistent история и core persistence verify_resilience.py resilience.json, StartedAt и восстановленная telemetry

Ограничения

Один Docker-host и одиночные backend/БД/MinIO/broker не обеспечивают HA при потере host/volume. HTTP используется только на localhost с синтетическими данными. Sampling — ParentBased AlwaysSample для локальной демонстрации; стоимость и альтернативы не исследуются. Очереди SDK/Collector ограничены, но telemetry при отказах может теряться. SLO задан и проверяем, это не обещание production SLA. Полный backup/архивирование вне объёма этой лабы.

Источники