Files
mtusi2026lab2/openspec/changes/bench-postgres/tasks.md
T

15 KiB
Raw Blame History

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). Если план не пишется — остановиться и обсудить с пользователем, а не менять способ молча.

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_*:?};
    • command Postgres с 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 у API DATABASE__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} без портов. После — нет контейнеров, сети и volume mtusi-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/ после прогона удалён.

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.
  • 8.3 Показать git status и git diff --stat, предложить сообщение, после подтверждения закоммитить код стенда (feat: run load bench on PostgreSQL with query plans). Проверка: git status чистый, на этом commit run.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-500k.txt есть.

    Предупреждение о хосте — переснять, а не игнорировать.

  • 10.3 Показать изменения, после подтверждения закоммитить evidence/bench/baseline/ (docs: add PostgreSQL baseline bench evidence).

  • 10.4 REPORT.md:

    • раздел экспериментов: стенд и лимиты трёх контейнеров, профиль, таблица результатов по ячейкам, ссылка на каталог, итог по H1–H4 как получилось;
    • в разделе архитектуры — обоснование индекса истории: запрос, планы первой, средней и последней страницы на 10k / 100k / 500k, сравнение без индекса, ссылки на 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 проходит.