16 KiB
Отчёт — лабораторная 6
- Автор: Меркулова М. А., БВТ2303.
- Целевая оценка: 4 — весь минимум и все пункты уровня 4 README. Трек 5 не заявлен.
- Ветка:
solution/BVT2303-Merkulova, создана отmainskeleton 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, migration005_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/архивирование вне объёма этой лабы.
Источники
- Собственная лабораторная 5.
- OpenTelemetry Go SDK/exporters.
- W3C Trace Context.
- Collector configuration.
- Loki native OTLP.
- Prometheus histograms.
- Grafana provisioning.