242 lines
25 KiB
Markdown
242 lines
25 KiB
Markdown
# Вопросы и решения лабы 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).
|