Files
mtusi2026lab6/KNOWN_ISSUES.md
T
ricoromaandClaude Opus 5.5 a4497e3f32 feat: add OpenTelemetry SDK, collector and telemetry stores
Collector (contrib), Prometheus, Loki, Tempo and Grafana with provisioning
from git; SDK in API and worker with level 3 metrics, traces and logs
carrying trace_id/span_id; telemetry off by default outside the stand;
broker healthcheck runs as the broker user so a fresh stand starts once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 10:19:50 +03:00

214 lines
20 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.
# Известные дефекты
Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md).
Исправленные удаляются отсюда, история — в git.
## Смесь версий при замене реплик на первый релиз с обработкой
- **Где:** `make rolling_update` с прежней версии (design change
`async-attachments`, решение 14), `AttachmentStatus` прежнего образа.
- **Что:** на время замены прежняя реплика отвечает 201 `ready` и даёт 500 на
чтении строки нового статуса (`ValueError` в `_to_dto`), а новая — 202. То же
после отката: незавершённые `queued` и `processing` дают 500 на прежней версии.
- **Чем грозит:** окно замены ограничено, переход 201 → 202 всё равно несовместим
для клиента на это окно; названо в `REPORT.md`.
- **Предложение:** не лечить: объявленный переход контракта. Новые статусы в
будущих версиях добавлять так, чтобы прежняя версия читала строку.
## Bootstrap после удаления bucket на маленьком диске: «api key wait (code 500)»
- **Где:** `infra/s3/bootstrap.sh` (режим `apply`) и сервер `s3`
(`docker-compose.yml`: entrypoint образа добавляет `-volume.max=0
-master.volumeSizeLimitMB=1024`), SeaweedFS 4.48.
- **Что:** после удаления bucket мимо bootstrap (`s3.bucket.delete`)
повторный bootstrap пишет «bucket created», затем «FAILED: api key wait
(code 500)». Найдено в правках по verify change `s3-storage`
(2026-10-20); воспроизведено и объяснено пробой design change
`track2-reconciler` (Context, 2026-10-22, проект `rcprobe`).
- **Причина:** не повторное имя bucket, а слоты томов. С `-volume.max=0`
число слотов считается по свободному месту диска / 1 ГиБ. Удаление
bucket удаляет тома его коллекции, но на маленьком диске слоты уже
заняты томами коллекции по умолчанию (журналы filer), и новых томов для
`messenger` выделить некуда: в журнале S3 — «No writable volumes and no
free volumes left for collection:messenger», PUT получает 500.
- **Условие:** диск, на котором `-volume.max=0` даёт мало слотов, — tmpfs
проб, а не volume стендов проекта. Проба: tmpfs 4 ГБ — 3 слота из 3
заняты, ошибка дважды подряд; tmpfs 16 ГБ — 15 слотов, повтор
bootstrap прошёл за 2 с. Рабочий стенд (volume на диске ВМ) — 417
слотов, 403 свободны (`weed shell volume.list`): удаление bucket и
повтор bootstrap этим не падают. Стенды проекта не затронуты.
- **Чем грозит:** только временным стендам на маленьком tmpfs: после
удаления bucket повтор bootstrap не проходит. Сверка bucket и БД
bucket не создаёт и не удаляет: на `NoSuchBucket` она прерывает проход
без изменений (design change `track2-reconciler`, решение 14).
- **Предложение:** на маленьких дисках — `-master.volumeSizeLimitMB`
меньше 1024 (больше слотов на тот же объём) или явный `-volume.max`;
для стендов проекта не нужно. Запись остаётся открытой.
## Уборщик удаляет объект зависшей загрузки по ключу вне своего префикса
- **Где:** `src/core/services/attachment_cleanup.py`
(`remove_stale_pending`: `delete_original` по `object_key` строки) и
политика `cleaner-objects` в `infra/s3/bootstrap.sh` (`s3:DeleteObject`
на `<bucket>/*`).
- **Что:** сервис уборки (`python -m src.cleaner`, `--once`) убирает
строку `pending` старше grace вместе с объектом по ключу из этой
строки, не проверяя, что ключ под `<база>/attachments/`. Ключ вне
префикса API не пишет; он бывает в базе, восстановленной под другим
именем (её строки ведут к объектам исходной базы), или после ручной
правки. Тогда уборщик удаляет объект чужого префикса — другой базы.
Найдено в правках по verify change `track2-reconciler` (замечание W2,
2026-10-22): сверка такую строку теперь только называет «чужим
объектом» и не убирает (design, «Уточнения apply», п. 19), а сервис
уборки — поведение change `upload-consistency` — не менялся.
- **Чем грозит:** только при строке с чужим ключом: потерей объекта
другой базы того же bucket. Стенды проекта таких строк не содержат.
- **Предложение:** в `remove_stale_pending` (или в `lock_stale_pending`)
— та же проверка `attachment_object_repo.is_own_key`: строку с чужим
ключом убирать без DELETE объекта (или пропускать с `warning`), сценарий
в требовании «Уборщик незавершённых загрузок» и тест на стенде отказов
(`set-key` hook уже есть); при желании — сузить `s3:DeleteObject`
политики до `<bucket>/<база>/attachments/*`, переделав проверки
bootstrap, которые удаляют свои объекты ключом уборщика.
## LB отвечает 408 на медленные заголовки текстом HAProxy
- **Где:** `infra/haproxy/haproxy.cfg`, `defaults`: `timeout
http-request 10s`, HAProxy 3.4.6.
- **Что:** клиент, который присылает заголовки запроса дольше 10 с,
получает от LB 408 со страницей HAProxy в HTML, а не ошибку в формате
контракта (`{"error": {...}}` с `request_id` = `X-Request-Id`).
`http-error status 408 … lf-string` его не меняет: такой ответ HAProxy
строит до потока запроса, где `http-error` уже не действует. Проба
change `upload-memory` (design, Context, п. 4; таблица «HAProxy,
сроки»): заголовки за 12 с — 408 HTML и с `http-error status 408`, и
без него. 400 посреди тела после change идёт в формате контракта.
- **Чем грозит:** клиент с медленной сетью на заголовках получает ответ
вне формата контракта. Путь загрузки и остальные пути API не
затронуты: заголовки приходят за миллисекунды.
- **Предложение:** `errorfile 408` со статичным JSON не годится:
`request_id` в нём один на все ответы, а контракт требует тот же id,
что в `X-Request-Id`, и уникальный. Варианты для разбора: проверить
`http-errors` / `errorloc` и Lua-ответ в новых версиях HAProxy 3.x;
либо поднять `timeout http-request` и назвать ограничение в
`REPORT.md` (уже названо в спеке `load-balancing`, «Ошибки
балансировщика в формате контракта»).
## Поля `float` настроек принимают `inf`
- **Где:** `src/config/settings.py` — все поля `float` с `gt=0` или
`ge=0`, кроме `[reconciler] max_objects_per_second`: сроки `[database]`,
`[cache]`, `[s3]`, `[uploads]`, `[cleaner] interval_seconds`,
`[reconciler] interval_seconds`. Найдено verify change
`track2-reconcile-cost` (S2) на `max_objects_per_second`; там исправлено
(`allow_inf_nan=False`), остальные поля — вне change.
- **Что:** pydantic принимает `inf` (`RECONCILER__INTERVAL_SECONDS=inf`,
`UPLOADS__WAIT_TIMEOUT_SECONDS=inf`): `inf > 0` верно. `nan` отсекают
`gt` и `ge`. Записи старта («Started API», «Started cleaner») выводят
значение как `Infinity` — это не JSON, и разбор журнала по строкам
ломается.
- **Чем грозит:** оператор, ошибившийся в значении, получает срок без
конца (ожидание места загрузки, вызов S3 без срока, плановая сверка,
которая не наступит) и журнал, который не разбирается как JSON.
Значения по умолчанию и `config_example.toml` не затронуты.
- **Предложение:** `allow_inf_nan=False` у каждого поля `float` (или
`model_config = ConfigDict(allow_inf_nan=False)` у секций), сценарий в
требовании «Некорректное значение останавливает запуск» спека
`service-configuration` и проверка `uv run python -c` с `inf` по полям.
## `driver.py reconcile-cycle` на наполненном стенде: свежий F стареет раньше проверки
- **Где:** `.claude/skills/run-mtusi-messenger/driver.py`, строка «exit code after X
and Y are removed» (grace пробы `RC_GRACE_S` 30 с). Найдено прогоном change
`unit-of-work` (задача 11.5); от кода не зависит.
- **Что:** на стенде с 11 тыс. объектов (накоплены `make student_test`) каждый проход
сверки длится ~5,8 с из-за предела скорости 2000 объектов/с, и за шесть проходов
объект F становится старше 30 с раньше этой проверки: dry-run находит `orphan_object`
и даёт код 3 вместо 0. Остальные проверки цикла совпадают, итог команды — код 1.
- **Чем грозит:** ложный FAIL сценария на долго живущем стенде, на чистом стенде его нет.
- **Предложение:** в этой проверке считать допустимой находку F или записывать F позже,
непосредственно перед ожиданием grace; либо передавать пробам `RATE=0`.
## Метаданные и скачивание вложения: 504 от LB вместо 503 при зависшем PostgreSQL
- **Где:** `GET /api/v1/attachments/{id}` и `GET …/content`
(`src/api/routers/v1/attachment.py`), `infra/haproxy/haproxy.cfg`. Найдено
пробами change `unit-of-work` (design, решение 6).
- **Что:** вход и блок сервиса — два блока по сроку `[database]
request_timeout_seconds`, то есть до `2T` = 12 с, а `timeout server` этих путей
— 10 с; общего срока у роутера вложений нет (передача дольше срока блока).
Дефект прежний: `CurrentUserBrief` и `db_scope` тоже были двумя шагами. Путь
загрузки не затронут: его `timeout server` 30 с.
- **Чем грозит:** при зависшем PostgreSQL клиент получает 504 от LB через 10 с
вместо 503 реплики; данные не страдают.
- **Предложение:** общий срок `request_deadline` на этих двух ручках на шаг до
начала потока (вход и блок метаданных, без передачи байтов): отдельной
зависимостью сложно, поток идёт после неё. Проще свой путь в
`http-request set-timeout server` LB для `GET /attachments/…`. Не чинится в
change `unit-of-work`: ручки вложений там без общего срока (решение 6).
## S3 на долго живущем стенде: лимит памяти при всплеске загрузок у границы байтов
- **Где:** сервис `s3` (`docker-compose.yml`: лимит 512 МБ, `GOMEMLIMIT=400MiB`,
`-s3.concurrentUploadLimitMB=64`), SeaweedFS 4.48. Найдено пробой change
`track1-queue-overload` (design, Context, проект `q1probe`, 2026-11-01).
- **Что:** на стенде, который ~80 мин принимал пробы без пересоздания volume (~9 200
заданий), `docker stats` показывал у S3 330–415 МиБ; при 12 загрузках 10 MiB в секунду
ядро его убило (`exit 137`, `OOMKilled: true`, один случай). На свежем стенде те же 12 и
15 загрузок в секунду — 322–399 МиБ и `oom_kill` 0. Зависит ли это от числа объектов,
проба не проверяла.
- **Чем грозит:** пока S3 лежит, загрузка и скачивание — 503. На рабочем стенде его
возвращает `restart: unless-stopped`; в пробе (`restart: "no"`) все 229 незавершённых
заданий за ~85 с исчерпали бюджет: `failed`, `retry_exhausted`, возврат — `make replay`.
Принятая работа не потеряна, реестр её называет.
- **Предложение:** замерить рост памяти S3 с числом объектов (профиль с накоплением, без
пересоздания volume); при подтверждении — лимит 768 МБ или меньше `GOMEMLIMIT`. Метка
`make bench_queue` этого не покажет: её ячейки идут на свежих volume.
## Граница живой загрузки уборщика не учитывает закрытие соединения
- **Где:** `src/cleaner/main.py`, `live_upload_bound_seconds`; `openspec/specs/load-balancing/spec.md`
и `openspec/specs/service-configuration/spec.md` («17 с»). Найдено verify change
`track1-queue-overload` (S9).
- **Что:** формула `2 × request_timeout_seconds + [s3] timeout_seconds` = 17 с не считает закрытие
соединения на зависшем сервере (`DB_CLOSE_TIMEOUT_SECONDS`, 2 с: возврат соединения идёт вне срока
блока). Оценка сверху — 2 × (6 + 2) + 5 = 21 с. То же у молчания реплики до тела: 21 с вместо 17, но
оба меньше `timeout server` 30 с, поэтому цепочка LB верна.
- **Чем грозит:** проверка старта пропускает grace от 18 до 21 с. При 900 с по умолчанию разницы нет,
запас огромный. На стенде отказов grace 20 с: при зависшем PostgreSQL уборщик может взять строку ещё
живой загрузки, но данные не страдают: `mark_queued` помеченную строку не переводит, клиент получает
503, объект удаляется.
- **Предложение:** прибавить `2 × DB_CLOSE_TIMEOUT_SECONDS` в формулу и поднять grace стенда отказов до
22 с и больше, отдельным change; там же поправить «17 с» в спеках. Правка меняет код уборщика и стенд
отказов, в `track1-queue-overload` не входит.
## Нестандартный метод HTTP: 400 текстом uvicorn, мимо приложения
- **Где:** HTTP-парсер uvicorn (httptools, выбирается автоматически), `src/main.py`
(`uvicorn.run` без `http=`). Найдено apply change `otel-telemetry` (`driver.py
telemetry-check`, сценарий `observability` «Необычный метод и неизвестный путь»).
- **Что:** запрос с методом, которого нет в списке llhttp (`BREW`), отклоняется парсером до
ASGI-приложения: `400 Bad Request`, `content-type: text/plain`, тело «Invalid HTTP request
received.», без `X-Request-Id`, `X-Instance-Id` и тела ошибки контракта; ни итоговой записи, ни
span, ни метрики. Метод из списка llhttp, но вне стандартного набора (`PROPFIND`, `PURGE`)
доходит до приложения: 404 в формате контракта и ряд `_OTHER`. HAProxy такой запрос передаёт.
- **Чем грозит:** ответ API не в формате контракта на экзотический метод; сценарий спека с
методом `BREW` по HTTP не воспроизводится — `telemetry-check` проверяет `_OTHER` на `PROPFIND`, а
у `BREW` — только отсутствие метода и UUID в метках.
- **Предложение:** `uvicorn.run(..., http="h11")` (h11 принимает любой токен метода) — после
замера цены на трек 1, — или правило HAProxy, отвечающее 400 в формате контракта на методы вне
списка; затем поправить сценарий спека. Отдельный change.
## Остановка API при замороженном PostgreSQL дольше срока контейнера
- **Где:** `src/main.py`, `await engine.dispose()` в lifespan без общего срока. Найдено
повторным verify change `unit-of-work` (S3); дефект прежний, правкой не вызван.
- **Что:** простаивающие соединения закрываются по очереди, каждое до
`DB_CLOSE_TIMEOUT_SECONDS` (2 с). Замер `dispose` на замороженном сервере: пул 10 —
20,05 с; пул 4 — 8,02 с и на `d8fe2e8`, и на `9efab79`. `docker stop` на замороженном
PostgreSQL не проверялся: то, что контейнер получит SIGKILL после 10 с, — расчёт.
- **Чем грозит:** только при замороженном PostgreSQL во время остановки реплики:
журнал без «Stopped API»; данные не страдают, незафиксированное откатит сервер.
- **Предложение:** общий срок на закрытие в lifespan, как `_CLOSE_TIMEOUT_SECONDS` у
worker и relay, и сценарий в спеке `graceful-shutdown`.