Files
mtusi2026labs/AGENTS.md
T
Artyom 1e00d861a8 Finalize lab 6 report and evidence index
Document grade 3 and 4 evidence, the observability cost study, and review limitations. Separate historical measurements and record static report validation without rerunning Docker workloads.
2026-11-07 04:33:20 +03:00

16 KiB
Raw Blame History

Что это за репозиторий

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 под SQLAlchemy 2.0.45 async (ORM/Core, async_sessionmaker, DeclarativeBase); миграции — Alembic 1.16.5, 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/* (БД, кэш, S3, broker, Grafana) и .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 (через scripts/lab6.sh: http://127.0.0.1:18086)
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

Команды стенда выше запускаются через scripts/lab6.sh, например scripts/lab6.sh make up. Локальные make check validate lint запускаются напрямую; make student-test создаёт одноразовые Docker-зависимости и не выполняется в документационной фазе.

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/, миграции — alembic/versions/, async alembic/env.py, one-shot alembic upgrade head; работа с БД — только SQLAlchemy ORM/Core, asyncpg используется как драйвер, конфигурация 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/shell: API 18086, HAProxy stats 26085, broker UI 26086, Prometheus 26090, Loki 26310, Tempo 26320, Grafana 26300. Для команд стенда используй scripts/lab6.sh, который согласует project, порты, URL проверок и NO_PROXY.
  • 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 и захват вброшенных ошибок и медленных запросов.

Актуальное состояние и границы этапов

  • Автор: Костылев Артём, БПИ2303. Итоговый отчёт — REPORT.md, индекс — evidence/README.md.
  • Актуальный runtime и измеритель: bc1d7aa7713858acb5d65b61d07e69a640f1ee97; успешное независимое ревью: 6ca1c7549978af3127966540385195ab0587f2e1. Поздние исправления ЛР5 доведены до immutable source c7b8feb805d151e878d77b0dff47320a9436b172, решения по путям — forward-port.md.
  • Текущий набор — evidence/forward-published/: 995 passed, 2 skipped, 19 deselected в сохранённом полном suite; 15 пригодных серий, 12000 запросов, balanced −92,2% медианного Tempo ingest, 48/48 error и 48/48 slow. Исторические grade3/grade4/track5 не выдаются за измерение позднего кода. Незатронутые storage/history проверки переиспользуются только с основанием из preserved-mechanisms.json.
  • Пять minor после ревью — review-summary.md и ограничения REPORT. Исправлять только major: доказанная угроза безопасности, потеря/повреждение данных, недоступность сервиса, неработающий обязательный сценарий. Minor сохранять, не блокировать ими отчёт/release; не объявлять неуспешный тест успешным.
  • Этапы запускает только runner: один агент переноса/уровней 3→4→5/evidence → review (отдельный fix major и re-review при необходимости) → отдельный отчёт → один агент нагрузки и публикации. Ревью/отчёт предыдущей лабы может идти параллельно реализации следующей. Самостоятельно фоновых агентов не создавать, runner/state не менять.
  • Обычные Docker-этапы используют отдельные project/порты/volumes совместно с другими лабами; эксклюзивный доступ получает только финальная нагрузка/release. Разрешён mtusi2026lab6 в основном репозитории либо hlpipe-lab6-* в каталоге под ним или /Users/artemkostylev/projects/learning/HL/labs/.pipeline/.runs/labs. Чужие контейнеры не трогать; в конце остановить свои без удаления постоянных volumes. Не выполнять reset/clean и удаление пользовательских данных.
  • Фон и условия измерения фиксировать. Пригодные сохранённые серии переиспользовать после проверки SHA/diff; повторять лишь отсутствующие, неуспешные или признанные непригодными. Изменение только документации не требует новой нагрузки.
  • Отчётная фаза меняет только REPORT.md, AGENTS.md и Markdown внутри evidence; OpenSpec/config, код и raw measurements не меняет. openspec/config.yaml уже содержит актуальный стек; циклы propose/apply/archive закрыты, проверка — openspec validate --all --strict --no-interactive.
  • Публикация только в private MTUCI-Labs на явно назначенном этапе PUBLICATION. Самостоятельные push и Telegram вне назначенной фазы запрещены; для разрешённого Telegram — только telegram-send. ЛР1/2 заморожены; другие репозитории читать только через предоставленный snapshot.