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>
162 lines
21 KiB
YAML
162 lines
21 KiB
YAML
schema: spec-driven
|
||
|
||
context: |
|
||
# Лабораторная 6 «Наблюдаемость: OpenTelemetry и Grafana» — контекст проекта
|
||
|
||
## Что это
|
||
Skeleton лабораторной 6 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
|
||
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 5. Skeleton содержит
|
||
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.6.0, `observability.md`,
|
||
`jobs.schema.json`, `attachment-states.md`), требования к конфигурации наблюдаемости
|
||
(`infra/otel/README.md`) и публичные black-box проверки (`tests/`, телеметрию не проверяют).
|
||
Целевая оценка — «5»: весь уровень 4 плюс трек 1 «Цена наблюдаемости».
|
||
|
||
## Границы (менять нельзя)
|
||
In scope лабы 6: наблюдаемость всей системы, включая фоновую обработку. Бизнес-API не
|
||
меняется. API, relay и worker отдают метрики, логи и трассы по OTLP в отдельный Collector;
|
||
Collector пишет их в хранилища трёх сигналов (Prometheus, Loki, Tempo) с persistent volumes;
|
||
Grafana показывает их через datasources и dashboards из provisioning в Git. Уровень «3» —
|
||
сигналы уровня «3» из `contracts/observability.md` (RED API, jobs по исходу и duration,
|
||
структурные логи с `trace_id`/`span_id`, реальные server и consumer spans), resource
|
||
attributes, низкая кардинальность, отсутствие секретов и тел в telemetry, запрос → трасса и
|
||
лог, job → трасса и лог worker, `make test` при включённой телеметрии. Уровень «4» — W3C
|
||
trace context API → outbox → broker → worker, producer/consumer spans и цепочка до S3/DB с
|
||
retry, p50/p95/p99 из histogram, доля ошибок, queue depth и возраст старейшей job, DB pool,
|
||
saturation worker, CPU/RAM, time to ready, SLI/SLO, alert rules (error rate, queue lag) с
|
||
firing → resolved, memory_limiter, batch и ограниченные очереди Collector, отказ хранилищ
|
||
телеметрии, разбор двух инцидентов. Трек 1 — цена наблюдаемости: telemetry off / on / head
|
||
sampling / tail sampling / сбалансированная конфигурация при одинаковой open-loop нагрузке.
|
||
Весь обязательный минимум lab1–lab5 (PostgreSQL, Basic → Bearer, keyset-пагинация, HAProxy и
|
||
≥2 реплики, `X-Instance-Id`, `Idempotency-Key`, RustFS, outbox, relay, RabbitMQ, worker с
|
||
арендой и вариантами, хуки отказов) сохраняется без изменений API.
|
||
|
||
Out of scope (не проектировать, не закладывать «на будущее»): TLS, mTLS и OpenBao (лаба 7);
|
||
трек 2 «SLO и обнаружение инцидентов» (не выбран): multi-window burn-rate alerts и слепой
|
||
прогон runbook; внешняя доставка alerts (почта, мессенджер), Alertmanager с receivers;
|
||
кластерные Loki/Tempo/Mimir, долговременное объектное хранилище телеметрии, HA Collector и
|
||
load-balancing exporter; профилирование (Pyroscope), RUM, eBPF; Kubernetes, Docker Swarm и
|
||
несколько узлов; новые бизнес-endpoint и поля контракта; HA брокера и PostgreSQL.
|
||
|
||
## Стек
|
||
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
|
||
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
|
||
`UvicornWorker` (пакет `uvicorn-worker`, `preload_app = False`), dishka (DI, интеграции FastAPI
|
||
и FastStream), pydantic v2 + pydantic-settings, structlog, asyncpg, redis-py для Valkey,
|
||
argon2-cffi, aiobotocore, Pillow, FastStream 0.7 с `faststream[rabbit,otel]` поверх aio-pika,
|
||
OpenTelemetry Python (API/SDK, OTLP/HTTP protobuf exporter без gRPC, инструментации FastAPI и
|
||
asyncpg, версии в `uv.lock`), pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`;
|
||
ruff и ty обязательны на `src/`, `student-tests/` и Python-обвязке стенда; `scripts/*.py`
|
||
держат синтаксис Python 3.9 и stdlib.
|
||
|
||
Инфраструктура — Docker Compose: всё из лабы 5 (`lb` HAProxy 3.2, `api` с `deploy.replicas`,
|
||
`migrate`, `postgres` 17, `valkey` 8, `s3` RustFS, `s3-init`, `broker` RabbitMQ 4.1, `relay`,
|
||
`worker`; сети `edge` и `backend` internal) плюс `otel-collector`
|
||
(`otel/opentelemetry-collector-contrib` по digest, OTLP/HTTP только во внутренних сетях,
|
||
memory_limiter → redaction → batch, ограниченные `sending_queue` и `retry_on_failure`),
|
||
`prometheus` (v3, `--web.enable-otlp-receiver`, rules, volume), `loki` (3.x single binary,
|
||
tsdb v13, OTLP, volume), `tempo` (2.x monolithic, local backend, volume), `grafana` (12.x,
|
||
provisioning из `infra/grafana`, пароль admin через `__FILE`), одноразовый `healthtools`
|
||
(статический busybox для healthcheck образов без shell). Все образы закреплены тегом и digest,
|
||
контейнеры non-root, с лимитами CPU/RAM и `stop_grace_period`. Секреты — compose secrets из
|
||
gitignored `secrets/`.
|
||
|
||
## Архитектура
|
||
Монолит с тремя доменными зонами по книге Персиваля и Грегори
|
||
(`openspec/notes/architecture-patterns-python.md`), развёрнутый как N реплик API и отдельные
|
||
процессы relay и worker из того же образа:
|
||
|
||
main.py сборка HTTP-приложения: вклады зон, связи зон портами, телеметрия процесса
|
||
relay.py сборка процесса relay: outbox → брокер, возврат просроченных аренд
|
||
worker.py сборка процесса worker: FastStream-подписчик очереди заданий
|
||
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
|
||
identity/ пользователи, пароли и сессии
|
||
messaging/ чаты, история и идемпотентная отправка, ссылки сообщения на вложения
|
||
attachments/ вложения: приём и staging, задания и outbox, обработка и варианты, порты
|
||
объектного хранилища, брокера, рендера и учёта заданий с адаптерами
|
||
shared/ только платформа: часы, id, журнал, телеметрия процесса (OTel SDK), пул
|
||
PostgreSQL, UoW-база, конвейер, health, ошибки, настройки, идентификатор реплики
|
||
|
||
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
|
||
от портов, адаптеры подключаются в `ioc.py` зоны. OpenTelemetry SDK и экспортёры живут только в
|
||
`shared/infrastructure/` и в сборке процессов; доменный код и слой приложения не знают об OTel,
|
||
наблюдаемость приходит через порты (`Logger`, учёт заданий) и инструментации на границе.
|
||
Зоны не импортируют друг друга; PostgreSQL — источник истины, S3 — байты, брокер — транспорт,
|
||
Valkey — кэш сессий, хранилища телеметрии — не источник истины ни для одного бизнес-факта.
|
||
|
||
## Источники норм
|
||
- `contracts/observability.md` — нормативные сигналы, resource attributes, запрещённые labels и
|
||
содержимое, alerts и инциденты.
|
||
- `infra/otel/README.md`, `infra/README.md` — что положить в Git и как отчитать роли.
|
||
- `contracts/README.md`, `contracts/openapi.json`, `contracts/jobs.schema.json`,
|
||
`contracts/attachment-states.md` — API и pipeline, неизменные с лабы 5 (кроме версии).
|
||
- `contracts/infrastructure.json` — роли, включая `otel_collector`, `telemetry_storage`, `grafana`.
|
||
- `README.md` — рубрика уровней «3» / «4» / «5»; `COURSE.md` — карта курса и переходы API.
|
||
- `openspec/notes/architecture-patterns-python.md` — словарь паттернов и их компромиссов.
|
||
|
||
При расхождении артефакта с `contracts/` источником считается `contracts/`.
|
||
Подгонка контракта или публичных тестов под реализацию решением не является.
|
||
|
||
rules:
|
||
proposal:
|
||
- "Пиши на русском; идентификаторы, поля, имена метрик, атрибутов и файлов — в оригинальном виде."
|
||
- "Держи в пределах 400 слов: Why / What changes / Impact без воды."
|
||
- "Указывай, какой уровень рубрики закрывает изменение: «3», «4» или заявленный трек «5»."
|
||
- "Обязательна секция «Non-goals» со ссылкой на Out of scope; не тащи в лабу 6 возможности лабы 7 и трека 2."
|
||
- "Связывай изменение с конкретным пунктом рубрики `README.md` и строкой таблицы доказательств `REPORT.md`."
|
||
- "Если изменение трогает `contracts/`, `tests/`, `README.md`, `COURSE.md` или README skeleton в `infra/` — это запрещено, оформляй как вопрос преподавателю."
|
||
specs:
|
||
- "Имя capability начинается с префикса лабы, в которой требование введено: `lab<N>-<имя>`, например `lab6-service-telemetry`. Номер берётся из `lab.json`."
|
||
- "Префикс означает происхождение, а не срок действия: требование с `lab1-` продолжает действовать в лабах 2–7, пока его явно не изменит новая дельта."
|
||
- "Требование существующей capability правится дельтой к ней же, под её исходным префиксом; новый префикс заводится только для по-настоящему нового поведения."
|
||
- "Дельта-спека описывает только наблюдаемое поведение, не реализацию."
|
||
- "Формулируй требования как `### Requirement:` плюс `#### Scenario:` в форме WHEN/THEN на русском."
|
||
- "Каждое требование трассируется на пункт `contracts/observability.md`, `contracts/README.md` или на критерий рубрики `README.md`."
|
||
- "Для сигнала фиксируй наблюдаемое: имя в хранилище (метрика Prometheus, поле Loki, атрибут span в Tempo), единицу, набор labels/атрибутов и запрос, которым его находят."
|
||
- "Сценарии обязаны покрывать негативные пути: недоступный Collector или хранилище телеметрии (API и `/health/ready` работают), выключенный SDK, запрос с паролем, токеном и текстом (их нет в Loki и Tempo), маршрут с UUID (в labels шаблон), запрос без активного span, повторная доставка и retry job, worker остановлен, а также прежние окна отказа lab1–lab5."
|
||
- "Для инфраструктурных требований фиксируй наблюдаемое: какие порты опубликованы, какие volumes переживают рестарт, что показывают `docker compose ps`, health-эндпоинты хранилищ и API Grafana."
|
||
- "Не вводи в контракт поля, заголовки и коды, которых нет в `contracts/openapi.json`."
|
||
design:
|
||
- "Создавай, если изменение затрагивает границы доменных зон, слои, процессы и fork, конкурентность, согласованность хранилищ, конвейер телеметрии, поведение при сигналах или конфигурацию контейнера."
|
||
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
|
||
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру и OTel."
|
||
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
|
||
- "Для телеметрии фиксируй: где и когда инициализируется SDK (после fork), resource attributes, процессоры и экспортёры, что происходит при недоступном Collector (очередь, отбрасывание, память), как SDK выключается."
|
||
- "Для каждого сигнала фиксируй источник (инструментация или свой инструмент), единицу, labels и их кардинальность, границы buckets histogram и почему они такие."
|
||
- "Для логов и трасс фиксируй, какие поля и атрибуты экспортируются, какие запрещены и где это обеспечено (allowlist в приложении, redaction в Collector)."
|
||
- "Для Collector и хранилищ фиксируй pipeline по сигналам, лимиты памяти, размеры очередей, retry, retention и что переживает рестарт."
|
||
- "Секреты, токены, ключи S3, пароли Grafana и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
|
||
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, лимиты, опубликованные порты, переменные окружения."
|
||
tasks:
|
||
- "Задачи — атомарные шаги не длиннее 2 часов, в порядке исполнения."
|
||
- "Группируй по слоям и артефактам: зависимости, платформа телеметрии, доменные зоны, точки входа, Collector и хранилища, provisioning, стенд, проверки, отчёт."
|
||
- "Одна задача не пересекает границу доменной зоны; связь зон оформляется отдельной задачей."
|
||
- "Первой в цепочке идёт задача уровня «3», задачи уровня «4» и трека «5» — после неё."
|
||
- "Каждая группа завершается задачей проверки: какой командой убедиться, что критерий рубрики выполнен."
|
||
- "Не создавай задач, меняющих `contracts/`, `tests/`, `README.md`, `COURSE.md` или рубрику."
|
||
|
||
operations:
|
||
apply:
|
||
guidance:
|
||
- "Соблюдай правило зависимостей: адаптер добавляется за существующим портом, а не импортом инфраструктуры в домен."
|
||
- "Новый код кладётся в свою доменную зону вместе со своими ошибками, событиями, командами и HTTP-фасадом."
|
||
- "`shared/` пополняется только платформой и механизмом связи; доменное понятие туда не попадает никогда."
|
||
- "Ядро `shared/` (domain, application, infrastructure) не импортирует веб-фреймворк и FastStream: транспорт живёт только в `shared/entrypoints/` и в `entrypoints/` зон."
|
||
- "OpenTelemetry SDK, экспортёры и инструментации подключаются только в `shared/infrastructure/` и в сборке процессов (`main.py`, `relay.py`, `worker.py`); SDK создаётся в процессе, который обслуживает запросы, а не в master gunicorn."
|
||
- "Экспорт телеметрии не блокирует запрос и не влияет на `/health/ready`: только batch-процессоры и периодический reader, короткий таймаут OTLP."
|
||
- "Логирование — только через порт `Logger` с allowlist полей; второй логгер в приложении не заводится. Тело сообщения, пароль, токен, `Authorization`, filename, object key и байты не пишутся ни в журнал, ни в атрибуты spans."
|
||
- "Labels метрик — только низкокардинальные (метод, шаблон маршрута, статус, тип job, исход); идентификаторы пользователей, чатов, сообщений, вложений и запросов — только в логах и атрибутах spans."
|
||
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
|
||
- "Конфигурация Collector, Prometheus, Loki, Tempo и Grafana — в `infra/`; dashboards — JSON в Git с фиксированными uid datasources; образы закреплены тегом и digest."
|
||
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
|
||
- "Публичные `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` запускаются против поднятого стенда с включённой телеметрией; после failover реплика возвращается `make restore`."
|
||
- "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается."
|
||
- "Отмечай выполнение в `tasks.md`; резюме держи кратким."
|
||
archive:
|
||
guidance:
|
||
- "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change."
|
||
- "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто."
|
||
- "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства."
|
||
- "Убедись, что `make check`, `make validate`, `make lint`, `make student-test`, `make obs-validate`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` и проверки телеметрии уровня против стенда проходят."
|
||
- "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом."
|
||
- "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."
|