diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index fbab227..ec0fc78 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -92,7 +92,7 @@ FastAPI 0.141 из `uv.lock`: `Retry-After` — положительное целое. У нас 429 — только у загрузки, когда заняты места процесса (design change `upload-memory`, решение 2). Места ограничивают одновременность, а не частоту: трактовка — вопрос 1 -преподавателю (`REPORT.md`, «Открытые вопросы преподавателю»). До ответа — 429, ответ +преподавателю (`TEACHER_QUESTIONS.md`, локальный, не в git; разбор — отчёт лабы 4). До ответа — 429, ответ «503» меняет строку `DOMAIN_ERRORS`, сценарии и тесты, но не подход. `DELETE /auth/sessions/current` отвечает 204 без тела. @@ -353,8 +353,8 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — (`status=ready`, `error_code=null`: другого статуса контракт лабы 4 не знает), ссылка в новом сообщении — 201. До пометки — 500, как выше. Контракт неоднозначен («404 — объекта нет», «неожиданное исключение — - 500», `status` только `ready`): это вопрос преподавателю (`REPORT.md`, - «Открытые вопросы преподавателю», п. 2), сделан вариант по + 500», `status` только `ready`): это вопрос преподавателю + (`TEACHER_QUESTIONS.md`, локальный, п. 12; разбор — отчёт лабы 4), сделан вариант по умолчанию. Ответ «иначе» меняет ветку `open_content`, сценарий `attachments` «Потерянный оригинал» и тест `test_reconcile_finds_and_fixes`. diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 2582e09..47276d7 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -195,7 +195,7 @@ paths: lost» и `AttachmentNotFound` (404) до обращения к S3; метаданные и `MessageService` эту колонку не смотрят (200 и 201, как у любого `ready`). Ответ — вариант по умолчанию до ответа преподавателя - (`REPORT.md`, «Открытые вопросы преподавателю», п. 2); + (`TEACHER_QUESTIONS.md`, локальный, п. 12; разбор — отчёт лабы 4); - сверка bucket и БД — `AttachmentReconcileService(uow, storage)` (`services/attachment_reconcile.py`, design change `track2-reconciler`, решения 3, 4, 7, 8), сервис процесса уборщика: diff --git a/AGENTS.md b/AGENTS.md index 3363175..b660988 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -311,8 +311,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore только при живом bucket; больше `[reconciler] max_changes` (100) изменений — ни одного и код 3. Потерянный оригинал помечается (`attachments.lost_at`): скачивание — 404, метаданные — 200, ссылка — - 201 (вопрос преподавателю, `REPORT.md`, «Открытые вопросы - преподавателю»). Уборщику разрешён список только + 201 (вопрос преподавателю, `TEACHER_QUESTIONS.md` — локальный, не в + git). Уборщику разрешён список только с префиксом `<база>/attachments/` (`S3_CLEANER_LIST_PREFIX` у bootstrap). На время восстановления базы уборщик останавливают (`docker.md`). С change `track2-reconcile-cost`: проход затрагивает в diff --git a/QUESTIONS.md b/QUESTIONS.md index d504c48..0946736 100644 --- a/QUESTIONS.md +++ b/QUESTIONS.md @@ -2,7 +2,8 @@ Решения, принятые без пользователя, и вопросы, которые не блокируют работу. Раздел на каждый change: `## `, внутри «Решения» и «Вопросы». -Вопросы преподавателю дублируются в `REPORT.md`. План изменений лабы (`PLAN.md`) +Вопросы преподавателю собраны в локальном `TEACHER_QUESTIONS.md` (не в git, по решению пользователя 2026-11-15; в +`REPORT.md` их нет). План изменений лабы (`PLAN.md`) удалён после последнего шага, последняя версия — `git show db3340d:PLAN.md`; ссылки на него ниже — на эту версию. diff --git a/REPORT.md b/REPORT.md index b44f34f..dfa3407 100644 --- a/REPORT.md +++ b/REPORT.md @@ -11,8 +11,8 @@ - Commit: код последнего change — `56132c7` (правки verify трека 1), метки последнего шага — код `b3a5ab8`, каталоги — `db3340d`, доказательства последнего шага — `db3340d`; снятое на других commit названо в разделе доказательств и в шапке каждого файла - PR: по шаблону `.github/pull_request_template.md`, заголовок `ЛР 6 — БВТ2301 — Сафронов — на 5`; номер — после публикации -- Согласования с преподавателем: три договорённости лаб 1–4 действуют, новых в лабе 6 нет. Открытые вопросы преподавателю — - 10 новых и перенесённые, раздел «Открытые вопросы преподавателю»; решения без пользователя — `QUESTIONS.md` +- Согласования с преподавателем: три договорённости лаб 1–4 действуют, новых в лабе 6 нет; решения без пользователя — + `QUESTIONS.md` - Использованные источники, библиотеки и помощь ИИ — последний раздел ## Запуск из чистого clone @@ -174,51 +174,6 @@ middleware и клиенты инфраструктуры (`src/infra/telemetry/ Новых договорённостей в лабе 6 нет. Расхождения FastAPI, разрешённые согласованием: 422 переведён в 400; битый JSON — 400 раньше 401, остальная валидация — после зависимостей. -### Открытые вопросы преподавателю - -Контракт допускает несколько трактовок, ответа пока нет; сделан названный вариант, подход от ответа -не зависит. Решения без пользователя и вопросы пользователю — `QUESTIONS.md`. - -**Новые в лабе 6:** - -1. **Класс статуса HTTP** («method, route template, status class»): выводится из кода статуса в - запросах (`http_response_status_code=~"5.."`), отдельной метки нет. Иначе — атрибут - `http.response.status_class` в middleware и в запросах dashboard. -2. **Restart hook и телеметрия.** `scripts/restart.sh` перезапускает API и хранилища бизнес-данных, - но не хранилища телеметрии; сохранность истории телеметрии после их рестарта показана отдельно - (`evidence/telemetry/check.md`). Иначе — строка в `scripts/restart.sh`. -3. **`service.version`** — версия контракта `1.6.0`, а не ревизия сборки. Иначе — аргумент сборки - образа. -4. **Необычный метод.** Сценарий «Необычный метод и неизвестный путь» проверен на `PROPFIND`: `BREW` - uvicorn отклоняет до приложения (400 текстом, `KNOWN_ISSUES.md`). Иначе — `http="h11"` у uvicorn или - правило HAProxy. -5. **Время до `ready`** считается от записи задания (та же транзакция, что `queued`, до ответа 202) до - фиксации `ready`; задания после replay не учитываются. Иначе — время replay из аудита - `attachment_job_replays`. -6. **CPU и память процессов** — только у процессов с SDK (реплики, worker вместе с процессами - обработки, relay) из их cgroup; PostgreSQL, S3, брокер, LB и уборщик не представлены: сокет Docker у - Collector — root на ВМ. Иначе — `docker_stats` или cAdvisor с названной ценой. -7. **Queue depth** — логическая очередь заданий по стадиям из PostgreSQL (outbox, отложенные повторы, в - брокере, в обработке), а не счётчик очереди RabbitMQ. Иначе — плагин `rabbitmq_prometheus` и доступ - к брокеру из сети телеметрии. -8. **SLI доступности** считается по ответам клиентам на LB (вместе с 502, 503, 504 самого LB), а «доля - ошибок» контракта (5xx API / бизнес-запросы без health) — отдельная панель. Иначе — SLI по метрикам - API с отдельным счётом ответов LB. -9. **Трек 1: достаточно ли трёх настроек** (выбор в голове 10 %, типовой tail sampling, агрегация - метрик) и проверенной сбалансированной конфигурации на одной нагрузке ниже насыщения? Иначе — вторая - интенсивность (ещё одна метка ~1 ч 50 мин). -10. **Трек 1: управляемые воздействия.** «Известное число» редких ошибок и медленных запросов внесено - строкой вложения без объекта (500), недекодируемым JPEG (`failed`), регистрацией и короткой - блокировкой таблицы сообщений. Допустимо? - -**Перенесены из лаб 4 и 5, ответа нет** (разбор — отчёт лабы 5, «Открытые вопросы преподавателю»): -занятые места загрузки и предел незавершённых заданий — 429, а не 503; потерянный по сверке оригинал — -метаданные 200, байты 404, ссылка 201; повтор сообщения, чьё вложение стало `failed` после отправки, — -201 с тем же `Message`; ориентация и альфа у `crop` и `optimized`; replay — команда `make replay`, а не -HTTP-ручка; изображение вне лимитов обработки — `invalid_image`; удаление объектов неудачной попытки по -сроку хранения; срок приёма при остановленном worker — до предела 250; изоляция `/proc/1/environ` от -процесса обработки (`PR_SET_DUMPABLE=0` не сделан). - ### Ответы на вопросы защиты **Чем лог, метрика и trace отвечают на разные вопросы об одном инциденте?** Метрика — «сколько и @@ -291,8 +246,8 @@ Change `otel-telemetry` (design — `openspec/changes/archive/2026-11-11-otel-te драйвер ждёт в Loki все записи прохода relay, а не первую — две попытки на `ef60b47` упали на этой гонке проверки; панель потерь на тихом стенде — 0); бюджет сервисов телеметрии — на `4178b3d` (лимиты Tempo и Grafana по замеру), шапки файлов `evidence/telemetry/` и `evidence/migrations/`. `evidence/stand/from- -scratch.md` ещё снят на рабочем дереве поверх `9b35c25`: пересъёмка ждёт разрешения пользователя -(`QUESTIONS.md`, `## otel-telemetry`, вопрос 8). +scratch.md` переснят на `28b1704` после разрешения пользователя 2026-11-15 (`QUESTIONS.md`, «Ответы +пользователя после последнего шага»). ### Назначение компонентов @@ -895,7 +850,8 @@ B2 — `probabilistic` 5 %; B3 — `decision_wait` 5 с и `num_traces` 10 000; **Рабочий стенд остаётся со 100 % трасс** и полным набором рядов: проверки уровней 3–4 (`telemetry-check`, `trace-chain`, `alerts-check`) ищут свой запрос и задание по сохранённым наблюдениям; сбалансированная конфигурация — проверяемая -рекомендация (вопрос пользователю — `QUESTIONS.md`, `## track1-telemetry-cost`, вопрос 1). +рекомендация; переводить рабочий стенд на неё пользователь не стал (`QUESTIONS.md`, «Ответы пользователя после последнего +шага»). ### Результаты (метка `baseline2`) @@ -1062,7 +1018,7 @@ QUEUE_LABEL=baseline4` → `evidence/queue/baseline4/`, код `b3a5ab8`, кат Пометка — недогрузка, а не насыщение. По правилу профиля `saturated` — повод переснять, и решение пользователя о swap (2026-11-15) её не покрывает. Метку приняли с пометкой решением основной сессии по указанию пользователя от 2026-10-31: предупреждения о хосте, которые явно не влияют на результат замера, прогон не останавливают (`QUESTIONS.md`, - `## track1-telemetry-cost`, «Решения основной сессии»; пересъёмка ~1 ч 25 мин — вопрос 8 там же, по умолчанию нет). Цена + `## track1-telemetry-cost`, «Решения основной сессии»; пересъёмку пользователь 2026-11-15 отклонил). Цена решения — более широкий разброс повторов (у `full` 2,473–3,228 мс). Поэтому разница `balanced` и `full` — в пределах шума, а не эффект. - **Tempo на границе лимита (наблюдение).** После выборки `memory.peak` Tempo у вариантов со всеми трассами — 595–640 МиБ @@ -1099,23 +1055,16 @@ QUEUE_LABEL=baseline4` → `evidence/queue/baseline4/`, код `b3a5ab8`, кат (`evidence/telemetry/budget.md`), это постоянная величина, а не результат варианта. Цена запросов панелей к хранилищам тоже не измерена. - Одна интенсивность ниже насыщения (~230 запросов/с на две реплики), открытая модель. Цена при насыщении и вторая точка - нагрузки не измерены (вопрос 1 ниже). + нагрузки не измерены. - Прогон длится 150 с: рост на диске — журнал предзаписи. Сутки и неделя — пересчёт принятых байт без сжатия блоков и без компакции. - Шум A/A — одна пара `full` / `full-aa` в той же метке; сдвиг хоста в третьем круге расширяет разброс, мелкие различия вариантов с SDK (`full`, `tail`, `metrics`, `balanced`) — в пределах шума. - Медленные записи внесены блокировкой таблицы, ошибки — строкой без объекта: это управляемые события с известным счётом, - а не естественный поток (вопрос 2 ниже). + а не естественный поток. - Причина недостающей трассы у `tail` не установлена (выше). Квантили сравниваются с квантилем журнала за то же окно, а не с истиной клиента. -### Открытые вопросы преподавателю (трек 1) - -1. Достаточно ли трёх настроек (выбор в голове 10 %, типовой tail sampling, агрегация метрик) и проверенной сбалансированной - конфигурации на одной нагрузке ниже насыщения? Иначе — вторая интенсивность (ещё одна метка ~1 ч 50 мин). -2. «Известное число» редких ошибок и медленных запросов внесено строкой вложения без объекта (500), недекодируемым JPEG - (`failed`), регистрацией и короткой блокировкой таблицы сообщений — допустимы ли такие управляемые воздействия? - ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | @@ -1150,9 +1099,8 @@ QUEUE_LABEL=baseline4` → `evidence/queue/baseline4/`, код `b3a5ab8`, кат без правок кода. Файлы уровней 3–5 сняты на commit своих change и с тех пор не переснимались, потому что код, который они проверяют, не менялся: `telemetry-check` — на `4a2f9c9`; `trace-chain` и `telemetry-outage` — на `15ea156`; `alerts-check`, `backend-outage` и `rules-test` — на `ef60b47`; бюджет — на `4178b3d`, `72cfa9a` и `15ea156`. `evidence/stand/from-scratch.md` -снят на рабочем дереве поверх `9b35c25`: команда сама удаляет volumes своего проекта, а это ждёт подтверждения пользователя -(вопрос 8 `## otel-telemetry`); сценарий «стенд с нуля одной командой» на закоммиченном коде показывает -`evidence/tests/clean-clone.md`. +— на `28b1704` (команда сама удаляет volumes своего одноразового проекта, пользователь разрешил 2026-11-15); тот же сценарий +из чистого clone — `evidence/tests/clean-clone.md`. ## Эксперименты и отказы @@ -1207,8 +1155,8 @@ swap, S3 1 / 512, LB 1 / 256; варианты «до» (образ `9cc6c0c`, **`dirty: true`.** Код — `b3a5ab8`, но метка очереди начата сразу после метки загрузок, когда в рабочем дереве были незакоммиченный каталог `evidence/uploads/baseline/` и правка этого отчёта (агент писал его во время замера). Образ и `bench/` эти файлы не читают (образ копирует `src/`, `migrations/`, `alembic.ini` и lock; `*.md` и `evidence` — в `.dockerignore`), других изменений не было, -поэтому числа воспроизводятся из `b3a5ab8`. Метка принята без пересъёмки — ошибка порядка названа, вопрос «переснять?» — -`QUESTIONS.md`, `## Последний шаг`. +поэтому числа воспроизводятся из `b3a5ab8`. Метка принята без пересъёмки — ошибка порядка названа, пересъёмку пользователь +2026-11-15 отклонил (`QUESTIONS.md`, «Ответы пользователя после последнего шага»). | Гипотеза | Вердикт | Главное | | --- | --- | --- | @@ -1265,8 +1213,8 @@ swap, S3 1 / 512, LB 1 / 256; варианты «до» (образ `9cc6c0c`, недосчёт `increase()` после рестарта, кроме перезапуска того же процесса быстрее ~75 с (срок рядов экспортёра 1 мин). - **Рабочий стенд хранит все трассы.** Сбалансированная конфигурация трека 1 (`bench/otel/`) проверена, - но рабочий стенд на неё не переведён: проверки уровней 3–4 ищут свой запрос (вопрос 1 - `## track1-telemetry-cost` в `QUESTIONS.md`). У типового tail sampling одна трасса медленной записи из 75 + но рабочий стенд на неё не переведён (решение пользователя 2026-11-15): проверки уровней 3–4 ищут + свой запрос. У типового tail sampling одна трасса медленной записи из 75 не найдена, причина не установлена. - **Пороговые оповещения, без burn-rate и доставки.** Трек 2 не выбран: оповещения — пороговые с окнами 2 мин, Alertmanager не ставится, состояние firing / resolved — в Prometheus и Grafana.