Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 5 specs and the
archived lab 1 to lab 5 changes into the lab 6 skeleton, so lab 6
continues the same spec history instead of starting from scratch. The
files come from the lab 5 solution commit 64d5c67.
Rewrite AGENTS.md and the openspec context and rules for lab 6: the
business API stays at contract 1.6.0, API, relay and worker start the
OpenTelemetry SDK in every process after fork and export OTLP over HTTP
to a separate Collector, Prometheus, Loki and Tempo store metrics, logs
and traces on volumes, Grafana only reads them through provisioning
kept in Git, telemetry never blocks a request and never feeds
/health/ready, metric labels stay low-cardinality and message bodies
and secrets never leave the process. Out of scope moves to lab 7,
track 2 and clustered telemetry backends.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
11 KiB
Что это за репозиторий
Skeleton лабораторной 6 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке solution/bpi2303-kostylev. Skeleton даёт задание (README.md), нормативный контракт (contracts/, включая contracts/observability.md) и публичные black-box проверки (tests/). Реализация API, relay, worker, Dockerfile, compose-стенд, конфигурация балансировщика, S3, брокера и стека наблюдаемости, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 6 построено переносом решения лабы 5.
Лаба 6: наблюдаемость всей системы, включая фоновую обработку. Бизнес-API не меняется (контракт 1.6.0). API, relay и worker инициализируют OpenTelemetry SDK в каждом процессе после fork (gunicorn-воркер, процесс relay, процесс worker) и отдают OTLP/HTTP в OTel Collector (otelcol-contrib); Collector раскладывает метрики в Prometheus 3 (OTLP-приём), логи в Loki 3 (OTLP /otlp), трассы в Tempo 2; Grafana 12 только показывает и связывает их, datasources и dashboards приходят из provisioning в Git. HTTP-метрики и server spans даёт инструментация FastAPI, client spans БД — инструментация asyncpg, consumer spans — RabbitTelemetryMiddleware FastStream. Логи идут через порт Logger (structlog → stdout JSON и OTLP) с trace_id/span_id, без тел сообщений и секретов. Остаётся всё из лаб 1–5: HAProxy перед ≥2 репликами, PostgreSQL, Valkey, RustFS, RabbitMQ, outbox, relay, worker с арендой и вариантами, хуки остановки реплики и рестарта стенда.
Команды
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, версия 1.6.0
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1 и jobs.schema.json (venv с requirements-dev.txt)
make install # uv sync --group dev
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test # собственные тесты (одноразовые PostgreSQL, Valkey, RustFS и RabbitMQ в Docker)
make secrets # локальные secrets/* (lab5 + Grafana и DSN Collector) и .env
make up # docker compose build, затем up -d --wait: хранилища, broker, стек наблюдаемости → migrate, s3-init → api ×2, relay, worker → lb
make obs-validate # otelcol validate, promtool check config, loki/tempo verify, JSON dashboards
make telemetry-check # Grafana provisioning, запрос → лог → трасса, job → трасса и лог worker, утечки
make test # публичный smoke через LB (BASE_URL, по умолчанию http://localhost:8080)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт lb, api, relay, worker и postgres, valkey, s3, broker с volumes
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики TARGET_INSTANCE_ID под запросами
make restore # вернуть остановленные реплики и дождаться их в ротации LB
make level3 # сценарии уровня «3» лабы 5 (scripts/pipeline_suite.py) → evidence/level3.json
make down # остановка без удаления данных; make reset-data — намеренное удаление volumes
tests/*.py и scripts/*.py — только stdlib, синтаксис Python 3.9 (make check разбирает их системным python3). Проверки сами не поднимают стенд. Хуки scripts/stop-one.sh и scripts/restart.sh запускаются тестом без shell, поэтому исполняемые и с shebang. Адреса Prometheus, Loki, Tempo и Grafana для scripts/obs_check.py — переменные PROMETHEUS_URL, LOKI_URL, TEMPO_URL, GRAFANA_URL (по умолчанию стандартные порты на 127.0.0.1).
Архитектура skeleton
lab.json— единственный источник номера лабы (6). От него зависятscripts/check_contract.py(info.version == 1.6.0) иtests/client.py(веткиLAB>=5: upload202 queued, ожиданиеreadyдо 60 с, ровно одинthumbnail256×160). Публичных проверок телеметрии нет: наблюдаемость доказывается своими скриптами иevidence/.tests/байт в байт как в лабе 5.contracts/openapi.jsonотличается толькоinfo.titleиinfo.version.contracts/observability.md— нормативный набор сигналов (уровни «3» и «4»), resource attributes, запрещённые labels метрик и запрещённое содержимое telemetry, alerts и инциденты.infra/otel/README.md— что лежит в Git (Collector, storage, provisioning, dashboards, rules).contracts/infrastructure.json— роли лабы 5 плюсotel_collector,telemetry_storage(метрики, логи, трассы, persistent volume) иgrafana(provisioning в Git).compose.example.yaml— только worksheet ролей.
Ключевые правила контракта (lab6)
- Resource attributes:
service.name(messenger-api,messenger-worker,messenger-relay),service.version,service.instance.id(уникален на процесс:<hostname>-<pid>),deployment.environment.name=lab. - Метрики не получают labels
user_id,chat_id,message_id,attachment_id,request_id, сырой URL, filename, текст; маршрут — шаблон (/api/v1/chats/{chat_id}/messages). HTTP duration — histogram в секундах (http.server.request.duration,OTEL_SEMCONV_STABILITY_OPT_IN=http). - Логи: timestamp, severity,
service.name,event,trace_id/span_idпри активном span. В telemetry никогда не попадают пароли,Authorization, токен сессии, тело сообщения, байты изображения, filename, ключи и подписанные URL; захват HTTP-заголовков выключен, Collector дополнительно редактирует подозрительные ключи. - Экспорт телеметрии никогда не блокирует запрос: только
Batch*ProcessorиPeriodicExportingMetricReader, короткий таймаут OTLP./health/readyне зависит от Collector, хранилищ телеметрии и Grafana.OTEL_SDK_DISABLED=trueвыключает SDK целиком. - Тело ошибки остаётся
{"error":{"code","message","request_id"}}сadditionalProperties: false:trace_idв тело и схемы не добавляется. - Сохраняются правила lab5 (outbox,
202 queued,ackпослеCOMMIT, ключ эффекта,409на/contentдоready), lab4, lab3 (X-Instance-Id,Idempotency-Key), lab2 и lab1.
Правила работы с репозиторием
- Не менять и не ослаблять
contracts/,tests/,README.md,COURSE.md,infra/README.md,infra/otel/README.md, рубрику. Расхождение оформляется вопросом преподавателю. - Код —
src/messenger/, миграции —src/messenger/migrations/NNNN_*.sql, конфигурация LB, нагрузки, S3, брокера и наблюдаемости —infra/(infra/otel,infra/prometheus,infra/loki,infra/tempo,infra/grafana), хуки и обвязка стенда —scripts/, собственные тесты —student-tests/, обезличенные доказательства —evidence/. - Без комментариев в коде; отступы — пробелы (
[tool.ruff.format]); Python 3.14 безfrom __future__ import annotationsиTYPE_CHECKING. - Наружу публикуются только LB, UI брокера, Prometheus, Loki, Tempo и Grafana на
127.0.0.1; порты реплик API, OTLP и self-metrics Collector не публикуются. Порты задаются переменными.env, дефолты compose — стандартные. REPORT.md: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов, сопоставление сигналовobservability.mdреальным именам метрик. PASS без команды не доказательство.- Ветка
solution/bpi2303-kostylev, коммиты на английском, перед каждым —make lint. Никогда не коммитить.env,secrets/, токены, пароли Grafana, ключи S3, пароли брокера, volumes, дампы.
Уровни оценки
Решение заявлено на «5» с треком 1 «Цена наблюдаемости»; таблица доказательств — в REPORT.md.
- 3 — минимум lab5 работает при включённой телеметрии; Collector, Prometheus, Loki, Tempo и Grafana в общем стенде с volumes и provisioning из Git; API, relay и worker отдают OTLP; RPS/errors/duration API, jobs по исходу и duration worker; структурные логи с
trace_id/span_id; реальные server и consumer spans; импортируемые dashboards; нет секретов и тел в telemetry; запрос → трасса и лог, job → трасса и лог worker. - 4 — W3C trace context API → outbox → broker → worker (producer/consumer), цепочка до S3/DB с retry; p50/p95/p99 из histogram, доля ошибок, queue depth и возраст старейшей job, DB pool, saturation worker, CPU/RAM; SLI/SLO, alert rules error rate и queue lag (firing → resolved); memory_limiter, batch, ограниченные очереди, отказ хранилищ телеметрии; два разобранных инцидента.
- 5 — трек 1: telemetry off / on / head sampling / tail sampling / сбалансированная конфигурация при одинаковой open-loop нагрузке — latency с клиента, CPU/RAM вне телеметрии, объём ingest, потери spans и захват вброшенных ошибок и медленных запросов.