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>
62 lines
11 KiB
Markdown
62 lines
11 KiB
Markdown
## Что это за репозиторий
|
||
|
||
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 с арендой и вариантами, хуки остановки реплики и рестарта стенда.
|
||
|
||
## Команды
|
||
|
||
```sh
|
||
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`: upload `202 queued`, ожидание `ready` до 60 с, ровно один `thumbnail` 256×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 и захват вброшенных ошибок и медленных запросов.
|