Files
mtusi2026lab6/QUESTIONS.md
T
2026-11-11 17:38:05 +03:00

242 lines
25 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.
# Вопросы и решения лабы 6
Решения, принятые без пользователя, и вопросы, которые не блокируют работу.
Раздел на каждый change: `## <change>`, внутри «Решения» и «Вопросы».
Вопросы преподавателю дублируются в `REPORT.md`. План изменений лабы —
`PLAN.md`.
## Ответы пользователя перед прогоном (2026-11-11)
- Оценка — 5, трек 1 «Цена наблюдаемости».
- Хранилища — Prometheus (метрики), Loki (логи), Tempo (трассы), отдельными
сервисами; интерфейс — Grafana.
- Уровень 4 — два change: `job-trace-propagation`, затем `slo-alerts`.
- Без пользователя можно (как в лабе 5): коммиты на ветках `feat/<change>`,
ff-merge в `solution/bvt2301-safronov`, архивация, установка зависимостей и
образов, запуск стенда и замеров, в конце `git push` ветки решения в свой
fork. PR не открывать. Разрешения — `.claude/settings.local.json`.
- Длинные замеры исключений (`make bench_uploads`, `make bench_queue`) — в
последнем шаге, на коде лабы 6 с телеметрией.
## Перенос из лабы 5
Источник: `mtusi2026lab5-safronov`, ветка `solution/bvt2301-safronov`,
commit `046ec9e`. Перенос — 2026-11-11.
### Решения
- Перенесены отслеживаемые файлы по AGENTS.md, «Переход в следующую лабу»,
`git archive 046ec9e`: `src/`, `student-tests/`, `service-tests/`,
`migrations/`, `alembic.ini`, `Dockerfile`, `docker-compose.yml`,
`infra/valkey/`, `infra/haproxy/`, `infra/s3/`, `infra/rabbitmq/`,
`infra/rollback/` (на него ссылаются `balancer.md` и откат реплик; в списке
переноса его не было — список дополнен), свои `scripts/restart.sh`,
`scripts/stop-one.sh`, `scripts/rolling-update.sh`, `pyproject.toml`,
`uv.lock`, `.python-version`, `config_example.toml`, `AGENTS.md`,
`CLAUDE.md`, `.claude/`, `openspec/`, `.graphifyignore`, `bench/`,
`KNOWN_ISSUES.md`, `.github/workflows/application.yml`, `.github/ci/`.
- Не перенесены: `README.md`, `COURSE.md`, `tests/`, `contracts/`, `lab.json`,
`REPORT.md`, `evidence/`, `graphify-out/`, `QUESTIONS.md` (этот файл —
новый), `.env`, `config.toml`, `.venv`.
- `Makefile`, `.gitignore`, `.dockerignore` skeleton лаб 5 и 6 совпадают
побайтно, поэтому взяты целиком из лабы 5 (skeleton + свои секции).
- `.env.example` — свой файл лабы 5 без правок. Новые имена skeleton
(`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`,
`OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_RESOURCE_ATTRIBUTES`) сопоставляет
первый change лабы (`PLAN.md`), как `BROKER_URL_FILE` и др. в лабе 5.
- Контракт API лабы 6 не изменился: `contracts/openapi.json` отличается только
`info` (заголовок, версия 1.6.0), `contracts/README.md` и `tests/` совпадают
с лабой 5. Новое — `contracts/observability.md`, три роли в
`contracts/infrastructure.json` (`otel_collector`, `telemetry_storage` с
persistent volume, `grafana` с provisioning в git), `infra/otel/README.md`.
`tests/client.py` для лабы 6 ведёт себя как для лабы 5 (загрузка — 202).
- Имя проекта compose и образ — `mtusi-lab6`, `mtusi-messenger:lab6`
(`docker-compose.yml`, спеки `container-run` и `container-image`, правила
`docker.md` и `balancer.md`, драйвер и `SKILL.md`, комментарии override CI
и стенда отказов), префикс проектов CI — `mtusi-lab6-safronov-ci-`. Иначе
стенд лабы 6 подключился бы к volumes лабы 5.
- `.claude/settings.local.json` (не в git) — только запреты: удаление
volumes лаб 5 и 6, `make wipe_data`, `down -v`, force push. Разрешения
прогона лабы 5 (commit, merge, push) не перенесены: для лабы 6 их даёт
пользователь перед прогоном (`PLAN.md`, «Что решает пользователь»).
- Commit «до» профилей `rollout`, `uploads`, `reconcile` стенда `bench/`
(`Profile.rollout_from`, `uploads_before`, `reconcile_before`) указывали на
commit лабы 5 (`7f38948`, `04f8592`), которых в истории лабы 6 нет: профили
отказали бы с кодом 2 до стенда. Они переведены на commit переноса `9cc6c0c`
отдельным коммитом, как `cc33a03` в лабе 5. Там же код успеха варианта «до»
профиля `uploads` — 202 вместо 201 (`uploads_success_codes`): «до» теперь код
лабы 5, его загрузка отвечает 202; с 201 вариант насчитал бы ноль успешных.
- Проверено на рабочем дереве после переноса: `make check` — PASS; `ruff
check` и `ruff format --check` — чисто (545 файлов); `make service_test` —
215 passed; `make run_docker` на новом проекте `mtusi-lab6` — см. дефект
ниже, после повторного `docker compose up -d --wait` все сервисы `healthy`
/ `running`; `make test` — PASS («lab6 public API scenario»); `make
student_test` — 223 passed, 1 failed: `test_exclusion_evidence_exists`
(ожидаемо, evidence не переносится). Нет 10 файлов:
`evidence/attachments/failover.md`, `evidence/attachments/storage.md`,
`evidence/auth/passwords-and-tokens.md`, `evidence/broker/isolated.md`,
`evidence/broker/stand.md`, `evidence/cache/hits.md`,
`evidence/idempotency/replay-after-restart.md`,
`evidence/queue/baseline4/summary.md`,
`evidence/replicas/test-persistence.md`,
`evidence/uploads/baseline/summary.md`. Сверка становится зелёной, когда
они сняты заново на стенде лабы 6 (`PLAN.md`, шаг 0 и последний шаг).
- Найден дефект первого старта RabbitMQ на пустом volume (`eacces` на
`.erlang.cookie` из-за healthcheck от root): `make run_docker` из чистого
clone падает на «dependency failed to start». Записан в `KNOWN_ISSUES.md`
с предложением правки, не исправлен: правка входит в первый change
(`PLAN.md`).
### Вопросы
Пока нет: решения пользователя — раздел «Ответы пользователя перед прогоном».
## otel-telemetry
Change `openspec/changes/archive/2026-11-11-otel-telemetry/` (propose и архив 2026-11-11). Номера —
решения design.
### Решения
- Развилки `PLAN.md` (раздел «1. `otel-telemetry`»): Collector — contrib 0.164.0, ради `tail_sampling` трека 1 (1); логи —
из SDK, процессором structlog в обеих цепочках, а не `filelog` по журналам Docker (2); метрики — `prometheus` exporter
Collector и scrape Prometheus, а не OTLP-приёмник Prometheus и не remote write (3); инструментирование — вручную в
единственных точках вызова, библиотек автоинструментирования нет: `instrumentation-sqlalchemy` 0.66b2 требует
`sqlalchemy<2.1`, а в lock 2.1.1 (4); relay и уборщик — без SDK до change 2 (5); `scripts/restart.sh` сервисы телеметрии
не трогает, история проверяется `telemetry-check` (6); начальные лимиты телеметрии — 2,5 CPU и 2048 МиБ, итог — по
замеру (7).
- Версии — последние патчи линий, вышедшие хотя бы за две недели до прогона: Prometheus v3.15.1, Loki 3.7.9, Tempo 3.1.1;
Grafana 13.3.1 — патч всех линий от 10.11 (1).
- Настройки — секция `[telemetry]`, по умолчанию выключено; стенд включает её окружением `api` и `worker`. Имена skeleton
`OTEL_*` не настройки: SDK собирается из явных значений, переменные `OTEL_*` удаляются из окружения процесса с `warning`
(8).
- `service.version` — версия контракта `1.6.0` (заодно `FastAPI(version=…)` вместо устаревшего 1.5.0), а не commit сборки
(9).
- API не продолжает входящий `traceparent` клиента: публичная точка входа (10).
- Класс статуса HTTP — первая цифра `http.response.status_code` в запросах; отдельной метки нет (10).
- Исход доставки worker (`ready`, `failed`, `retry`, `skipped`, `requeued`, `dropped`, `error`) возвращает сервис, метрику
и span пишет точка входа; меняется тип результата `handle` и быстрые тесты сервиса (11).
- Текст исключений в span не пишется — только класс ошибки; traceback — в журнале (10, 12).
- Закрытие SDK — со своим сроком в отдельном потоке: пробы — до 6 с на `shutdown()` при замороженном Collector (13).
- Grafana — без состояния (tmpfs), без загрузки плагинов, лишние встроенные источники выключены (проба: 368 → 251 МиБ) (16).
- Хранилища и Grafana — в отдельной сети `telemetry`, наружу — только Grafana на `127.0.0.1` (17).
- Collector, Loki и Tempo без healthcheck Docker: в образах нет оболочки и HTTP-клиента; живость — `up` в Prometheus (18).
- Брокер: healthcheck от пользователя брокера (`gosu rabbitmq`) — закрывает дефект первого старта (19).
- Консоль, `make test_isolated`, стенд отказов и `bench/` — без телеметрии (20).
- Проверка «стенд с нуля» — команда драйвера со своим проектом compose, которая сама удаляет свои volumes:
`make wipe_data` и `down -v` агенту запрещены (21).
- Apply (2026-11-11), подробности — design, «Уточнения apply»:
- `BREW` не доходит до приложения (парсер uvicorn, 400 текстом): `_OTHER` проверен на `PROPFIND`, дефект — в
`KNOWN_ISSUES.md` (п. 2);
- атрибуты сверх решения 12: `stored` у `SET` Valkey, `messenger.s3.result`, `error.type` = код у 5xx без исключения,
атрибуты процесса обработки (п. 3);
- закрытие SDK — по потоку на провайдер (п. 4); подтверждение доставки — внутри места конкуренции (п. 5);
- Grafana: выключены 15 встроенных источников, кроме prometheus, loki, tempo; сверх решения — получение ключей
плагинов, внешние снимки, ссылки обратной связи, gravatar (п. 6);
- `level=error` Loki «empty ring» на старте и Tempo «no jobs found» в простое — шум, не отказ (п. 7);
- `stand-from-scratch` останавливает рабочий стенд на время проверки (`make stop` / `docker compose start`) (п. 10);
- лимиты решения 7 подтверждены замером, не менялись (п. 11).
- Правки по verify (2026-11-11, design, «Уточнения apply», п. 13–18):
- дренаж API 9 с с включённой телеметрией — ошибка настроек с именем `app.graceful_shutdown_seconds` (8 + 1 с SDK ≤ 9
с), без телеметрии 9 с допустимы; у worker закрытие SDK — внутри прежнего окна 0,5 с (п. 13);
- экспортёры OTLP — своя `requests.Session` с `trust_env=False`: прокси окружения не действуют (п. 14);
- сценарий «Необычный метод и неизвестный путь» — на `PROPFIND` и `GET`, `BREW` — ограничение (п. 15);
- `telemetry-check`: ссылки лог ↔ трасса источников Grafana, нет рядов health, `service.instance.id` worker (п. 16);
- `stand-from-scratch --project` — только `mtusi-lab6-scratch[-…]`, иначе код 2 до docker (п. 17).
### Вопросы
Не блокируют работу; ответ меняет только указанное место.
1. Преподавателю: класс статуса HTTP («method, route template, status class») — допустимо ли выводить его из кода статуса в
запросах (`http_response_status_code=~"5.."`) без отдельной метки? Иначе — атрибут `http.response.status_class` в
middleware и в запросах dashboard.
2. Преподавателю: restart hook перезапускает API и хранилища бизнес-данных, но не хранилища телеметрии; сохранность истории
телеметрии показана отдельно (`evidence/telemetry/check.md`). Достаточно ли так? Иначе — строка в `scripts/restart.sh`.
3. Преподавателю: `service.version` — версия контракта, а не ревизия сборки. Иначе — аргумент сборки и четыре пути сборки
(design, решение 9).
4. Преподавателю: ответы, которые генерирует HAProxy (502, 503, 504), в метрики API не попадают, метрик HAProxy на уровне 3
нет. Для SLO уровня 4 это решает change `slo-alerts`.
5. Пользователю: метки последнего шага (`make bench_uploads`, `make bench_queue`) по методике `bench/` снимаются с
выключенным SDK: «код лабы 6 с телеметрией» — код есть, телеметрия выключена. Если нужны метки с включённой телеметрией —
это профиль трека 1 (change `track1-telemetry-cost`) и другая методика.
6. Преподавателю (apply): сценарий `observability` «Необычный метод и неизвестный путь» назван методом `BREW`, а его
uvicorn отклоняет до приложения (400 не в формате контракта, `KNOWN_ISSUES.md`). Достаточно ли `_OTHER` на методе,
который доходит до приложения (`PROPFIND`)? Иначе — `http="h11"` у uvicorn или правило HAProxy (отдельный change).
7. Пользователю (apply): перед замерами для отчёта переснять `telemetry-check`, `telemetry-outage`,
`stand-from-scratch` и бюджет на закоммиченном коде — evidence сняты на незакоммиченном дереве поверх `9b35c25`.
Сделано частично: `telemetry-check` и `telemetry-outage` пересняты на `68f1e97`; замер бюджета на нём поднял лимиты
Tempo и Grafana (design, «Уточнения apply», п. 19); `budget.md` переснят на `4178b3d`. `stand-from-scratch` не
переснят: запуск команды агентом 2026-11-11 отклонил классификатор режима auto (вопрос 8), `evidence/stand/
from-scratch.md` — прежний, с рабочего дерева поверх `9b35c25`. Нужен запуск пользователем (`make stop`, `python3
.claude/skills/run-mtusi-messenger/driver.py stand-from-scratch --runs 2`, `docker compose start`) или разрешение.
8. Пользователю (verify W4): `driver.py stand-from-scratch` сам удаляет volumes своего проекта (`docker compose -p
mtusi-lab6-scratch… down -v` в начале, после каждого прогона и при Ctrl+C), а deny-правила `.claude/settings.local.json`
запрещают агенту `down -v`. Подтвердите, что так можно для одноразового проекта `mtusi-lab6-scratch*` (как у `make
failure_checks` со своим `<рабочий>-failures`). Имя проекта команда теперь принимает только по шаблону
`^mtusi-lab6-scratch(-[a-z0-9]+)?$`, иначе код 2 до вызовов docker. Настройки разрешений не менялись. Иначе —
убирать проект scratch руками пользователя, а команда только печатает команду уборки.
### Предложения на потом
Найдено verify, решено не исправлять в этом change.
- S2: evidence для сценария «Restart hook не трогает телеметрию» — по коду выполняется (`scripts/restart.sh` сервисы
телеметрии не называет), но вывода нет. Предложение: в `telemetry-check` или отдельной пробе — `StartedAt` сервисов
телеметрии до и после `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (задача 11.5 его уже сверяет на глаз).
- S4: relay и уборщик SDK не запускают, но загружают его модули через `SqlAlchemyUnitOfWork` (`src/infra/db/uow.py` →
`src/infra/telemetry`): 139 модулей, RSS уборщика ~100 МиБ при ~90 МиБ в `docker.md`. Предложение для change 2: ленивый
импорт SDK в `src/infra/telemetry` (до `start`) или замер `memory.peak` relay и уборщика и правка `docker.md`.
Решено в change `job-trace-propagation` (design, решение 7): ленивый импорт.
## job-trace-propagation
Change `openspec/changes/job-trace-propagation/` (propose 2026-11-11). Номера — решения design.
### Решения
- Развилки `PLAN.md` (раздел «2. `job-trace-propagation`»):
- parent или link — consumer span дочерний к контексту сообщения и с link на него (2): обработка по одному сообщению без
объемлющего span, semantic conventions messaging это допускают и требуют link; одна трасса на загрузку и цельная выборка
цепочки при head sampling трека 1. Span producer — на каждую публикацию, в клиенте брокера, дочерний к контексту загрузки,
сохранённому в задании (3, 4);
- источник очереди — relay: снимок по PostgreSQL раз в 5 с одним запросом по частичным индексам (проба — 0,31 мс), стадии
`scheduled`, `outbox`, `published`, `processing`, возраст старейшего незавершённого от устойчивого приёма (9); не
приёмник Collector (пароль PostgreSQL у Collector) и не метрики брокера (нет outbox и возраста);
- смесь версий при `make rolling_update` — строки и сообщения без контекста: span producer нет, consumer span — корень, как
на уровне 3; ни одна комбинация версий не даёт ошибки (6);
- `docker.sock` у Collector отвергнут (доступ к API Docker — root на ВМ): CPU и память — из cgroup v2 изнутри контейнеров
API, worker и relay (12).
- Carrier — заголовки AMQP `traceparent` и `tracestate`, тело сообщения по `contracts/jobs.schema.json` не меняется (1):
неверное значение в теле сделало бы сообщение «не по схеме» (`dropped`), а заголовок просто игнорируется;
`contracts/attachment-states.md` native headers допускает, отображение полей — в `REPORT.md`.
- Контекст в задании — колонки `attachment_jobs.traceparent`, `tracestate` (`text NULL`, CHECK `NOT VALID`), пишет загрузка
через зависимость API; сервис телеметрию не импортирует (4).
- Sampler — `ParentBased(ALWAYS_ON)`: при 100 % то же, флаг выборки контекста задания соблюдается; baggage не переносится (5).
- SDK в relay (`messenger-relay`); у уборщика и команды replay SDK нет; модули SDK грузятся только при запуске телеметрии —
закрывает S4 change `otel-telemetry` (проба: −322 модуля и −10 МиБ RSS) (7).
- `handle()` worker возвращает DTO итога доставки (исход, попытка, причина, код ошибки, время до готовности); время до
готовности — от записи задания до фиксации `ready`, задания после replay не учитываются (8).
- Пул — `db.client.connection.*` semantic conventions; ожидающие и отказы по сроку считает пул `CountingQueuePool` (публичный
`Pool.connect()`), фабрика engine о телеметрии не знает (10).
- Насыщение worker — занятые места, ёмкость, ожидающие места доставки и среднее за окно по сумме длительностей (11).
- Без `messaging.message.id` и без span Create и Settle: `id` задания в span — против решения 12 change `otel-telemetry`,
подтверждение — внутри consumer span (13, Non-Goals).
- Новых параметров `[telemetry]` нет: интервал и срок свежести снимка очереди, границы времени до готовности — константы.
- Dashboard уровня 4 — тот же `messenger-overview.json` (без нового bind mount и `configs` CI) (14); проверка — одна команда
драйвера `trace-chain` (16).
### Вопросы
Не блокируют работу; ответ меняет только указанное место.
1. Преподавателю: «End-to-end time to ready — от durable acceptance до публикации ready» измеряется от записи задания (та же
транзакция, что `queued`, до ответа 202) до фиксации `ready`, а задания после replay не учитываются: их приём — действие
оператора. Достаточно ли так? Иначе — время replay из аудита `attachment_job_replays` (worker, решение 8).
2. Преподавателю: «process/container CPU/RAM» — только у процессов с SDK (реплики API, worker вместе с процессами обработки,
relay), из их cgroup; PostgreSQL, S3, брокер, LB и уборщик не представлены, потому что сокет Docker у Collector — root на
ВМ. Достаточно ли? Иначе — `docker_stats` или cAdvisor с названной ценой (решение 12).
3. Преподавателю: «Queue depth» — логическая очередь заданий по стадиям из PostgreSQL (outbox, отложенные повторы, в брокере,
в обработке), а не счётчик очереди RabbitMQ: очередь брокера — стадия `published`. Достаточно ли? Иначе — плагин
`rabbitmq_prometheus` и доступ к брокеру из сети телеметрии (решение 9).