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>
214 lines
20 KiB
Markdown
214 lines
20 KiB
Markdown
# Известные дефекты
|
||
|
||
Найдены попутно, не исправлены без отдельной просьбы (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`.
|