Files
mtusi2026lab6/openspec/config.yaml
T
ArtyomandClaude Opus 5.5 a0d3947710 Carry over the agent context and openspec history from lab 5
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>
2026-10-29 03:46:20 +03:00

162 lines
21 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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»."