Files
mtusi2026lab2/AGENTS.md
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

62 lines
11 KiB
Markdown
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.
## Что это за репозиторий
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 и захват вброшенных ошибок и медленных запросов.