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>
20 KiB
20 KiB
Известные дефекты
Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md). Исправленные удаляются отсюда, история — в git.
Смесь версий при замене реплик на первый релиз с обработкой
- Где:
make rolling_updateс прежней версии (design changeasync-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 changes3-storage(2026-10-20); воспроизведено и объяснено пробой design changetrack2-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 changetrack2-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 changetrack2-reconciler(замечание W2, 2026-10-22): сверка такую строку теперь только называет «чужим объектом» и не убирает (design, «Уточнения apply», п. 19), а сервис уборки — поведение changeupload-consistency— не менялся. - Чем грозит: только при строке с чужим ключом: потерей объекта другой базы того же bucket. Стенды проекта таких строк не содержат.
- Предложение: в
remove_stale_pending(или вlock_stale_pending) — та же проверкаattachment_object_repo.is_own_key: строку с чужим ключом убирать без DELETE объекта (или пропускать сwarning), сценарий в требовании «Уборщик незавершённых загрузок» и тест на стенде отказов (set-keyhook уже есть); при желании — сузить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уже не действует. Проба changeupload-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 changetrack2-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_S30 с). Найдено прогоном changeunit-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. Найдено пробами changeunit-of-work(design, решение 6). - Что: вход и блок сервиса — два блока по сроку
[database] request_timeout_seconds, то есть до2T= 12 с, аtimeout serverэтих путей — 10 с; общего срока у роутера вложений нет (передача дольше срока блока). Дефект прежний:CurrentUserBriefиdb_scopeтоже были двумя шагами. Путь загрузки не затронут: егоtimeout server30 с. - Чем грозит: при зависшем PostgreSQL клиент получает 504 от LB через 10 с вместо 503 реплики; данные не страдают.
- Предложение: общий срок
request_deadlineна этих двух ручках на шаг до начала потока (вход и блок метаданных, без передачи байтов): отдельной зависимостью сложно, поток идёт после неё. Проще свой путь вhttp-request set-timeout serverLB дляGET /attachments/…. Не чинится в changeunit-of-work: ручки вложений там без общего срока (решение 6).
S3 на долго живущем стенде: лимит памяти при всплеске загрузок у границы байтов
- Где: сервис
s3(docker-compose.yml: лимит 512 МБ,GOMEMLIMIT=400MiB,-s3.concurrentUploadLimitMB=64), SeaweedFS 4.48. Найдено пробой changetrack1-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_kill0. Зависит ли это от числа объектов, проба не проверяла. - Чем грозит: пока 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 changetrack1-queue-overload(S9). - Что: формула
2 × request_timeout_seconds + [s3] timeout_seconds= 17 с не считает закрытие соединения на зависшем сервере (DB_CLOSE_TIMEOUT_SECONDS, 2 с: возврат соединения идёт вне срока блока). Оценка сверху — 2 × (6 + 2) + 5 = 21 с. То же у молчания реплики до тела: 21 с вместо 17, но оба меньшеtimeout server30 с, поэтому цепочка 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 changeotel-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 changeunit-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.