- bench stand is a separate compose project mtusi-bench (API, Postgres, Valkey) with fixed limits, fresh volume per size and migrations - k6 registers with a password, logs in with Basic and sends Bearer - VACUUM (ANALYZE) and CHECKPOINT after prefill - EXPLAIN (ANALYZE, BUFFERS) of the app's history query via auto_explain, plus the same query without the index in a rolled back transaction - Postgres CPU, table and index size in results; storages in passport - bench_compare checks storage limits, images and settings - remove inproc.py and make bench_inproc Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
Tasks
Как строить — design.md (дальше «решение N»), что должно получиться —
дельта specs/load-benchmark/spec.md. Перед первым файлом слоя
прочитать его правило: bench.md, docker.md, run-modes.md.
Замер для отчёта снимается с закоммиченного кода. Коммит — только после
подтверждения пользователя, make bench полной матрицы — только с его
согласия (bench.md, «Измеренное состояние — commit», «Результаты»).
Рабочий стенд (mtusi-lab2) не трогать ни на одном шаге.
1. Проба auto_explain
-
1.1 Проверить решение 5 до остального кода, на временном проекте compose
mtusi-benchс override из задачи 2.1:- Postgres с
shared_preload_libraries=auto_explain, миграции, API; - пара сообщений через HTTP;
- включение
auto_explainчерезALTER SYSTEM+pg_reload_conf(), маркерыRAISE LOG; - один запрос истории уже открытым соединением пула.
Проверка: в
docker logsмежду маркерами есть записьduration: … plan:сQuery Textзапросаmessages,Query ParametersиBuffers. ПослеALTER SYSTEM RESETновых записей нет. Стенд удалён (down -v). Если план не пишется — остановиться и обсудить с пользователем, а не менять способ молча. - Postgres с
2. Стенд на compose
-
2.1
bench/bench.compose.ymlиbench/bench.env(решение 1):- имена
mtusi-bench-*и сетьmtusi-bench; ports: !reset [], уapiиmigrate—volumes: !reset [];- образ
mtusi-messenger:bench; - у api —
healthcheck: disable, у всех —restart: "no"; - лимиты и
AUTH__SESSION_TTL_SECONDSиз${BENCH_*:?}; commandPostgres сauto_explain;- в
bench.envтолько несекретные имена и порты.
Проверка:
docker compose -p mtusi-bench --env-file bench/bench.env -f docker-compose.yml -f bench/bench.compose.yml configс переменнымиBENCH_*и паролями показывает лимиты, отсутствиеportsиconfig.toml, сетьmtusi-bench. БезBENCH_*— ошибка:?. Рабочий.envна вывод не влияет: с--env-fileу APIDATABASE__USER=bench, без флага — значение из рабочего.env(сам.envне правится). - имена
-
2.2
bench/run.py: классStandповерх compose (решения 1, 2):- одна функция вызова с
-p mtusi-bench, обоими-fи собранным окружением: пароли изsecretsна прогон,BENCH_*из новых полейProfile; - на размер:
down -v,up --wait postgres valkey,run --rm migrate,up --no-deps --no-build api, ожидание готовности; check_freeпо контейнерам проекта иmtusi-bench-k6;- предупреждение в вывод и
host_warnings, если сумма лимитов памяти API, Postgres и Valkey больше памяти VM минус 1,5 ГиБ; - уборка в
finallyи по Ctrl+C.
Проверка:
uv run python bench/run.py --profile quick --label quick-stand --sizes 1000проходит размер, предупреждения о VM нет при лимитах 2 + 3 + 0,5 ГБ на VM 7,75 ГиБ. С--memory 6g(отладка) предупреждение есть. Во время прогонаdocker psпоказываетmtusi-bench-{postgres,valkey,api,k6}без портов. После — нет контейнеров, сети и volumemtusi-bench*. Ctrl+C посреди наполнения — то же;make run_dockerна 8080 всё время отвечает, егоStartedAtне меняется. - одна функция вызова с
3. Идентификация в k6
- 3.1
bench/k6/lib.jsиprepare.js(решение 3):authHeaders(token)— Bearer;- регистрация с паролем из
crypto.randomBytes, вход по Basic; - токены в
fixture.json; createChatиsendMessageс токеном.
- 3.2
prefill.js,write.js,read.js,cursors.js,tail.js— токен отправителя или читателя из фикстуры. Проверка задач 3.1–3.2:- короткий прогон проходит все этапы без 401 и
errors; - в access-логе API нет
X-User-Id-запросов; grep -rпо каталогу метки на токены и пароли из.work/(снять до уборки) ничего не находит;.work/после прогона удалён.
- короткий прогон проходит все этапы без 401 и
4. Обслуживание БД и метрики хранилища
- 4.1 Обслуживание после наполнения (решение 4):
VACUUM (ANALYZE)иCHECKPOINTчерезdocker exec … psqlот пользователя контейнера, строка этапа в выводе. Затем размеры таблицы и индексовmessages,count(*),db_bytes_per_messageвmeta.sizesи в сводку. Проверка: в выводе короткого прогона строки этапов идут по порядку наполнение → обслуживание → курсоры. Вmeta.jsonу каждого размера поля объёма заполнены,count(*)= N. - 4.2
db_cpu_coresв концеRUN_FIELDSиPREFILL_FIELDS,dbв строке прогона (решение 6). Проверка: вruns.csvиprefill.csvпрежние столбцы на месте и в том же порядке, новый — последним и заполнен. - 4.3 Сторож Postgres и Valkey: пометка
stand_down, остановка матрицы с именем контейнера (решение 6). Проверка:docker kill mtusi-bench-postgresво время прогона чтения короткого профиля — прогон помечен, команда называет контейнер, код ≠ 0, стенд убран.
5. План запроса истории
- 5.1
bench/k6/explain.js: первая страница, середина и последний курсор пула, проверка 200 и полной страницы. - 5.2 Этап «план» в
run.py(решение 5): маркеры, включение и выключениеauto_explain, разбор журнала, ровно три записиmessagesилиBenchErrorс размером. Затем psql-пара с индексом и без вBEGIN … ROLLBACK, проверка индекса поpg_indexes, файлexplain-<размер>.txt, раздел «Планы запроса истории» вsummary.md. Проверка на коротком прогоне:- у каждого размера есть файл с тремя планами приложения и парой psql;
- сводка показывает узел, буферы и время;
- после этапа
\d messagesв Postgres стенда содержитix_messages_chat_id_created_at_id; - при выключенном вызове
explain.js(временная правка, не коммитить) команда падает с размером и убирает стенд.
6. Паспорт и сравнение меток
-
6.1 Паспорт (решение 7):
stand.postgres: образ, версия, настройки;stand.valkey: образ, версия,maxmemory;limitsпо трём контейнерам;app_envбезPASSWORD;- версии SQLAlchemy, asyncpg и redis.
Проверка: в
meta.jsonкороткого прогона поля заполнены,grep -i passwordпо каталогу метки находит только имена ключей, не значения. -
6.2
bench/compare.py(решение 8): рекурсивная методика, таблица памяти с байтами в БД. Проверка на двух коротких метках:- метка сама с собой — нули во всех ячейках;
- метка с
--memory 1gпротив обычной — отказ с ключомlimits.api.memoryи обоими значениями; - ручная правка
stand.postgres.settings.shared_buffersв копииmeta.json— отказ с этим ключом.
-
6.3
bench/ab.pyбезbench_inproc, проверка занятости — каталог метки стенда. Проверка:uv run python bench/ab.py --before a --after b --reapply HEAD --dry-runна чистом дереве печатает план безbench_inproc. Занятая метка и нечистое дерево — отказ до первого шага.
7. Удаление inproc.py и цели Makefile
- 7.1 Удалить
bench/inproc.py, цельbench_inprocи строкуevidence/profile/quick-*.txtв.gitignore. Обновить комментарии целейbench*вMakefile: заголовок без «трек 1», оценки времени — по факту задачи 8.2. Проверка:grep -rn inprocвнеopenspec/changes/archiveи этого change пуст.make -n bench bench_quick bench_compare bench_abпечатает команды без ошибок.
8. Проверка стенда и коммит кода
- 8.1
make lint. Проверка: без замечаний. - 8.2
make bench_quickцеликом. Проверка:- код 0, все размеры и прогоны без пометок
errors; - в сводке планы на 10k;
- время прогона и скорость наполнения записаны для оценки полной матрицы. Если оценка заметно больше часа — сказать пользователю до baseline.
- код 0, все размеры и прогоны без пометок
- 8.3 Показать
git statusиgit diff --stat, предложить сообщение, после подтверждения закоммитить код стенда (feat: run load bench on PostgreSQL with query plans). Проверка:git statusчистый, на этом commitrun.pyпишетdirty: false.
9. Документация
-
9.1
.claude/rules/bench.md:- раздел «Что доработать под лабу 2» убрать;
- в «Что не меняется между метками» — лимиты и образы Postgres и
Valkey, настройки Postgres образа с
auto_explain, окружение приложения из override, обслуживание после наполнения; - в «Как писать» — граница чёрного ящика для Postgres стенда
(решение 4) вместо исключения
--child; - раздел «Диагностика» удалить;
- таблица инструментов без
inproc.py.
Проверка: правило не упоминает
MemoryStore,X-User-Idиbench_inproc. -
9.2
AGENTS.md:- строки
bench*в таблице команд с оценками времени по факту; - карта кода:
bench.compose.yml,bench.env,explain.js, безinproc.pyиevidence/profile/; - в «Переходном состоянии» убрать пункт
bench/.
Проверка:
grep -n "inproc\|не доработан" AGENTS.mdпуст. - строки
10. Базовый замер и отчёт
-
10.1 Записать гипотезы H1–H4 (решение 10) в раздел экспериментов
REPORT.mdдо запуска полной матрицы. Проверка: раздел есть в diff до появленияevidence/bench/baseline/. -
10.2 Подготовить хост (питание, swap,
memory_pressure, нет посторонних контейнеров) и с согласия пользователя запуститьmake bench BENCH_LABEL=baseline. Проверка:- код 0,
status: complete, 54 прогона; - в паспорте
dirty: false, безhost_warnings; - файлы
explain-10k.txt,explain-100k.txt,explain-1M.txtесть.
Предупреждение о хосте — переснять, а не игнорировать.
- код 0,
-
10.3 Показать изменения, после подтверждения закоммитить
evidence/bench/baseline/(docs: add PostgreSQL baseline bench evidence). -
10.4
REPORT.md:- раздел экспериментов: стенд и лимиты трёх контейнеров, профиль, таблица результатов по ячейкам, ссылка на каталог, итог по H1–H4 как получилось;
- в разделе архитектуры — обоснование индекса истории: запрос,
планы первой, средней и последней страницы на 10k / 100k / 1M,
сравнение без индекса, ссылки на
explain-*.txt; - строка уровня 4 «индекс истории и EXPLAIN» в таблице доказательств вместо TODO;
- ограничения: один большой чат, настройки Postgres по умолчанию, generic и custom plan, Docker Desktop;
- убрать «EXPLAIN — следующий change» из «Ограничений» и
«Переходного состояния»
AGENTS.md.
Проверка: каждое число в тексте есть в
summary.md,runs.csvилиexplain-*.txtметкиbaseline. Commit метки указан. -
10.5 Показать изменения, после подтверждения закоммитить отчёт и документацию (
docs: report PostgreSQL baseline and history index plans).graphify update .. Проверка:git statusчистый,openspec validate bench-postgres --strictпроходит.