From e76eed789f1370b69cd2da27ecd67c21f719ed9a Mon Sep 17 00:00:00 2001 From: roman Date: Fri, 2 Oct 2026 01:21:15 +0300 Subject: [PATCH] feat: run load bench on PostgreSQL with query plans - 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 --- .claude/rules/bench.md | 142 +-- .gitignore | 3 +- AGENTS.md | 27 +- Makefile | 21 +- bench/ab.py | 28 +- bench/bench.compose.yml | 52 + bench/bench.env | 11 + bench/compare.py | 54 +- bench/inproc.py | 845 ---------------- bench/k6/cursors.js | 4 +- bench/k6/explain.js | 49 + bench/k6/lib.js | 37 +- bench/k6/prefill.js | 6 +- bench/k6/prepare.js | 23 +- bench/k6/read.js | 2 +- bench/k6/tail.js | 2 +- bench/k6/write.js | 6 +- bench/run.py | 905 ++++++++++++++++-- .../changes/bench-postgres/.openspec.yaml | 2 + openspec/changes/bench-postgres/design.md | 439 +++++++++ openspec/changes/bench-postgres/proposal.md | 109 +++ .../specs/load-benchmark/spec.md | 539 +++++++++++ openspec/changes/bench-postgres/tasks.md | 221 +++++ 23 files changed, 2443 insertions(+), 1084 deletions(-) create mode 100644 bench/bench.compose.yml create mode 100644 bench/bench.env delete mode 100644 bench/inproc.py create mode 100644 bench/k6/explain.js create mode 100644 openspec/changes/bench-postgres/.openspec.yaml create mode 100644 openspec/changes/bench-postgres/design.md create mode 100644 openspec/changes/bench-postgres/proposal.md create mode 100644 openspec/changes/bench-postgres/specs/load-benchmark/spec.md create mode 100644 openspec/changes/bench-postgres/tasks.md diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index fbbdf236..ca013a69 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -5,58 +5,68 @@ paths: # Нагрузочный стенд (`bench/`) -Стенд перенесён из лабы 1, где он обслуживал трек 1 «5» (нагрузка на -in-memory API): матрица размеров истории и уровней конкуренции для -чтения и записи, метрики и сырые данные в `evidence/bench/<метка>/`. -Что стенд обязан делать — спек `load-benchmark`, почему так — archived -changes `load-bench-harness` (стенд) и `perf-bottleneck-fix` -(диагностика и сравнение меток) в `openspec/changes/archive/`. +Стенд перенесён из лабы 1 (трек 1 «5», нагрузка на in-memory API) и на +лабе 2 переведён на PostgreSQL: матрица размеров истории и уровней +конкуренции для чтения и записи, метрики, планы запроса истории и сырые +данные в `evidence/bench/<метка>/`. Что стенд обязан делать — спек +`load-benchmark`, почему так — archived changes `load-bench-harness` +(стенд), `perf-bottleneck-fix` (сравнение меток) и `bench-postgres` +(стенд на PostgreSQL, план запроса) в `openspec/changes/archive/`. Результаты и выводы — `REPORT.md`, раздел «Эксперименты и отказы». -На лабе 2 стенд нужен для двух вещей: наполнить ≥10 000 сообщений под -`EXPLAIN (ANALYZE, BUFFERS)` (уровень 4) и снять «до» и «после» для -выбранного трека «5» (`README.md`). Метки лабы 1 сюда не переносились: -другое хранилище — другая методика, сравнивать их с лабой 2 нельзя. +На лабе 2 стенд нужен для двух вещей: план запроса истории +`EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях (уровень 4) и «до» и +«после» для трека «5» №2 (`README.md`). Метки лабы 1 сюда не +переносились: другое хранилище — другая методика, сравнивать их с +лабой 2 нельзя. -## Что доработать под лабу 2 +Стенд — свой проект compose `mtusi-bench`: тот же `docker-compose.yml` +с override `bench/bench.compose.yml` (по образцу `make failure_checks`), +подстановки — `bench/bench.env`, а не `.env` рабочего стенда. Пароли +хранилищ `run.py` генерирует на прогон и никуда не пишет. Каждый размер — +свежий стенд: `down -v`, Postgres и Valkey, миграции, API. -Пока это не сделано, `make bench*` на коде лабы 2 не запускать. - -- `run.py` поднимает только контейнер API. Нужны Postgres с тем же - пином, что в compose, своими лимитами и volume стенда, а до - наполнения — миграции. -- `k6/lib.js` шлёт `X-User-Id`. Нужны регистрация с паролем, вход по - Basic и Bearer, как в `Actor.headers()` `student-tests/`. -- `inproc.py` собирает приложение над `MemoryStore`. На Postgres время - запроса уходит в основном в БД; переписать или убрать инструмент — - решает design change. -- В «Что не меняется между метками» добавляются параметры Postgres: - лимиты CPU и памяти, конфигурация, прогрев кэша перед замером. - -В `bench/` четыре инструмента: +В `bench/` три инструмента: | Файл | Команда | Что делает | |---|---|---| -| `run.py`, `k6/` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки и память | -| `inproc.py` | `make bench_inproc` | диагностика: куда уходит время одного запроса внутри приложения | +| `run.py`, `k6/`, `bench.compose.yml`, `bench.env` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки, CPU API и Postgres, память, снимает планы запроса истории | | `compare.py` | `make bench_compare` | дельта двух меток стенда, эффект или шум | -| `ab.py` | `make bench_ab` | стенд и диагностика «до» и «после» одного изменения подряд, в одной сессии хоста | +| `ab.py` | `make bench_ab` | стенд «до» и «после» одного изменения подряд, в одной сессии хоста | ## Что не меняется между метками Метки сравнимы, только если различается код приложения и больше ничего. Не меняются: -- **лимиты контейнера приложения:** `--cpus=1 --memory=2g - --memory-swap=2g`, `--no-healthcheck`, без `.env` и `config.toml`, - порты на хост не публикуются; +- **лимиты контейнеров без swap:** API — 1 CPU / 2 ГБ, PostgreSQL — + 4 CPU / 3 ГБ, Valkey — 2 CPU / 512 МБ (поля `Profile`, в compose — + переменными `BENCH_*`). Healthcheck API выключен, `restart: "no"`, + порты на хост не публикуются. Сумма лимитов памяти должна + помещаться в VM docker с запасом 1,5 ГиБ, иначе — предупреждение о + хосте; +- **хранилища:** образы PostgreSQL и Valkey — те же пины, что у рабочего + стенда (из `docker-compose.yml`). Valkey — тот же `valkey.conf`. + PostgreSQL — настройки образа плюс `shared_preload_libraries = + auto_explain`, выключенный вне этапа плана. Настройки, от которых + зависят план и запись, пишутся в паспорт (`stand.postgres.settings`); +- **приложение:** настройки по умолчанию из `settings.py` и окружение + из override (`AUTH__SESSION_TTL_SECONDS` из `Profile`), без `.env` и + `config.toml`. Окружение без паролей — в паспорте (`stand.app_env`); +- **обслуживание после наполнения:** `VACUUM (ANALYZE)` и `CHECKPOINT` + до сбора курсоров и прогонов. Затем этап плана, затем прогоны с + прогревом перед каждым; - **генератор:** `grafana/k6` той же версии и digest, в той же docker-сети, без лимита CPU; - **профиль `full`:** размеры, конкуренция, повторы, прогрев и длительности, длина текста, порция наполнения, зерно выбора курсоров - и сдвиг зерна для прогрева, порог пометки `generator`. Все они — поля - `Profile` в `run.py` и целиком пишутся в `meta.json`: новый параметр - методики заводится там же, а не константой в коде. + и сдвиг зерна для прогрева, порог пометки `generator`, лимиты и срок + сессии стенда. Все они — поля `Profile` в `run.py` и целиком пишутся в + `meta.json`: новый параметр методики заводится там же, а не константой + в коде. + +`make bench_compare` проверяет совпадение всего этого по паспортам +(лимиты, образы, настройки PostgreSQL, окружение приложения, профиль). Изменить что-то из списка — значит сменить методику: старые метки перестают быть «до», базовый замер переснимается, а в `REPORT.md` @@ -65,43 +75,42 @@ changes `load-bench-harness` (стенд) и `perf-bottleneck-fix` ## Как писать - Стенд — чёрный ящик: `run.py`, `k6/` и `compare.py` не импортируют - `src` и не ходят в приложение мимо HTTP. Все запросы делает k6 внутри - сети стенда, оркестратор управляет только docker CLI. Единственное - исключение — режим `--child` в `inproc.py`: он работает внутри - контейнера и импортирует приложение, потому что разложить время - внутри процесса снаружи нельзя. На хосте `inproc.py` тоже только - управляет docker. + `src` и не ходят в приложение мимо HTTP. Все запросы к API делает k6 + внутри сети стенда, оркестратор управляет только docker CLI. +- Исключение — PostgreSQL стенда: оркестратор обращается к нему + напрямую (`docker exec … psql` от пользователя контейнера, SQL через + stdin, `docker logs`), но только для обслуживания и измерения: + - `VACUUM (ANALYZE)` и `CHECKPOINT`; + - размеры таблиц; + - включение и выключение `auto_explain` между маркерами; + - журнал Postgres с планами; + - план без индекса в транзакции, которая откатывается. + + Данных, видимых приложению, он не меняет, а между прогонами нагрузки + нет. +- Из журнала Postgres в результаты идут только планы запроса истории + (`messages`). Между маркерами журнал содержит и проверку сессии с + SHA-256 токена в параметрах: она отбрасывается и не пишется никуда. +- Все вызовы `docker compose` — только с `-p mtusi-bench`, обоими `-f` и + `--env-file bench/bench.env`, с окружением, собранным `run.py`: + без `-p` `down -v` удалил бы чужой volume, без `--env-file` compose + прочитал бы рабочий `.env`. - Скрипты `bench/` на хосте — только stdlib Python, запуск `uv run python bench/<файл>.py`. Новых зависимостей не добавлять. - Сценарии k6 — JavaScript без Node.js: только встроенные модули k6. Заголовок идентификации собирается в одном месте `lib.js`: Bearer, - как `Actor.headers()` в `student-tests/`. + как `Actor.headers()` в `student-tests/`. Пароли пользователей стенда + живут только в памяти `prepare.js`, токены — в `.work/fixture.json`, + который удаляется в конце прогона; в каталог метки не попадает ни то, + ни другое. - Имена контейнеров и сети — `mtusi-bench-*`. Чужие контейнеры (`make run_docker`, другие проекты) стенд не трогает и не - останавливает. Уборка своих — в `finally` и по Ctrl+C. + останавливает. Уборка своих — в `finally` и по Ctrl+C. Остатки + прерванного прогона `run.py` не удаляет сам: он отказывается + стартовать и печатает команды уборки. - Случайность только через свой генератор с зерном из профиля (`seed + номер VU`), не `Math.random`. -## Диагностика: `make bench_inproc` - -- Она объясняет, а не меряет. Её числа не попадают в таблицы - результатов стенда и не выдаются за пропускную способность: в - `REPORT.md` они идут как «куда уходит время запроса», рядом с путём к - файлу в `evidence/profile/`. -- Процесс запускается в образе стенда с тем же `--cpus=1`, отсоединённо - (`docker run -d`), как контейнер стенда. С подключённым клиентом - docker и на хосте цена логов другая: запись в stdout контейнера стоит - процессу десятки микросекунд на запрос. -- Время запроса гуляет от запуска процесса к запуску на 1–3%. Поэтому - каждый режим логов запускается несколько раз, а варианты одного шага - (текущий форматтер против эталонного) сравниваются внутри одного - процесса. -- Варианты кода для сравнения живут в самом скрипте (подклассы моделей - ответа), а не в `src`. Если для пробы всё же меняется `src` — правило - следующего раздела. -- Сверка формата времени с эталоном — часть команды: правка - `src/utils/utc.py` проверяется ею, а не на глаз. - ## Измеренное состояние — commit Замер или тест, результат которого идёт в отчёт, снимается с @@ -143,9 +152,12 @@ changes `load-bench-harness` (стенд) и `perf-bottleneck-fix` - Каталог метки не перезаписывается. `evidence/bench/quick-*` — в `.gitignore`: короткий прогон проверяет стенд, а не даёт результат. -- `evidence/profile/<метка>.txt` тоже не перезаписывается; пробные - метки `quick-*` — в `.gitignore`. `evidence/compare/<до>__<после>.md` - выводится из неизменяемых каталогов меток и может пересоздаваться. +- `evidence/compare/<до>__<после>.md` выводится из неизменяемых + каталогов меток и может пересоздаваться; сравнения пробных меток + `quick-*` — в `.gitignore`. +- Планы запроса истории — `explain-<размер>.txt` в каталоге метки, как + есть из журнала Postgres и psql. В отчёт числа плана переносятся из + этих файлов или из раздела планов `summary.md`, не пересчитываются. - Столбцы `runs.csv` и `prefill.csv` не переименовываются и не удаляются: по ним сравниваются метки. Новая метрика — новый столбец в конце. diff --git a/.gitignore b/.gitignore index 8a0656a8..bb7066ca 100644 --- a/.gitignore +++ b/.gitignore @@ -32,8 +32,7 @@ coverage/ graphify-out/ # make bench_quick: самопроверка стенда, не результат evidence/bench/quick-*/ -# пробные запуски bench_inproc и сравнения пробных меток -evidence/profile/quick-*.txt +# сравнения пробных меток evidence/compare/*quick-* # Keep small, sanitized evidence summaries in evidence/ under version control. # Inspect git diff --cached: ignore rules are not a secret scanner. diff --git a/AGENTS.md b/AGENTS.md index f6e882ef..322be788 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,13 +82,11 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey). Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change `session-auth`, кэш Valkey — change `membership-cache`, автоматические -проверки отказов — change `failure-checks`. Этот файл и +проверки отказов — change `failure-checks`, нагрузочный стенд на +PostgreSQL с планами запроса — change `bench-postgres`. Этот файл и `.claude/rules/` описывают целевое состояние лабы 2, поэтому в остальном код с ними пока расходится: -- `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с - `X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` — - change `bench-postgres` (`bench.md`); - в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления базы: иначе в кэше останутся карточки чатов, созданных после снятия backup (design change `membership-cache`, Risks); @@ -159,7 +157,7 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan | `run-modes.md` | точки входа, `Makefile`, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM | | `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`: мультистейдж, non-root, пины, healthcheck, стенд compose, volumes, restart hook | | `student-tests.md` | `student-tests/**`: обязательные проверки уровня 4, black-box по HTTP, особый стенд | - | `bench.md` | `bench/**`: нагрузочный стенд из лабы 1 и его доработка под Postgres, что не меняется между метками замеров, диагностика и сравнение меток, коммиты измеренных состояний | + | `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний | | `migrations.md` | `migrations/**`, `alembic.ini`, `src/infra/db/models/**`: схема до запросов, ограничения, индексы, повторный запуск миграций | - **`openspec/`** (схема `spec-driven`, язык артефактов — русский, см. @@ -252,10 +250,9 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan | `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) | | `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); сервер недоступен — код 2 и одна строка с адресом | | `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) | -| `make bench [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) | -| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт | -| `make bench_inproc [BENCH_LABEL=...]` | куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в `evidence/profile/<метка>.txt`, занятая метка — отказ. Объясняет, но не меряет пропускную способность | -| `make bench_ab BEFORE=... AFTER=... REAPPLY=` | «до» и «после» одного изменения подряд (~40 мин): `bench` и `bench_inproc` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, то же для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита | +| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 1M (~45 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда); на каждый размер — свежий стенд, `VACUUM (ANALYZE)` и планы запроса истории (`auto_explain`). Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) | +| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k (~2,5 мин), метка `quick-<время>`, в git не идёт | +| `make bench_ab BEFORE=... AFTER=... REAPPLY=` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита | | `make bench_compare BEFORE=... AFTER=... [AA=...]` | дельта двух меток `make bench` по ячейкам матрицы; метки с разной методикой не сравнивает; с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` | Разовая подмена внешнего порта — аргументом make: @@ -314,10 +311,11 @@ student-tests/ # black-box тесты по HTTP (уровень 4) run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, уборка (stdlib) fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггер сбоя участников (stdlib) failures.compose.yml # override стенда отказов: без публикации портов -bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick - run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json - k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы - inproc.py # make bench_inproc: разложение времени запроса внутри процесса, сверка формата времени +bench/ # нагрузочный стенд на API + Postgres + Valkey: make bench / make bench_quick + run.py # оркестратор: стенд compose, матрица, обслуживание БД, планы, метрики, runs.csv / summary.md / meta.json + bench.compose.yml # override стенда mtusi-bench: имена, лимиты BENCH_*, без портов и config.toml, auto_explain + bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей) + k6/ # сценарии k6: prepare (вход по Basic), prefill, cursors, explain, read, tail, write; lib.js — Bearer и хелперы compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose @@ -333,8 +331,7 @@ evidence/migrations/ # миграции с нуля и повторно, evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт evidence/tests/ # выводы make test_isolated, make student_test и make failure_checks для REPORT.md -evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6 -evidence/profile/<метка>.txt # результаты make bench_inproc +evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, планы explain-<размер>.txt, сырые итоги k6 evidence/compare/ # таблицы make bench_compare: <до>__<после>.md KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы ``` diff --git a/Makefile b/Makefile index 354956bc..1ab54256 100644 --- a/Makefile +++ b/Makefile @@ -134,29 +134,24 @@ stop_cache: # ------------------------- -# Load benchmark (трек 1) +# Load benchmark # ------------------------- BENCH_LABEL ?= baseline -# полная матрица, ~18 мин; метка не должна существовать; результаты — -# evidence/bench/$(BENCH_LABEL)/, ход — строки в терминале и progress.json +# полная матрица на своём проекте compose mtusi-bench (API, PostgreSQL, +# Valkey, без портов хоста), ~45 мин; метка не должна существовать; +# результаты и планы запроса истории — evidence/bench/$(BENCH_LABEL)/, +# ход — строки в терминале и progress.json .PHONY: bench bench: uv run python bench/run.py --profile full --label $(BENCH_LABEL) -# самопроверка стенда на малых размерах, ~1,5 мин; результат в git не идёт +# самопроверка стенда на малых размерах, ~2,5 мин; результат в git не идёт .PHONY: bench_quick bench_quick: uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ) -# разложение времени запроса внутри процесса в образе стенда, ~2 мин: -# объясняет, куда уходит CPU, но не меряет; результат — -# evidence/profile/$(BENCH_LABEL).txt, метки quick-* в git не идут -.PHONY: bench_inproc -bench_inproc: - uv run python bench/inproc.py --label $(BENCH_LABEL) - # дельта двух меток по ячейкам матрицы: BEFORE и AFTER обязательны, AA — # метка того же кода, что BEFORE, для уровня шума; результат — # evidence/compare/$(BEFORE)__$(AFTER).md @@ -164,9 +159,9 @@ bench_inproc: bench_compare: uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" --aa "$(AA)" -# «до» и «после» подряд в одной сессии, ~40 мин: bench и bench_inproc для +# «до» и «после» подряд в одной сессии, два прогона bench: bench для # BEFORE, commit доказательств, git revert commit REAPPLY (возврат -# откаченного изменения), затем то же для AFTER. Сам делает два коммита; +# откаченного изменения), затем bench для AFTER. Сам делает два коммита; # рабочее дерево должно быть чистым .PHONY: bench_ab bench_ab: diff --git a/bench/ab.py b/bench/ab.py index 3c0fac7a..250e1f41 100644 --- a/bench/ab.py +++ b/bench/ab.py @@ -3,10 +3,11 @@ Запуск — `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=`. В рабочем дереве должен лежать код «до», а изменение — быть закоммиченным и откаченным отдельным commit; `REAPPLY` — commit отката. -Скрипт снимает стенд и разложение «до», коммитит их, возвращает -изменение (`git revert` commit отката) и снимает «после». Между -прогонами на хосте нет другой работы. Только stdlib. Методика — design -change `perf-bottleneck-fix`, решения 7 и 9. +Скрипт снимает стенд «до», коммитит его результаты, возвращает изменение +(`git revert` commit отката) и снимает «после». Между прогонами на хосте +нет другой работы. Только stdlib. Методика — design change +`perf-bottleneck-fix`, решения 7 и 9; без разложения внутри процесса — +design change `bench-postgres`, решение 8. """ import argparse @@ -35,12 +36,9 @@ def problems(args: argparse.Namespace) -> list[str]: if not re.fullmatch(r"[A-Za-z0-9._-]+", name or ""): found.append(f"bad label {name!r}: use [A-Za-z0-9._-]") continue - for path in ( - ROOT / "evidence" / "bench" / name, - ROOT / "evidence" / "profile" / f"{name}.txt", - ): - if path.exists(): - found.append(f"{path.relative_to(ROOT)} already exists") + path = ROOT / "evidence" / "bench" / name + if path.exists(): + found.append(f"{path.relative_to(ROOT)} already exists") if args.before == args.after: found.append("BEFORE and AFTER must be different labels") if git("status", "--porcelain").stdout.strip(): @@ -54,20 +52,12 @@ def problems(args: argparse.Namespace) -> list[str]: def steps(args: argparse.Namespace) -> list[list[str]]: - # стенд идёт раньше разложения: его dirty считается по всему дереву return [ ["make", "bench", f"BENCH_LABEL={args.before}"], - ["make", "bench_inproc", f"BENCH_LABEL={args.before}"], - [ - "git", - "add", - f"evidence/bench/{args.before}", - f"evidence/profile/{args.before}.txt", - ], + ["git", "add", f"evidence/bench/{args.before}"], ["git", "commit", "-m", f"docs: add {args.before} bench evidence"], ["git", "revert", "--no-edit", args.reapply], ["make", "bench", f"BENCH_LABEL={args.after}"], - ["make", "bench_inproc", f"BENCH_LABEL={args.after}"], ] diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml new file mode 100644 index 00000000..4bdcd9b3 --- /dev/null +++ b/bench/bench.compose.yml @@ -0,0 +1,52 @@ +# Override стенда make bench (bench/run.py): тот же docker-compose.yml под +# проектом mtusi-bench, со своими volume, сетью и лимитами. Пины, healthcheck +# хранилищ, valkey.conf и миграции — из основного файла. Подстановки — из +# bench/bench.env, а не из .env рабочего стенда; пароли и BENCH_* передаёт +# run.py (поля Profile), без них стенд не поднимается. Решения 1, 2, 5 design +# change bench-postgres; что не меняется между метками — .claude/rules/bench.md. +services: + postgres: + container_name: mtusi-bench-postgres + # упавший контейнер не поднимается сам: прогон помечается stand_down + restart: "no" + # auto_explain загружен, но выключен (log_min_duration = -1): run.py + # включает его только на этапе плана, между прогонами + command: ["postgres", "-c", "shared_preload_libraries=auto_explain"] + ports: !reset [] + cpus: ${BENCH_DB_CPUS:?run make bench} + mem_limit: ${BENCH_DB_MEMORY:?run make bench} + memswap_limit: ${BENCH_DB_MEMORY:?run make bench} + + valkey: + container_name: mtusi-bench-valkey + restart: "no" + ports: !reset [] + cpus: ${BENCH_CACHE_CPUS:?run make bench} + mem_limit: ${BENCH_CACHE_MEMORY:?run make bench} + memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench} + + migrate: + image: mtusi-messenger:bench + # без config.toml рабочего стенда: настройки — окружение и дефолты + volumes: !reset [] + + api: + container_name: mtusi-bench-api + image: mtusi-messenger:bench + restart: "no" + ports: !reset [] + volumes: !reset [] + # проверка раз в несколько секунд — лишний CPU внутри лимита API + healthcheck: + disable: true + environment: + # размер 1M идёт дольше часа по умолчанию: сессия не должна истечь + AUTH__SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL_SECONDS:?run make bench} + cpus: ${BENCH_APP_CPUS:?run make bench} + mem_limit: ${BENCH_APP_MEMORY:?run make bench} + memswap_limit: ${BENCH_APP_MEMORY:?run make bench} + +networks: + default: + # k6 подключается к сети стенда по имени (docker run --network) + name: mtusi-bench diff --git a/bench/bench.env b/bench/bench.env new file mode 100644 index 00000000..8653f27f --- /dev/null +++ b/bench/bench.env @@ -0,0 +1,11 @@ +# Подстановки compose для стенда make bench вместо .env рабочего стенда +# (docker compose --env-file bench/bench.env). Только несекретные имена и +# порты внутри сети стенда: пароли генерирует bench/run.py на каждый +# прогон, лимиты и срок сессии приходят из Profile (BENCH_*). +POSTGRES_USER=bench +POSTGRES_DB=bench +POSTGRES_HOST=postgres +POSTGRES_PORT=5432 +VALKEY_HOST=valkey +VALKEY_PORT=6379 +APP__PORT=8080 diff --git a/bench/compare.py b/bench/compare.py index de076f57..3b37bce6 100644 --- a/bench/compare.py +++ b/bench/compare.py @@ -3,8 +3,9 @@ Запуск — `make bench_compare BEFORE=<метка> AFTER=<метка> [AA=<метка>]`. Читает `runs.csv` и `meta.json` из `evidence/bench/<метка>/`, пишет `evidence/compare/<до>__<после>.md`. Только stdlib, docker и приложение -не нужны. Метки с разной методикой не сравниваются. Правило «эффект или -шум» — design change `perf-bottleneck-fix`, решение 7. +не нужны. Метки с разной методикой не сравниваются (с лабы 2 методика +включает и хранилища: design change `bench-postgres`, решение 8). Правило +«эффект или шум» — design change `perf-bottleneck-fix`, решение 7. """ import argparse @@ -93,15 +94,40 @@ def load(name: str) -> Label: return Label(name=name, meta=meta, runs=runs) +def flatten(prefix: str, value: Any, into: dict[str, Any]) -> None: + """Вложенные словари паспорта → плоские ключи `a.b.c`.""" + if isinstance(value, dict): + for key, inner in value.items(): + flatten(f"{prefix}.{key}", inner, into) + else: + into[prefix] = value + + def methodology(label: Label) -> dict[str, Any]: - """Параметры, которые у сравнимых меток обязаны совпадать.""" + """Параметры, которые у сравнимых меток обязаны совпадать. + + Профиль, лимиты всех контейнеров стенда, образ генератора, образы и + настройки PostgreSQL и Valkey, окружение приложения (решение 8 design + change `bench-postgres`). + """ + meta = label.meta + stand = meta.get("stand", {}) flat: dict[str, Any] = {} - for section in ("profile", "limits"): - for key, value in label.meta.get(section, {}).items(): - flat[f"{section}.{key}"] = value - image = label.meta.get("generator", {}).get("image") - if image is not None: - flat["generator.image"] = image + flatten("profile", meta.get("profile", {}), flat) + flatten("limits", meta.get("limits", {}), flat) + for name, value in ( + ("generator.image", meta.get("generator", {}).get("image")), + ("stand.postgres.image", stand.get("postgres", {}).get("image")), + ("stand.valkey.image", stand.get("valkey", {}).get("image")), + ): + if value is not None: + flat[name] = value + flatten( + "stand.postgres.settings", + stand.get("postgres", {}).get("settings", {}), + flat, + ) + flatten("stand.app_env", stand.get("app_env", {}), flat) return flat @@ -284,16 +310,18 @@ def memory_table(before: Label, after: Label) -> list[str]: first, second = sizes(before), sizes(after) lines = [ - "| Размер | Байт на сообщение до | после | " - "RSS после наполнения до, МиБ | после |", - "|---|---|---|---|---|", + "| Размер | Байт RSS на сообщение до | после | " + "RSS после наполнения до, МиБ | после | " + "Байт в БД на сообщение до | после |", + "|---|---|---|---|---|---|---|", ] for size in sorted(first.keys() & second.keys()): a, b = first[size], second[size] lines.append( f"| {human(size)} | {a.get('bytes_per_message')} | " f"{b.get('bytes_per_message')} | {a.get('rss_after_mib')} | " - f"{b.get('rss_after_mib')} |", + f"{b.get('rss_after_mib')} | {a.get('db_bytes_per_message')} | " + f"{b.get('db_bytes_per_message')} |", ) return lines diff --git a/bench/inproc.py b/bench/inproc.py deleted file mode 100644 index ea63d56e..00000000 --- a/bench/inproc.py +++ /dev/null @@ -1,845 +0,0 @@ -"""Разложение стоимости запроса внутри процесса: диагностика трека 1. - -Запуск — `make bench_inproc BENCH_LABEL=<метка>`. На хосте скрипт собирает -образ стенда, запускает себя в контейнере и пишет -`evidence/profile/<метка>.txt`; здесь только stdlib. В контейнере -(`--child`) он импортирует приложение и вызывает его как ASGI, без -uvicorn и сети. Числа объясняют, куда уходит время запроса; пропускную -способность и задержки меряет только `make bench`. Методика — design -change `perf-bottleneck-fix`, граница — `.claude/rules/bench.md`. -""" - -import argparse -import asyncio -import cProfile -import functools -import importlib.metadata -import json -import os -import platform -import pstats -import random -import re -import statistics -import subprocess -import sys -import time -from collections.abc import Awaitable, Callable -from datetime import UTC, datetime, timedelta, timezone -from pathlib import Path -from typing import Annotated, Any -from uuid import UUID - -ROOT = Path(__file__).resolve().parents[1] -SCRIPT = Path(__file__).resolve() -APP_IMAGE = "mtusi-messenger:bench" -CONTAINER = "mtusi-bench-inproc" -RESULT_MARK = "INPROC_RESULT " -# незакоммиченные изменения считаются только по тому, что попадает в замер -APP_FILES = ( - "src", - "Dockerfile", - "pyproject.toml", - "uv.lock", - ".dockerignore", - ".python-version", - "bench/inproc.py", -) - -# эталон формата времени: запись, которой оно сериализовалось до правки. -# Литерал, а не константа из src: расхождение с кодом должно быть видно -REFERENCE_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ" -RFC3339_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z") - -SEED = 20260930 -SIZE = 20_000 -TEXT_LENGTH = 64 -PAGE_LIMIT = 50 -CURSOR_POOL = 300 -# запусков процесса на каждый режим: от запуска к запуску время запроса -# гуляет на 1–3%, внутри запуска — меньше -LAUNCHES = 3 -# режим логов: уровень и флаги процесса. INFO — как на стенде; INFO_NULL — -# записи собираются, но stdout процесса смотрит в /dev/null -MODES: dict[str, tuple[str, list[str]]] = { - "INFO": ("INFO", []), - "INFO_NULL": ("INFO", ["--null-stdout"]), - "WARNING": ("WARNING", []), -} -REPEATS = 5 -REQUESTS = 3000 -PART_ROUNDS = 2000 -VALUE_ROUNDS = 100_000 -PROFILE_REQUESTS = 2000 -PROFILE_TOP = 15 -FORMAT_SAMPLES = 20_000 -TIME_NAMES = ("to_rfc3339", "strftime", "isoformat", "astimezone") - - -class InprocError(Exception): - """Диагностика не может продолжать: сообщение для человека.""" - - -def spread(values: list[float]) -> dict[str, float]: - return { - "median": round(statistics.median(values), 3), - "min": round(min(values), 3), - "max": round(max(values), 3), - } - - -# ------------------------------------------------------------- в контейнере - - -def reference_rfc3339(value: datetime, fmt: str) -> str: - return value.astimezone(UTC).strftime(fmt) - - -def format_values() -> list[datetime]: - """Случайные значения 1970–2100 и граничные случаи формата.""" - rng = random.Random(SEED) - start = datetime(1970, 1, 1, tzinfo=UTC) - span = int((datetime(2100, 1, 1, tzinfo=UTC) - start).total_seconds()) - values = [ - start - + timedelta( - seconds=rng.randrange(span), - microseconds=rng.randrange(1_000_000), - ) - for _ in range(FORMAT_SAMPLES) - ] - moment = datetime(2026, 9, 30, 12, 0, 0, tzinfo=UTC) - values += [moment.replace(microsecond=m) for m in (0, 1, 999_999)] - values += [ - start, - datetime(2026, 12, 31, 23, 59, 59, 999_999, tzinfo=UTC), - datetime(2028, 2, 29, 0, 0, 0, tzinfo=UTC), - ] - # другой часовой пояс: после приведения к UTC меняются день и год - for hours in (3, -8): - zone = timezone(timedelta(hours=hours)) - values += [ - datetime(2026, 12, 31, 23, 30, 0, 0, tzinfo=zone), - datetime(2027, 1, 1, 1, 30, 0, 123, tzinfo=zone), - ] - return values - - -def check_format( - to_text: Callable[[datetime], str], - from_text: Callable[[str], datetime], - fmt: str, -) -> dict[str, Any]: - """Текущий форматтер против эталона; первое расхождение — в ответ.""" - values = format_values() - for value in values: - expected = reference_rfc3339(value, fmt) - got = to_text(value) - problem = None - if got != expected: - problem = "differs from reference" - elif not RFC3339_RE.fullmatch(got): - problem = "not YYYY-MM-DDTHH:MM:SS.ffffffZ" - elif from_text(got) != value: - problem = "does not parse back to the same instant" - if problem: - return { - "checked": len(values), - "mismatch": { - "problem": problem, - "value": value.isoformat(), - "expected": expected, - "got": got, - }, - } - return {"checked": len(values), "mismatch": None} - - -class Probe: - """Прямые ASGI-вызовы приложения.""" - - def __init__(self, app: Any) -> None: - self.app = app - - @staticmethod - def headers( - user: str | None, - body: bytes = b"", - ) -> list[tuple[bytes, bytes]]: - result = [(b"host", b"inproc")] - if body: - result.append((b"content-type", b"application/json")) - result.append((b"content-length", str(len(body)).encode())) - if user: - result.append((b"x-user-id", user.encode())) - return result - - async def request( - self, - method: str, - path: str, - headers: list[tuple[bytes, bytes]], - *, - query: bytes = b"", - body: bytes = b"", - ) -> tuple[int, bytes]: - scope = { - "type": "http", - "asgi": {"version": "3.0"}, - "http_version": "1.1", - "method": method, - "scheme": "http", - "path": path, - "raw_path": path.encode(), - "query_string": query, - "root_path": "", - "headers": headers, - "client": ("127.0.0.1", 1), - "server": ("127.0.0.1", 8080), - } - messages: list[dict[str, Any]] = [] - - async def receive() -> dict[str, Any]: - return {"type": "http.request", "body": body, "more_body": False} - - async def send(message: dict[str, Any]) -> None: - messages.append(message) - - await self.app(scope, receive, send) - return ( - messages[0]["status"], - b"".join(m.get("body", b"") for m in messages[1:]), - ) - - async def create( - self, - path: str, - payload: dict[str, Any], - user: str | None = None, - ) -> dict[str, Any]: - body = json.dumps(payload).encode() - status, raw = await self.request( - "POST", - path, - self.headers(user, body), - body=body, - ) - if status != 201: - raise InprocError(f"POST {path}: {status} {raw[:200]!r}") - return json.loads(raw) - - -async def repeat( - fn: Callable[[], Awaitable[None]], - count: int, -) -> dict[str, Any]: - """Прогрев и REPEATS повторов; время и CPU процесса на один запрос.""" - await fn() - walls, cpus = [], [] - for _ in range(REPEATS): - wall, cpu = time.perf_counter(), time.process_time() - await fn() - walls.append((time.perf_counter() - wall) / count * 1e6) - cpus.append((time.process_time() - cpu) / count * 1e6) - return {"wall_us": spread(walls), "cpu_us": spread(cpus)} - - -def repeat_sync(fn: Callable[[], Any], count: int) -> dict[str, float]: - for _ in range(count): - fn() - walls = [] - for _ in range(REPEATS): - wall = time.perf_counter() - for _ in range(count): - fn() - walls.append((time.perf_counter() - wall) / count * 1e6) - return spread(walls) - - -def function_label(file: str, line: int, name: str) -> str: - if file == "~": - return name - if "site-packages/" in file: - short = file.split("site-packages/", 1)[1] - elif file.startswith(os.getcwd() + "/"): - short = file[len(os.getcwd()) + 1 :] - else: - short = "/".join(file.split("/")[-2:]) - return f"{short}:{line}({name})" - - -async def profile( - fn: Callable[[], Awaitable[None]], - count: int, -) -> dict[str, Any]: - """cProfile: число вызовов и порядок функций, не доли времени.""" - profiler = cProfile.Profile() - profiler.enable() - await fn() - profiler.disable() - rows = [] - for (file, line, name), (_, calls, own, total, _) in pstats.Stats( - profiler, - ).stats.items(): - if file == __file__: - continue - rows.append( - { - "function": function_label(file, line, name), - "name": name, - "calls": round(calls / count, 2), - "own_us": round(own / count * 1e6, 2), - "total_us": round(total / count * 1e6, 2), - }, - ) - rows.sort(key=lambda row: row["own_us"], reverse=True) - return { - "top": rows[:PROFILE_TOP], - "time": [ - row for row in rows if any(n in row["name"] for n in TIME_NAMES) - ], - } - - -async def measure(args: argparse.Namespace) -> dict[str, Any]: - # приложение импортируется только здесь: на хосте скрипт — stdlib - sys.path.insert(0, os.getcwd()) - from pydantic import PlainSerializer - from src.infra.memory import MemoryStore - - from src.api.schemas import Message, MessagePage - from src.core.services import MessageService - from src.main import app - from src.utils.utc import from_rfc3339, to_rfc3339 - - result: dict[str, Any] = { - "level": os.environ.get("APP__LOG_LEVEL", "INFO"), - "versions": { - "python": platform.python_version(), - **{ - name: importlib.metadata.version(name) - for name in ( - "fastapi", - "starlette", - "pydantic", - "pydantic_core", - "structlog", - ) - }, - }, - "platform": { - "machine": platform.machine(), - "libc": " ".join(platform.libc_ver()), - }, - } - - def reference(value: datetime) -> str: - return reference_rfc3339(value, args.reference_format) - - class ReferenceMessage(Message): - created_at: Annotated[ - datetime, - PlainSerializer(reference, return_type=str), - ] - - class ReferencePage(MessagePage): - items: list[ReferenceMessage] - - class NativeMessage(Message): - created_at: datetime - - class NativePage(MessagePage): - items: list[NativeMessage] - - if args.parts: - result["format"] = check_format( - to_rfc3339, - from_rfc3339, - args.reference_format, - ) - if result["format"]["mismatch"]: - return result - - # lifespan при прямых ASGI-вызовах не выполняется - app.state.store = MemoryStore() - probe = Probe(app) - user = ( - await probe.create( - "/api/v1/users", - {"username": "inproc_reader", "display_name": "Reader"}, - ) - )["id"] - chats = [ - ( - await probe.create( - "/api/v1/chats", - {"title": title, "member_ids": [user]}, - user, - ) - )["id"] - for title in ("read", "write") - ] - read_path, write_path = (f"/api/v1/chats/{c}/messages" for c in chats) - body = json.dumps({"text": "x" * TEXT_LENGTH}).encode() - get_headers = probe.headers(user) - post_headers = probe.headers(user, body) - - async def post(path: str, count: int) -> None: - for _ in range(count): - status, _ = await probe.request( - "POST", - path, - post_headers, - body=body, - ) - if status != 201: - raise InprocError(f"POST {path}: {status}") - - await post(read_path, SIZE) - cursors: list[str] = [] - query = f"limit={PAGE_LIMIT}".encode() - while len(cursors) < CURSOR_POOL: - status, raw = await probe.request( - "GET", - read_path, - get_headers, - query=query, - ) - cursor = json.loads(raw)["next_cursor"] - if status != 200 or cursor is None: - raise InprocError(f"cursor walk: {status}, next_cursor {cursor}") - cursors.append(cursor) - query = f"limit={PAGE_LIMIT}&cursor={cursor}".encode() - rng = random.Random(SEED) - queries = [ - f"limit={PAGE_LIMIT}&cursor={rng.choice(cursors)}".encode() - for _ in range(REQUESTS) - ] - - async def reads(count: int = REQUESTS) -> None: - for query in queries[:count]: - status, _ = await probe.request( - "GET", - read_path, - get_headers, - query=query, - ) - if status != 200: - raise InprocError(f"GET {read_path}: {status}") - - async def writes(count: int = REQUESTS) -> None: - await post(write_path, count) - - result["requests"] = { - "read": await repeat(reads, REQUESTS), - "write": await repeat(writes, REQUESTS), - } - if not args.parts: - return result - - dto = await MessageService(store=app.state.store).list_messages( - chat_id=UUID(chats[0]), - user_id=UUID(user), - limit=PAGE_LIMIT, - cursor=cursors[len(cursors) // 2], - ) - current = MessagePage.model_validate(dto) - reference_page = ReferencePage.model_validate(dto) - native = NativePage.model_validate(dto) - if current.model_dump_json() != reference_page.model_dump_json(): - result["format"]["mismatch"] = { - "problem": "page JSON differs from reference", - "value": "page of messages", - "expected": reference_page.model_dump_json()[:200], - "got": current.model_dump_json()[:200], - } - return result - moment = dto.items[0].created_at - result["parts"] = { - "dto_to_model": repeat_sync( - functools.partial(MessagePage.model_validate, dto), - PART_ROUNDS, - ), - "json_current": repeat_sync(current.model_dump_json, PART_ROUNDS), - "json_reference": repeat_sync( - reference_page.model_dump_json, - PART_ROUNDS, - ), - "json_native": repeat_sync(native.model_dump_json, PART_ROUNDS), - "value_current": repeat_sync( - functools.partial(to_rfc3339, moment), - VALUE_ROUNDS, - ), - "value_reference": repeat_sync( - functools.partial(reference, moment), - VALUE_ROUNDS, - ), - } - result["profile"] = { - "read": await profile( - functools.partial(reads, PROFILE_REQUESTS), - PROFILE_REQUESTS, - ), - "write": await profile( - functools.partial(writes, PROFILE_REQUESTS), - PROFILE_REQUESTS, - ), - } - return result - - -def child(args: argparse.Namespace) -> int: - """Логи приложения идут в stdout, результат — одной строкой в stderr.""" - if args.null_stdout: - # до импорта приложения: его логгер берёт sys.stdout при настройке - os.dup2(os.open(os.devnull, os.O_WRONLY), 1) - result = asyncio.run(measure(args)) - print(RESULT_MARK + json.dumps(result), file=sys.stderr, flush=True) - return 3 if (result.get("format") or {}).get("mismatch") else 0 - - -# ------------------------------------------------------------------ на хосте - - -def sh(*args: str, check: bool = True) -> str: - proc = subprocess.run( - args, - capture_output=True, - text=True, - check=False, - env={**os.environ, "LC_ALL": "C"}, - ) - if check and proc.returncode != 0: - raise InprocError( - f"{' '.join(args[:4])}…: exit {proc.returncode}\n" - f"{(proc.stdout + proc.stderr)[-2000:]}", - ) - return proc.stdout.strip() - - -def run_child(level: str, extra: list[str]) -> dict[str, Any]: - """Один запуск процесса в контейнере. - - Контейнер отсоединён (`-d`), как контейнер стенда: с подключённым - клиентом docker каждая строка лога обходится процессу заметно дороже. - """ - sh( - "docker", - "run", - "-d", - "--name", - CONTAINER, - "--cpus=1", - "--memory=2g", - "--memory-swap=2g", - "--network=none", - "--no-healthcheck", - "-e", - f"APP__LOG_LEVEL={level}", - "-v", - f"{SCRIPT}:/bench/inproc.py:ro", - "--entrypoint", - "python", - APP_IMAGE, - "/bench/inproc.py", - "--child", - *extra, - ) - try: - code = sh("docker", "wait", CONTAINER) - proc = subprocess.run( - ["docker", "logs", CONTAINER], - stdout=subprocess.DEVNULL, - stderr=subprocess.PIPE, - text=True, - check=False, - ) - finally: - sh("docker", "rm", "-f", CONTAINER, check=False) - for line in reversed(proc.stderr.splitlines()): - if line.startswith(RESULT_MARK): - return json.loads(line[len(RESULT_MARK) :]) - raise InprocError(f"child {level}: exit {code}\n{proc.stderr[-2000:]}") - - -def passport(argv: list[str], label: str) -> dict[str, Any]: - docker = json.loads(sh("docker", "info", "--format", "{{json .}}")) - machine = platform.machine() - system = platform.system() - if system == "Darwin": - system = f"macOS {platform.mac_ver()[0]}" - machine = sh("sysctl", "-n", "machdep.cpu.brand_string", check=False) - return { - "label": label, - "date": datetime.now(UTC).isoformat(timespec="seconds"), - "command": " ".join(["uv run python bench/inproc.py", *argv]), - "commit": sh("git", "-C", str(ROOT), "rev-parse", "--short", "HEAD"), - "dirty": bool( - sh( - "git", - "-C", - str(ROOT), - "status", - "--porcelain", - "--", - *APP_FILES, - ), - ), - "image": sh("docker", "image", "inspect", "-f", "{{.Id}}", APP_IMAGE), - "host": f"{machine}, {system}", - "docker": ( - f"Docker {docker.get('ServerVersion')}, VM " - f"{docker.get('NCPU')} CPU" - ), - } - - -def cell(value: dict[str, float], digits: int = 1) -> str: - return ( - f"{value['median']:.{digits}f} " - f"({value['min']:.{digits}f}–{value['max']:.{digits}f})" - ) - - -def across( - launches: list[dict[str, Any]], - scenario: str, - key: str = "wall_us", -) -> dict[str, float]: - """Медианы запусков процесса: их медиана и разброс.""" - return spread( - [run["requests"][scenario][key]["median"] for run in launches], - ) - - -def render( - meta: dict[str, Any], - launches: dict[str, list[dict[str, Any]]], -) -> str: - info = launches["INFO"][0] - versions = info["versions"] - parts = info["parts"] - native = parts["json_native"]["median"] - current_cost = parts["json_current"]["median"] - native - reference_cost = parts["json_reference"]["median"] - native - # медианы по запускам: [режим][сценарий] - time = { - mode: { - scenario: across(launches[mode], scenario) - for scenario in ("read", "write") - } - for mode in MODES - } - total = {s: time["INFO"][s]["median"] for s in ("read", "write")} - log_build = { - s: time["INFO_NULL"][s]["median"] - time["WARNING"][s]["median"] - for s in ("read", "write") - } - log_write = { - s: total[s] - time["INFO_NULL"][s]["median"] for s in ("read", "write") - } - model = parts["dto_to_model"]["median"] - rest = time["WARNING"]["read"]["median"] - model - native - current_cost - lines = [ - f"# Разложение стоимости запроса: метка `{meta['label']}`", - "", - f"- Дата: {meta['date']}", - f"- Commit: `{meta['commit']}`, незакоммиченные изменения " - f"приложения: {'есть' if meta['dirty'] else 'нет'}", - f"- Команда: `{meta['command']}`", - f"- Образ: `{APP_IMAGE}` {meta['image'][:19]}…; " - + ", ".join(f"{name} {ver}" for name, ver in versions.items()) - + f"; {info['platform']['libc']}, {info['platform']['machine']}", - "- Контейнер: `--cpus=1 --memory=2g --network=none`, отсоединён " - f"(`docker run -d`), как контейнер стенда; хост: {meta['host']}; " - f"{meta['docker']}", - f"- Данные: {SIZE} сообщений по {TEXT_LENGTH} символа, страница " - f"{PAGE_LIMIT}, зерно {SEED}", - "- Приложение вызывается в том же процессе как ASGI, без uvicorn " - "и сети. Это объяснение, куда уходит время запроса, а не замер " - "стенда: пропускную способность и задержки меряет `make bench`.", - f"- Время на запрос: {LAUNCHES} запуска процесса на каждый режим " - f"логов, в запуске — медиана {REPEATS} повторов по {REQUESTS} " - "запросов; значение — медиана (min–max) по запускам, мкс.", - "- Режимы логов: INFO — как на стенде, stdout контейнера; INFO с " - "stdout процесса в `/dev/null` — записи собираются, но не " - "пишутся в контейнер; WARNING — записи INFO отбрасываются.", - f"- Части ответа: один запуск, медиана (min–max) {REPEATS} " - "повторов, мкс. Варианты сравниваются внутри одного процесса.", - "", - "## Формат времени", - "", - f"Значений сверено с эталоном `{REFERENCE_FORMAT}`: " - f"{info['format']['checked']}; расхождений нет, обратный разбор " - "совпал, JSON страницы совпал с эталонным.", - "", - "## Сводка: из чего складывается запрос, мкс", - "", - "| Часть | read | write |", - "|---|---|---|", - "| Всего внутри приложения, логи INFO | " - f"{total['read']:.1f} | {total['write']:.1f} |", - "| логи: запись в stdout контейнера | " - f"{log_write['read']:.1f} | {log_write['write']:.1f} |", - "| логи: сборка записи (structlog, JSON) | " - f"{log_build['read']:.1f} | {log_build['write']:.1f} |", - f"| форматирование времени в ответе | {current_cost:.1f} | — |", - f"| JSON ответа без форматирования времени | {native:.1f} | — |", - f"| DTO → модель ответа | {model:.1f} | — |", - "| остальное: маршрутизация, зависимости, сервис | " - f"{rest:.1f} | {time['WARNING']['write']['median']:.1f} |", - "", - "Строки про логи и «остальное» — разности медиан разных запусков; " - "части ответа измерены напрямую.", - "", - "## Время на запрос", - "", - "| Сценарий | Логи INFO | Логи INFO, stdout в /dev/null | " - "Логи WARNING |", - "|---|---|---|---|", - ] - for scenario in ("read", "write"): - lines.append( - f"| {scenario} | " - + " | ".join(cell(time[mode][scenario]) for mode in MODES) - + " |", - ) - lines += [ - "", - "CPU процесса на запрос при логах INFO: " - + ", ".join( - f"{name} {cell(across(launches['INFO'], name, 'cpu_us'))}" - for name in ("read", "write") - ) - + ".", - "", - f"## Построение ответа страницы ({PAGE_LIMIT} сообщений)", - "", - "| Шаг | мкс |", - "|---|---|", - f"| DTO → модель ответа | {cell(parts['dto_to_model'])} |", - f"| модель → JSON, текущий форматтер | " - f"{cell(parts['json_current'])} |", - f"| модель → JSON, эталонный `strftime` | " - f"{cell(parts['json_reference'])} |", - f"| модель → JSON, без Python-сериализатора времени | " - f"{cell(parts['json_native'])} |", - "| цена форматирования времени: текущий − без сериализатора | " - f"{current_cost:.1f} |", - f"| то же для эталонного `strftime` | {reference_cost:.1f} |", - f"| одно значение, текущий форматтер | " - f"{cell(parts['value_current'], 3)} |", - f"| одно значение, эталонный `strftime` | " - f"{cell(parts['value_reference'], 3)} |", - "", - f"## Профиль вызовов (cProfile, {PROFILE_REQUESTS} запросов)", - "", - "cProfile завышает цену кода с большим числом мелких вызовов: " - "отсюда берутся число вызовов и порядок функций, не доли времени.", - ] - for scenario in ("read", "write"): - data = info["profile"][scenario] - lines += [ - "", - f"### {scenario}: форматирование времени", - "", - "| Функция | Вызовов на запрос | Своё время, мкс | " - "С вложенными, мкс |", - "|---|---|---|---|", - ] - lines += [profile_row(row) for row in data["time"]] - lines += [ - "", - f"### {scenario}: {PROFILE_TOP} функций по своему времени", - "", - "| Функция | Вызовов на запрос | Своё время, мкс | " - "С вложенными, мкс |", - "|---|---|---|---|", - ] - lines += [profile_row(row) for row in data["top"]] - return "\n".join(lines) + "\n" - - -def profile_row(row: dict[str, Any]) -> str: - return ( - f"| `{row['function']}` | {row['calls']:g} | " - f"{row['own_us']:.1f} | {row['total_us']:.1f} |" - ) - - -def host(args: argparse.Namespace, argv: list[str]) -> int: - if not re.fullmatch(r"[A-Za-z0-9._-]+", args.label or ""): - print(f"bad label {args.label!r}: use [A-Za-z0-9._-]", flush=True) - return 2 - out = ROOT / "evidence" / "profile" / f"{args.label}.txt" - if out.exists(): - print(f"{out.relative_to(ROOT)} already exists", flush=True) - return 2 - extra = ["--reference-format", args.reference_format] - names = sh("docker", "ps", "-a", "--format", "{{.Names}}", check=False) - if CONTAINER in names.split(): - # чужой запуск не трогаем: уборка ниже — только за собой - print( - f"container {CONTAINER} already exists: another run is going " - f"or a crashed one left it; docker rm -f {CONTAINER}", - flush=True, - ) - return 1 - launches: dict[str, list[dict[str, Any]]] = {mode: [] for mode in MODES} - try: - sh("docker", "build", "-q", "-t", APP_IMAGE, str(ROOT)) - meta = passport(argv, args.label) - print(f"image {APP_IMAGE} built, commit {meta['commit']}", flush=True) - # режимы чередуются: дрейф хоста не ложится на один из них - for number in range(1, LAUNCHES + 1): - for mode, (level, flags) in MODES.items(): - first = not launches["INFO"] - result = run_child( - level, - [*extra, *flags, *(["--parts"] if first else [])], - ) - mismatch = (result.get("format") or {}).get("mismatch") - if mismatch: - print( - f"time format check failed: {mismatch['problem']}\n" - f" value: {mismatch['value']}\n" - f" expected: {mismatch['expected']}\n" - f" got: {mismatch['got']}", - flush=True, - ) - return 1 - launches[mode].append(result) - requests = result["requests"] - print( - f"launch {number}/{LAUNCHES} {mode:<9} " - f"read {requests['read']['wall_us']['median']:.1f} " - f"write {requests['write']['wall_us']['median']:.1f} us", - flush=True, - ) - except InprocError as exc: - print(f"inproc failed: {exc}", flush=True) - return 1 - text = render(meta, launches) - out.parent.mkdir(parents=True, exist_ok=True) - out.write_text(text, encoding="utf-8") - print(text, flush=True) - print(f"saved to {out.relative_to(ROOT)}", flush=True) - return 0 - - -def main(argv: list[str]) -> int: - parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("--label") - parser.add_argument("--child", action="store_true") - parser.add_argument("--parts", action="store_true") - parser.add_argument("--null-stdout", action="store_true") - # отладка сверки: с другим эталоном команда обязана упасть - parser.add_argument("--reference-format", default=REFERENCE_FORMAT) - args = parser.parse_args(argv) - if args.child: - return child(args) - return host(args, argv) - - -if __name__ == "__main__": - sys.exit(main(sys.argv[1:])) diff --git a/bench/k6/cursors.js b/bench/k6/cursors.js index 6a07f6e6..d80f7c9a 100644 --- a/bench/k6/cursors.js +++ b/bench/k6/cursors.js @@ -19,7 +19,7 @@ export const options = { export function setup() { const url = `${API}/chats/${fixture.readChatId}/messages`; - const params = { headers: authHeaders(fixture.readerId) }; + const params = { headers: authHeaders(fixture.tokens[fixture.readerId]) }; const positions = []; let cursor = null; let walked = 0; @@ -50,6 +50,8 @@ export function setup() { eligible: eligible.length, first_after: pool.length ? pool[0].after : null, last_after: pool.length ? pool[pool.length - 1].after : null, + // позиции курсоров пула: сколько сообщений до каждого (для плана) + afters: pool.map((p) => p.after), cursors: pool.map((p) => p.cursor), }; } diff --git a/bench/k6/explain.js b/bench/k6/explain.js new file mode 100644 index 00000000..edfcb516 --- /dev/null +++ b/bench/k6/explain.js @@ -0,0 +1,49 @@ +// Этап плана: три страницы истории читаемого чата подряд, пока в Postgres +// стенда включён auto_explain. Первая — без курсора, средняя и последняя +// полная — курсоры из пула (середина и конец). Порядок запросов = порядок +// планов в журнале: оркестратор сопоставляет их по нему. +import http from "k6/http"; +import { check, fail } from "k6"; + +import { API, PAGE_LIMIT, WORK_DIR, authHeaders } from "./lib.js"; + +const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`)); +const pool = JSON.parse(open(`${WORK_DIR}/cursors.json`)); + +export const options = { + vus: 1, + iterations: 1, +}; + +export default function () { + const cursors = pool.cursors; + if (cursors.length === 0) { + fail("cursor pool is empty: history is shorter than a walk page"); + } + const pages = [ + ["first", null], + ["middle", cursors[Math.floor(cursors.length / 2)]], + ["last", cursors[cursors.length - 1]], + ]; + const url = `${API}/chats/${fixture.readChatId}/messages`; + const params = { headers: authHeaders(fixture.tokens[fixture.readerId]) }; + for (const [name, cursor] of pages) { + const query = cursor === null + ? `?limit=${PAGE_LIMIT}` + : `?limit=${PAGE_LIMIT}&cursor=${encodeURIComponent(cursor)}`; + const res = http.get(url + query, params); + const ok = check(res, { + [`${name} 200`]: (r) => r.status === 200, + [`${name} full page`]: (r) => + r.status === 200 && r.json("items.#") === PAGE_LIMIT, + }); + if (!ok) { + fail(`explain page ${name}: ${res.status}`); + } + } +} + +// итог не нужен: планы оркестратор берёт из журнала Postgres +export function handleSummary() { + return {}; +} diff --git a/bench/k6/lib.js b/bench/k6/lib.js index 500c2ac2..e871f891 100644 --- a/bench/k6/lib.js +++ b/bench/k6/lib.js @@ -1,5 +1,6 @@ // Общие хелперы сценариев стенда: адрес, идентификация, текст, генератор // случайных чисел, запись итога. Не Node.js: только встроенные модули k6. +import encoding from "k6/encoding"; import http from "k6/http"; import { check, fail } from "k6"; @@ -20,9 +21,18 @@ export const SUCCESS_DURATION = "http_req_duration{expected_response:true}"; // порог всегда выполняется: он нужен, чтобы подметрика попала в итог export const SUMMARY_THRESHOLDS = { [SUCCESS_DURATION]: ["max>=0"] }; -// идентификация лабы 1; с лабы 2 здесь Bearer, как Actor.headers() -export function authHeaders(userId) { - return { "X-User-Id": userId, "Content-Type": "application/json" }; +// идентификация, как Actor.headers() в student-tests: Bearer-токен сессии +export function authHeaders(token) { + return { + Authorization: `Bearer ${token}`, + "Content-Type": "application/json", + }; +} + +// синтетический пароль (72 символа, контракт — 12–128): только в памяти +// prepare.js, в фикстуру и результаты не попадает +function syntheticPassword() { + return `${crypto.randomUUID()}-${crypto.randomUUID()}`; } // синтетический текст ровно TEXT_LENGTH ASCII-символов @@ -43,23 +53,32 @@ export function mulberry32(seed) { }; } +// регистрация с паролем и вход по Basic: { id, token } пользователя export function register(username, displayName) { + const password = syntheticPassword(); const res = http.post( `${API}/users`, - JSON.stringify({ username, display_name: displayName }), + JSON.stringify({ username, display_name: displayName, password }), { headers: { "Content-Type": "application/json" } }, ); if (!check(res, { "register 201": (r) => r.status === 201 })) { fail(`register ${username}: ${res.status} ${res.body}`); } - return res.json("id"); + const basic = encoding.b64encode(`${username}:${password}`); + const login = http.post(`${API}/auth/sessions`, null, { + headers: { Authorization: `Basic ${basic}` }, + }); + if (!check(login, { "login 201": (r) => r.status === 201 })) { + fail(`login ${username}: ${login.status} ${login.body}`); + } + return { id: res.json("id"), token: login.json("token") }; } -export function createChat(ownerId, title, memberIds) { +export function createChat(ownerToken, title, memberIds) { const res = http.post( `${API}/chats`, JSON.stringify({ title, member_ids: memberIds }), - { headers: authHeaders(ownerId) }, + { headers: authHeaders(ownerToken) }, ); if (!check(res, { "chat 201": (r) => r.status === 201 })) { fail(`create chat ${title}: ${res.status} ${res.body}`); @@ -67,12 +86,12 @@ export function createChat(ownerId, title, memberIds) { return res.json("id"); } -export function sendMessage(chatId, senderId, text) { +export function sendMessage(chatId, senderToken, text) { const res = http.post( `${API}/chats/${chatId}/messages`, JSON.stringify({ text }), { - headers: authHeaders(senderId), + headers: authHeaders(senderToken), responseCallback: http.expectedStatuses(201), }, ); diff --git a/bench/k6/prefill.js b/bench/k6/prefill.js index 7591b088..7abc014e 100644 --- a/bench/k6/prefill.js +++ b/bench/k6/prefill.js @@ -31,7 +31,11 @@ export const options = { export default function () { const n = OFFSET + exec.scenario.iterationInTest; const sender = fixture.memberIds[n % fixture.memberIds.length]; - sendMessage(fixture.readChatId, sender, syntheticText("p", n)); + sendMessage( + fixture.readChatId, + fixture.tokens[sender], + syntheticText("p", n), + ); } export function handleSummary(data) { diff --git a/bench/k6/prepare.js b/bench/k6/prepare.js index d40a279b..20f63b9c 100644 --- a/bench/k6/prepare.js +++ b/bench/k6/prepare.js @@ -1,5 +1,7 @@ // Пользователи и два чата стенда: читаемый (сценарий read) и чат записи -// (сценарий write). Итог — fixture.json в рабочем каталоге. +// (сценарий write). Каждый пользователь регистрируется с паролем и входит по +// Basic; в фикстуру идут id и Bearer-токены, пароли — нет. Итог — +// fixture.json в рабочем каталоге: оркестратор удаляет его в конце прогона. import { WORK_DIR, createChat, register } from "./lib.js"; const MEMBERS = Number(__ENV.MEMBERS || 10); @@ -11,19 +13,24 @@ export const options = { }; export function setup() { - // размер начинается с пустого процесса, поэтому имени хватает времени + // размер начинается с пустой базы, поэтому имени хватает времени const stamp = Date.now().toString(36); - const readerId = register(`b${stamp}_reader`, "Bench reader"); + const tokens = {}; + const reader = register(`b${stamp}_reader`, "Bench reader"); + tokens[reader.id] = reader.token; const memberIds = []; for (let i = 0; i < MEMBERS; i++) { - memberIds.push(register(`b${stamp}_m${i}`, `Bench member ${i}`)); + const member = register(`b${stamp}_m${i}`, `Bench member ${i}`); + tokens[member.id] = member.token; + memberIds.push(member.id); } - const everyone = [readerId, ...memberIds]; + const everyone = [reader.id, ...memberIds]; return { - readerId, + readerId: reader.id, memberIds, - readChatId: createChat(readerId, "bench read", everyone), - writeChatId: createChat(readerId, "bench write", everyone), + tokens, + readChatId: createChat(reader.token, "bench read", everyone), + writeChatId: createChat(reader.token, "bench write", everyone), }; } diff --git a/bench/k6/read.js b/bench/k6/read.js index ae8c9d0d..540bfc22 100644 --- a/bench/k6/read.js +++ b/bench/k6/read.js @@ -27,7 +27,7 @@ const SEED = Number(__ENV.SEED || 0); const TRACE = Number(__ENV.TRACE || 0); const URL = `${API}/chats/${fixture.readChatId}/messages`; const PARAMS = { - headers: authHeaders(fixture.readerId), + headers: authHeaders(fixture.tokens[fixture.readerId]), responseCallback: http.expectedStatuses(200), }; diff --git a/bench/k6/tail.js b/bench/k6/tail.js index 7f29e62c..1609dab8 100644 --- a/bench/k6/tail.js +++ b/bench/k6/tail.js @@ -18,7 +18,7 @@ export const options = { export function setup() { const url = `${API}/chats/${fixture.readChatId}/messages`; - const params = { headers: authHeaders(fixture.readerId) }; + const params = { headers: authHeaders(fixture.tokens[fixture.readerId]) }; // пустой пул (история короче страницы обхода) — читаем с начала const hasPool = pool.cursors.length > 0; let cursor = hasPool ? pool.cursors[pool.cursors.length - 1] : null; diff --git a/bench/k6/write.js b/bench/k6/write.js index f6a97d43..dee1c333 100644 --- a/bench/k6/write.js +++ b/bench/k6/write.js @@ -31,7 +31,11 @@ export const options = { export default function () { const n = OFFSET + exec.scenario.iterationInTest; const sender = fixture.memberIds[n % fixture.memberIds.length]; - sendMessage(fixture.writeChatId, sender, syntheticText("w", n)); + sendMessage( + fixture.writeChatId, + fixture.tokens[sender], + syntheticText("w", n), + ); } export function handleSummary(data) { diff --git a/bench/run.py b/bench/run.py index a9d9570f..7ef2e58e 100644 --- a/bench/run.py +++ b/bench/run.py @@ -1,8 +1,12 @@ -"""Нагрузочный стенд трека 1: матрица размеров истории и конкуренции. +"""Нагрузочный стенд: матрица размеров истории и конкуренции. -Запуск — `make bench` / `make bench_quick`. Методика — design change -`load-bench-harness`, инварианты — `.claude/rules/bench.md`. Только -stdlib: приложение не импортируется, всё через docker CLI и k6. +Запуск — `make bench` / `make bench_quick`. Стенд — API, PostgreSQL и +Valkey: проект compose `mtusi-bench` из `docker-compose.yml` с override +`bench/bench.compose.yml`. Методика — design changes `load-bench-harness` +и `bench-postgres`, инварианты — `.claude/rules/bench.md`. Только stdlib: +приложение не импортируется, его нагружает k6 по HTTP; к PostgreSQL +стенда оркестратор ходит только для обслуживания и измерений (VACUUM, +размеры, планы запроса). """ import argparse @@ -11,6 +15,7 @@ import json import os import platform import re +import secrets import shutil import signal import statistics @@ -18,6 +23,8 @@ import subprocess import sys import threading import time +import uuid +from collections.abc import Callable from dataclasses import asdict, dataclass, replace from datetime import UTC, datetime from pathlib import Path @@ -29,9 +36,23 @@ K6_IMAGE = ( "9c2dee7f8ed74d317e4027c06a10f169b625638189de8d4555d0b3486a5aeb34" ) APP_IMAGE = "mtusi-messenger:bench" +PROJECT = "mtusi-bench" NETWORK = "mtusi-bench" APP = "mtusi-bench-api" +DB = "mtusi-bench-postgres" +CACHE = "mtusi-bench-valkey" K6 = "mtusi-bench-k6" +# контейнеры стенда по ролям: лимиты, состояние, паспорт +CONTAINERS = {"api": APP, "postgres": DB, "valkey": CACHE} +COMPOSE_FILES = ( + ROOT / "docker-compose.yml", + ROOT / "bench" / "bench.compose.yml", +) +# подстановки compose вместо .env рабочего стенда +ENV_FILE = ROOT / "bench" / "bench.env" +# что из окружения хоста нужно самому docker compose; остальное (в том +# числе POSTGRES_* из shell) в стенд не попадает +HOST_ENV = ("PATH", "HOME", "USER", "TMPDIR", "DOCKER_HOST", "DOCKER_CONFIG") READY_CHECK = ( "import urllib.request; urllib.request.urlopen(" "'http://127.0.0.1:8080/health/ready', timeout=2)" @@ -39,6 +60,47 @@ READY_CHECK = ( SUCCESS_METRIC = "http_req_duration{expected_response:true}" # предупреждение о хосте: swap занят больше, МиБ SWAP_WARN_MIB = 1024 +# предупреждение о VM: лимиты памяти стенда + этот запас больше памяти VM +VM_RESERVE_GIB = 1.5 +# psql в контейнере Postgres от пользователя образа, без пароля; SQL — stdin +PSQL = ( + 'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq -v ON_ERROR_STOP=1' +) +# настройки Postgres в паспорте: от них зависят план и стоимость записи +PG_SETTINGS = ( + "shared_buffers", + "effective_cache_size", + "work_mem", + "maintenance_work_mem", + "max_connections", + "synchronous_commit", + "fsync", + "wal_level", + "checkpoint_timeout", + "max_wal_size", + "random_page_cost", + "jit", + "autovacuum", + "plan_cache_mode", + "shared_preload_libraries", +) +# auto_explain на этапе плана; вне его log_min_duration = -1 (выключен) +EXPLAIN_SETTINGS = { + "auto_explain.log_min_duration": "0", + "auto_explain.log_analyze": "on", + "auto_explain.log_buffers": "on", + "auto_explain.log_timing": "on", + "auto_explain.log_format": "text", +} +# пауза после pg_reload_conf(): SIGHUP доходит до соединений пула API +RELOAD_PAUSE_S = 1.0 +# страницы этапа плана в порядке запросов explain.js +EXPLAIN_PAGES = ("first", "middle", "last") +INDEX_NODE_RE = re.compile( + r"Index Only Scan(?: Backward)? using (\w+)" + r"|Index Scan(?: Backward)? using (\w+)" + r"|Bitmap Index Scan on (\w+)", +) RUN_FIELDS = [ "run", @@ -65,6 +127,8 @@ RUN_FIELDS = [ "generator_cpu_cores", "flags", "check_failed", + # лаба 2: новые столбцы — только в конец + "db_cpu_cores", ] PREFILL_FIELDS = [ "size", @@ -85,6 +149,7 @@ PREFILL_FIELDS = [ "mem_cgroup_end_mib", "generator_cpu_cores", "flags", + "db_cpu_cores", ] @@ -112,6 +177,14 @@ class Profile: generator_cpu_limit: float = 4.0 cpus: str = "1" memory: str = "2g" + # лаба 2: лимиты хранилищ (swap = память) и срок сессии стенда; идут в + # compose переменными BENCH_* (bench/bench.compose.yml). Решение 2 + # design change bench-postgres + db_cpus: str = "4" + db_memory: str = "3g" + cache_cpus: str = "2" + cache_memory: str = "512m" + session_ttl_seconds: int = 21600 PROFILES = { @@ -194,6 +267,15 @@ def mib_bytes(value: int | None) -> float | None: return None if value is None else round(value / 2**20, 1) +def size_bytes(text: str) -> int: + """Лимит памяти docker (`512m`, `2g`) в байтах.""" + match = re.fullmatch(r"(\d+(?:\.\d+)?)([kmg]?)b?", text.strip().lower()) + if not match: + raise BenchError(f"bad memory limit {text!r}: use 512m or 2g") + power = {"": 0, "k": 1, "m": 2, "g": 3}[match.group(2)] + return int(float(match.group(1)) * 1024**power) + + def fmt(value: float | None, digits: int = 0) -> str: return "—" if value is None else f"{value:.{digits}f}" @@ -248,6 +330,29 @@ def host_warnings(state: dict[str, Any]) -> list[str]: return warnings +def vm_warnings(profile: Profile) -> list[str]: + """Лимиты памяти стенда не помещаются в VM docker с запасом. + + Тогда лимит перестаёт быть гарантией: контейнеры делят память VM, и + метки разных дней несравнимы. + """ + total = sh("docker", "info", "--format", "{{.MemTotal}}", check=False) + if not total.isdigit(): + return [] + limits = sum( + size_bytes(value) + for value in (profile.memory, profile.db_memory, profile.cache_memory) + ) + budget = int(total) - int(VM_RESERVE_GIB * 2**30) + if limits <= budget: + return [] + return [ + f"memory limits {limits / 2**30:.1f} GiB + {VM_RESERVE_GIB} GiB " + f"reserve exceed docker VM memory {int(total) / 2**30:.1f} GiB: " + "limits are not guaranteed", + ] + + def git_info() -> dict[str, Any]: commit = sh("git", "-C", str(ROOT), "rev-parse", "--short", "HEAD") status = sh("git", "-C", str(ROOT), "status", "--porcelain") @@ -266,7 +371,8 @@ def static_passport(profile: Profile) -> dict[str, Any]: "-c", "import importlib.metadata as m, json, platform; print(json.dumps(" "{'python': platform.python_version(), **{p: m.version(p) for p in " - "('fastapi', 'starlette', 'pydantic', 'uvicorn')}}))", + "('fastapi', 'starlette', 'pydantic', 'uvicorn', 'sqlalchemy', " + "'asyncpg', 'redis')}}))", ) k6_version = sh("docker", "run", "--rm", K6_IMAGE, "version") host: dict[str, Any] = {"os": platform.system(), "machine": None} @@ -306,20 +412,46 @@ def static_passport(profile: Profile) -> dict[str, Any]: class Watcher: - """Раз в секунду, пока идёт запуск k6: VmRSS приложения и жив ли оно. + """Раз в секунду, пока идёт запуск k6: VmRSS приложения, живы ли оно, + PostgreSQL и Valkey. - Приложение умерло (OOM) — k6 останавливается: иначе каждый его запрос - ждал бы таймаута, и наполнение тянулось бы часами. + Приложение или хранилище умерло (OOM, kill) — k6 останавливается: + иначе каждый его запрос ждал бы таймаута, и наполнение тянулось бы + часами. """ def __init__(self) -> None: self.samples: list[int] = [] self.app_died = False + self.stand_died: list[str] = [] self._stop = threading.Event() self._thread = threading.Thread(target=self._loop, daemon=True) + def _halt(self) -> None: + sh("docker", "exec", K6, "pkill", "-INT", "k6", check=False) + def _loop(self) -> None: while not self._stop.wait(1.0): + states = sh( + "docker", + "inspect", + "-f", + "{{.Name}} {{.State.Running}}", + DB, + CACHE, + check=False, + ) + dead = [ + name.lstrip("/") + for name, running in ( + line.split() for line in states.splitlines() if line + ) + if running != "true" + ] + if dead: + self.stand_died = dead + self._halt() + return out = sh( "docker", "exec", @@ -343,7 +475,7 @@ class Watcher: ) if running != "true": self.app_died = True - sh("docker", "exec", K6, "pkill", "-INT", "k6", check=False) + self._halt() return def __enter__(self) -> "Watcher": @@ -355,22 +487,105 @@ class Watcher: self._thread.join() +def compose_env(profile: Profile) -> dict[str, str]: + """Окружение `docker compose` стенда, собранное с нуля. + + Пароли хранилищ — новые на каждый прогон: живут только в этом словаре + и в контейнерах стенда, в результаты не пишутся. Лимиты и срок сессии + — из профиля (`BENCH_*` в `bench/bench.compose.yml`). + """ + env = {key: os.environ[key] for key in HOST_ENV if key in os.environ} + return { + **env, + "LC_ALL": "C", + "POSTGRES_PASSWORD": secrets.token_urlsafe(24), + "VALKEY_PASSWORD": secrets.token_urlsafe(24), + "BENCH_APP_CPUS": profile.cpus, + "BENCH_APP_MEMORY": profile.memory, + "BENCH_DB_CPUS": profile.db_cpus, + "BENCH_DB_MEMORY": profile.db_memory, + "BENCH_CACHE_CPUS": profile.cache_cpus, + "BENCH_CACHE_MEMORY": profile.cache_memory, + "BENCH_SESSION_TTL_SECONDS": str(profile.session_ttl_seconds), + } + + +def leftovers() -> dict[str, list[str]]: + """Контейнеры, volume и сеть стенда, оставшиеся от другого прогона. + + Ключ — подкоманда docker, которой их удалить. + """ + project = f"label=com.docker.compose.project={PROJECT}" + names = sh("docker", "ps", "-a", "--format", "{{.Names}}").split() + containers = sh( + "docker", + "ps", + "-a", + "--filter", + project, + "--format", + "{{.Names}}", + ).split() + networks = sh("docker", "network", "ls", "--format", "{{.Name}}").split() + return { + "rm -f": containers + ([K6] if K6 in names else []), + "volume rm": sh( + "docker", + "volume", + "ls", + "-q", + "--filter", + project, + ).split(), + "network rm": [NETWORK] if NETWORK in networks else [], + } + + class Stand: - """Сеть, контейнер приложения и контейнер k6 на время одного размера.""" + """Проект compose `mtusi-bench` и контейнер k6 на время одного размера.""" def __init__(self, profile: Profile, label_dir: Path) -> None: self.profile = profile self.label_dir = label_dir self.work_dir = label_dir / ".work" + self.env = compose_env(profile) + + def compose(self, *args: str, check: bool = True) -> str: + """docker compose стенда; без `-p mtusi-bench` не вызывается.""" + files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))] + proc = subprocess.run( + [ + "docker", + "compose", + "-p", + PROJECT, + "--env-file", + str(ENV_FILE), + *files, + *args, + ], + capture_output=True, + text=True, + env=self.env, + check=False, + ) + if check and proc.returncode != 0: + raise BenchError( + f"docker compose {' '.join(args[:3])}: exit " + f"{proc.returncode}\n{(proc.stdout + proc.stderr)[-2000:]}", + ) + return proc.stdout.strip() def check_free(self) -> None: - names = sh("docker", "ps", "-a", "--format", "{{.Names}}").split() - busy = [name for name in (APP, K6) if name in names] - if busy: + found = {cmd: names for cmd, names in leftovers().items() if names} + if found: + fix = "; ".join( + f"docker {cmd} {' '.join(names)}" + for cmd, names in found.items() + ) raise BenchError( - f"containers {', '.join(busy)} already exist: another bench " - "is running or a crashed one left them; remove with " - f"docker rm -f {' '.join(busy)}", + "bench stand leftovers exist: another bench is running or a " + f"crashed one left them; remove with: {fix}", ) def build_image(self) -> str: @@ -384,23 +599,14 @@ class Stand: ) return sh("docker", "image", "inspect", "-f", "{{.Id}}", APP_IMAGE) - def start(self) -> None: + def start(self, say: Callable[[str], None]) -> None: + """Свежий стенд: пустая база на новом volume, миграции, API, k6.""" self.work_dir.mkdir(parents=True, exist_ok=True) - sh("docker", "network", "create", NETWORK) - sh( - "docker", - "run", - "-d", - "--name", - APP, - "--network", - NETWORK, - f"--cpus={self.profile.cpus}", - f"--memory={self.profile.memory}", - f"--memory-swap={self.profile.memory}", - "--no-healthcheck", - APP_IMAGE, - ) + self.compose("up", "-d", "--wait", "postgres", "valkey") + say("postgres and valkey healthy") + self.compose("run", "--rm", "migrate") + say("migrations applied") + self.compose("up", "-d", "--no-deps", "--no-build", "api") sh( "docker", "run", @@ -432,54 +638,182 @@ class Stand: ) if probe.returncode == 0: return - state = self.app_state() + state = self.state(APP) if not state["running"]: reason = "oom" if state["oom"] else "exited" raise BenchError(f"{APP} died during start ({reason})") time.sleep(0.25) raise BenchError(f"{APP} not ready in {timeout:.0f}s") - def stop(self) -> None: + def stop(self) -> bool: + """k6, контейнеры, сеть и volume стенда; True — ничего не осталось. + + k6 — первым: подключённый к сети чужой контейнер не дал бы compose + удалить сеть. + """ subprocess.run( - ["docker", "rm", "-f", APP, K6], - capture_output=True, - check=False, - ) - subprocess.run( - ["docker", "network", "rm", NETWORK], + ["docker", "rm", "-f", K6], capture_output=True, check=False, ) + self.compose("down", "-v", "--remove-orphans", check=False) + return not any(leftovers().values()) def limits(self) -> dict[str, Any]: - host = json.loads( - sh("docker", "inspect", "-f", "{{json .HostConfig}}", APP), - ) - config = json.loads( - sh("docker", "inspect", "-f", "{{json .Config}}", APP), - ) - return { - "nano_cpus": host.get("NanoCpus"), - "memory": host.get("Memory"), - "memory_swap": host.get("MemorySwap"), - "published_ports": host.get("PortBindings") or {}, - "healthcheck": (config.get("Healthcheck") or {}).get("Test"), - "log_driver": (host.get("LogConfig") or {}).get("Type"), - } + """Лимиты контейнеров стенда, прочитанные у запущенных контейнеров.""" + limits = {} + for role, name in CONTAINERS.items(): + host = json.loads( + sh("docker", "inspect", "-f", "{{json .HostConfig}}", name), + ) + config = json.loads( + sh("docker", "inspect", "-f", "{{json .Config}}", name), + ) + limits[role] = { + "nano_cpus": host.get("NanoCpus"), + "memory": host.get("Memory"), + "memory_swap": host.get("MemorySwap"), + "published_ports": host.get("PortBindings") or {}, + "healthcheck": (config.get("Healthcheck") or {}).get("Test"), + "log_driver": (host.get("LogConfig") or {}).get("Type"), + } + return limits - def app_state(self) -> dict[str, Any]: + def state(self, name: str) -> dict[str, Any]: state = json.loads( - sh("docker", "inspect", "-f", "{{json .State}}", APP), + sh("docker", "inspect", "-f", "{{json .State}}", name), ) - restarts = sh("docker", "inspect", "-f", "{{.RestartCount}}", APP) + restarts = sh("docker", "inspect", "-f", "{{.RestartCount}}", name) return { "running": state.get("Running"), "oom": state.get("OOMKilled"), "restarts": int(restarts or 0), } + def down_storages(self) -> list[str]: + """Хранилища, которые за прогон умирали, убивались или рестартовали.""" + down = [] + for name in (DB, CACHE): + state = self.state(name) + if not state["running"] or state["oom"] or state["restarts"]: + down.append(name) + return down + + def psql(self, sql: str, *, check: bool = True) -> str: + """SQL в базе стенда через stdin: пользователь контейнера, без пароля.""" + proc = subprocess.run( + ["docker", "exec", "-i", DB, "sh", "-c", PSQL], + input=sql, + capture_output=True, + text=True, + check=False, + ) + if check and proc.returncode != 0: + raise BenchError(f"psql: exit {proc.returncode}\n{proc.stderr}") + return proc.stdout.strip() + + def maintain(self) -> float: + """VACUUM (ANALYZE) и CHECKPOINT после наполнения; секунды. + + Статистика и состояние таблиц одинаковы у всех меток, а не + зависят от того, когда сработал autovacuum (решение 4). + """ + started = time.monotonic() + self.psql("VACUUM (ANALYZE);\nCHECKPOINT;\n") + return time.monotonic() - started + + def storage(self) -> dict[str, Any]: + """Объём таблицы сообщений и её индексов, число строк.""" + row = self.psql( + "SELECT pg_table_size('messages'), pg_indexes_size('messages'), " + "count(*) FROM messages;\n", + ) + table, indexes, count = (int(value) for value in row.split("|")) + return { + "messages_rows": count, + "messages_table_bytes": table, + "messages_indexes_bytes": indexes, + "db_bytes_per_message": ( + round((table + indexes) / count) if count else None + ), + } + + def db_log(self) -> str: + """Журнал Postgres стенда (stderr контейнера): только в памяти.""" + proc = subprocess.run( + ["docker", "logs", DB], + capture_output=True, + text=True, + check=False, + ) + return proc.stdout + proc.stderr + + def passport(self) -> dict[str, Any]: + """Хранилища и окружение API для паспорта; паролей здесь нет.""" + settings = self.psql( + "SELECT name, current_setting(name) FROM pg_settings " + "WHERE name = ANY(string_to_array(" + f"'{','.join(PG_SETTINGS)}', ',')) ORDER BY name;\n", + ) + info = sh( + "docker", + "exec", + CACHE, + "sh", + "-c", + 'exec valkey-cli -p "$VALKEY_PORT" INFO server', + ) + valkey_version = re.search(r"^valkey_version:(\S+)", info, re.M) + memory = sh( + "docker", + "exec", + CACHE, + "sh", + "-c", + 'exec valkey-cli -p "$VALKEY_PORT" CONFIG GET "maxmemory*"', + ).splitlines() + env = json.loads( + sh("docker", "inspect", "-f", "{{json .Config.Env}}", APP), + ) + app_env = dict( + sorted( + item.split("=", 1) + for item in env + if re.match(r"[A-Z0-9_]+__[A-Z0-9_]+=", item) + and "PASSWORD" not in item.split("=", 1)[0] + ), + ) + + def image(name: str) -> dict[str, str]: + return { + "image": sh( + "docker", + "inspect", + "-f", + "{{.Config.Image}}", + name, + ), + "id": sh("docker", "inspect", "-f", "{{.Image}}", name), + } + + return { + "postgres": { + **image(DB), + "version": self.psql("SHOW server_version;\n"), + "settings": dict( + line.split("|", 1) for line in settings.splitlines() + ), + }, + "valkey": { + **image(CACHE), + "version": valkey_version.group(1) if valkey_version else None, + **dict(zip(memory[::2], memory[1::2], strict=True)), + }, + "app_env": app_env, + } + def snapshot(self) -> dict[str, Any]: - """CPU и память приложения, CPU генератора. + """CPU и память приложения, CPU PostgreSQL и генератора. Если приложение уже мертво (OOM), его поля — None: снимок нужен и для записи проваленного прогона. @@ -495,6 +829,14 @@ class Stand: check=False, ) k6 = sh("docker", "exec", K6, "cat", "/sys/fs/cgroup/cpu.stat") + db = sh( + "docker", + "exec", + DB, + "cat", + "/sys/fs/cgroup/cpu.stat", + check=False, + ) def number(pattern: str, text: str) -> int | None: match = re.search(pattern, text, re.MULTILINE) @@ -506,6 +848,7 @@ class Stand: "rss_kib": number(r"^VmRSS:\s+(\d+) kB", app), "hwm_kib": number(r"^VmHWM:\s+(\d+) kB", app), "k6_usec": number(r"^usage_usec (\d+)$", k6), + "db_usec": number(r"^usage_usec (\d+)$", db), } def k6( @@ -616,6 +959,10 @@ class Measured: def generator_cpu(self) -> float | None: return self.cores("k6_usec") + @property + def db_cpu(self) -> float | None: + return self.cores("db_usec") + def k6_failure(script: str, proc: subprocess.CompletedProcess[str]) -> str: tail = (proc.stdout + proc.stderr)[-3000:] @@ -632,9 +979,10 @@ def measure( before = stand.snapshot() with Watcher() as watcher: proc = stand.k6(script, env, check=False) - # если приложение умерло, k6 остановлен сторожем: прогон пишется с - # пометкой, а не падает здесь - if proc.returncode != 0 and not watcher.app_died: + # если приложение или хранилище умерло, k6 остановлен сторожем: прогон + # пишется с пометкой, а не падает здесь + died = watcher.app_died or watcher.stand_died + if proc.returncode != 0 and not died: raise BenchError(k6_failure(script, proc)) after = stand.snapshot() values = [ @@ -652,12 +1000,15 @@ def run_flags( profile: Profile, measured: Measured, app: dict[str, Any], + storages_down: list[str], ) -> list[str]: flags = [] if app["oom"]: flags.append("oom") if not app["running"] or app["restarts"]: flags.append("app_down") + if storages_down: + flags.append("stand_down") summary = measured.summary if summary["requests_failed"] or summary["check_failed"]: flags.append("errors") @@ -667,6 +1018,160 @@ def run_flags( return flags +# ----------------------------------------------------------- план запроса + + +def plan_entries(log: str, marker: str) -> list[str]: + """Записи auto_explain между маркерами этапа плана. + + Запись начинается строкой `LOG: duration: … plan:` и продолжается + строками с табуляцией; префикс времени и pid отбрасывается. + """ + lines = log.splitlines() + bounds = [ + next( + (i for i, line in enumerate(lines) if f"{marker} {edge}" in line), + None, + ) + for edge in ("start", "end") + ] + if None in bounds: + return [] + entries: list[list[str]] = [] + current: list[str] | None = None + for line in lines[bounds[0] + 1 : bounds[1]]: + if line.startswith("\t"): + if current is not None: + current.append(line[1:]) + continue + current = None + head = line.partition("LOG: ")[2].rstrip() + if head.startswith("duration:") and head.endswith("plan:"): + current = [head] + entries.append(current) + return ["\n".join(entry) for entry in entries] + + +def is_history(entry: str) -> bool: + """Запись — запрос страницы истории (читает таблицу messages). + + Остальные записи окна (проверка сессии с хэшем токена в параметрах, + служебные запросы) в результаты не попадают. + """ + text = entry.partition("Query Parameters:")[0] + return "Query Text:" in text and "FROM messages" in text + + +def plan_parts(entry: str) -> dict[str, Any] | None: + """Текст запроса, параметры и тело плана записи auto_explain.""" + lines = entry.splitlines() + starts = [i for i, line in enumerate(lines) if line.startswith("Query ")] + if len(starts) != 2 or not lines[starts[1]].startswith("Query Param"): + return None + text = "\n".join(lines[starts[0] : starts[1]]) + params = lines[starts[1]].partition(": ")[2] + return { + "text": text.removeprefix("Query Text: "), + "params": [ + value.replace("''", "'") + for value in re.findall(r"\$\d+ = '((?:[^']|'')*)'", params) + ], + "plan": "\n".join(lines[starts[1] + 1 :]), + } + + +def plan_summary(plan: str, time_ms: float | None) -> dict[str, Any]: + """Узел доступа к messages, буферы верхнего узла, строки, время.""" + node = re.search( + r"((?:Parallel )?(?:Seq Scan|Index Only Scan|Index Scan|" + r"Bitmap Heap Scan)(?: Backward)?(?: using \w+)? on messages)", + plan, + ) + buffers = re.search(r"Buffers: ([^\n]*)", plan) + hit = re.search(r"shared hit=(\d+)", buffers.group(1)) if buffers else None + read = re.search(r"read=(\d+)", buffers.group(1)) if buffers else None + rows = re.search(r"\(actual time=[\d.]+\.\.[\d.]+ rows=([\d.]+)", plan) + if time_ms is None: + execution = re.search(r"Execution Time: ([\d.]+) ms", plan) + time_ms = float(execution.group(1)) if execution else None + return { + "node": node.group(1) if node else None, + "shared_hit": int(hit.group(1)) if hit else 0, + "shared_read": int(read.group(1)) if read else 0, + "rows": float(rows.group(1)) if rows else None, + "time_ms": time_ms, + # параметры в условиях плана — generic plan, литералы — custom + "kind": "generic" if re.search(r"\$\d", plan) else "custom", + } + + +def entry_duration(entry: str) -> float | None: + match = re.match(r"duration: ([\d.]+) ms", entry) + return float(match.group(1)) if match else None + + +def index_name(plan: str) -> str | None: + match = INDEX_NODE_RE.search(plan) + return ( + next((name for name in match.groups() if name), None) + if match + else None + ) + + +def render_explain( + size: int, + git: dict[str, Any], + positions: dict[str, int], + entries: list[str], + contrast: dict[str, str] | None, +) -> str: + """Файл `explain-<размер>.txt`: планы приложения и пара psql.""" + lines = [ + f"# План запроса истории: размер {human(size)}", + "", + f"Commit {git['commit']}" + + (" + незакоммиченные изменения" if git["dirty"] else ""), + "Страница истории читаемого чата; позиция — сколько сообщений", + "истории до страницы:", + *(f"- {page}: после {after}" for page, after in positions.items()), + "", + "## Планы приложения", + "", + "auto_explain (ANALYZE, BUFFERS, TIMING): запрос, параметры и план,", + "с которыми его выполнило приложение (prepared statement asyncpg).", + "", + ] + for page, entry in zip(EXPLAIN_PAGES, entries, strict=True): + lines += [f"### {page}", "", entry, ""] + if contrast is None: + lines += [ + "## Средняя страница без индекса", + "", + "План приложения не использовал индекс: сравнения нет.", + "", + ] + return "\n".join(lines) + index = contrast["index"] + lines += [ + "## Средняя страница в psql: с индексом и без", + "", + "Тот же текст запроса и те же параметры, что у плана middle.", + "psql планирует их заново (custom plan). DROP INDEX — внутри", + "транзакции, затем ROLLBACK: индекс остаётся в базе.", + "", + f"### С индексом {index}", + "", + contrast["with_index"], + "", + f"### Без индекса {index}", + "", + contrast["without_index"], + "", + ] + return "\n".join(lines) + + # ------------------------------------------------------------ результаты @@ -760,8 +1265,11 @@ def build_summary( f"{profile['repeats']}; чтение {profile['read_measure_s']} с после " f"{profile['read_warmup_s']} с прогрева; запись " f"{profile['write_measure']} после {profile['write_warmup']}", - f"- Лимиты приложения: {profile['cpus']} CPU, {profile['memory']} " - "без swap; значения — медиана (min–max) по повторам", + f"- Лимиты без swap: API {profile['cpus']} CPU / " + f"{profile['memory']}, PostgreSQL {profile['db_cpus']} CPU / " + f"{profile['db_memory']}, Valkey {profile['cache_cpus']} CPU / " + f"{profile['cache_memory']}; значения — медиана (min–max) по " + "повторам", "- Посторонние контейнеры в VM во время замера: " + (", ".join(meta.get("other_containers") or []) or "нет"), "", @@ -774,9 +1282,9 @@ def build_summary( f"## Сценарий `{scenario}`", "", "| Размер | Клиенты | RPS | p50, мс | p95, мс | p99, мс | " - "max, мс | CPU, ядер | RSS конец, МиБ | Сообщений в начале | " - "Пометки |", - "|---|---|---|---|---|---|---|---|---|---|---|", + "max, мс | CPU API, ядер | CPU БД, ядер | RSS конец, МиБ | " + "Сообщений в начале | Пометки |", + "|---|---|---|---|---|---|---|---|---|---|---|---|", ] cells = sorted({(r["size"], r["concurrency"]) for r in rows}) for size, conc in cells: @@ -794,6 +1302,7 @@ def build_summary( f"{cell([r['p99_ms'] for r in group], 2)} | " f"{cell([r['max_ms'] for r in group], 1)} | " f"{cell([r['app_cpu_cores'] for r in group], 2)} | " + f"{cell([r['db_cpu_cores'] for r in group], 2)} | " f"{cell([r['rss_end_mib'] for r in group], 1)} | " f"{cell([r['store_messages_start'] for r in group], 0)} | " f"{' '.join(flags) or '—'} |", @@ -803,18 +1312,49 @@ def build_summary( lines += [ "## Память и наполнение по размерам", "", - "| Размер | RSS до, МиБ | RSS после, МиБ | Байт на сообщение | " - "Наполнение, сообщ/с | Курсоров в пуле | Пик RSS за размер, МиБ |", - "|---|---|---|---|---|---|---|", + "Объём `messages` — после `VACUUM (ANALYZE)`, до прогонов: в " + "таблице ровно N сообщений читаемого чата.", + "", + "| Размер | RSS API до, МиБ | RSS API после, МиБ | " + "Байт RSS на сообщение | Таблица, МиБ | Индексы, МиБ | " + "Байт в БД на сообщение | Наполнение, сообщ/с | " + "Курсоров в пуле | Пик RSS за размер, МиБ |", + "|---|---|---|---|---|---|---|---|---|---|", ] for info in sizes: lines.append( f"| {human(info['size'])} | {info['rss_before_mib']} | " f"{info['rss_after_mib']} | {info['bytes_per_message']} | " + f"{mib_bytes(info.get('messages_table_bytes'))} | " + f"{mib_bytes(info.get('messages_indexes_bytes'))} | " + f"{info.get('db_bytes_per_message', '—')} | " f"{info['prefill_rate']} | {info['cursors']} | " f"{info.get('rss_peak_mib', '—')} |", ) lines.append("") + lines += [ + "## Планы запроса истории", + "", + "Страница читаемого чата (`limit` профиля). `app` — план " + "запроса приложения (auto_explain), `psql` — тот же запрос с " + "теми же параметрами в psql, `no index` — без индекса в " + "откатываемой транзакции. Буферы — верхнего узла плана, файлы " + "— `explain-<размер>.txt`.", + "", + "| Размер | Страница | После сообщений | Источник | Узел | " + "shared hit | read | Строк | Время, мс | План |", + "|---|---|---|---|---|---|---|---|---|---|", + ] + for info in sizes: + for plan in info.get("plans", []): + lines.append( + f"| {human(info['size'])} | {plan['page']} | " + f"{plan['after']} | {plan['source']} | " + f"{plan['node'] or '—'} | {plan['shared_hit']} | " + f"{plan['shared_read']} | {fmt(plan['rows'])} | " + f"{fmt(plan['time_ms'], 3)} | {plan['kind']} |", + ) + lines.append("") if prefill: largest = max(r["size"] for r in prefill) curve = [r for r in prefill if r["size"] == largest] @@ -823,14 +1363,16 @@ def build_summary( f"хранилища, {profile['prefill_vus']} клиента", "", "| Порция | Сообщений после | RPS | p50, мс | p95, мс | " - "p99, мс | max, мс | CPU, ядер | RSS, МиБ | Пометки |", - "|---|---|---|---|---|---|---|---|---|---|", + "p99, мс | max, мс | CPU API, ядер | CPU БД, ядер | RSS, МиБ | " + "Пометки |", + "|---|---|---|---|---|---|---|---|---|---|---|", ] for r in curve: lines.append( f"| {r['chunk']} | {r['messages_after']} | {fmt(r['rps'])} | " f"{r['p50_ms']} | {r['p95_ms']} | {r['p99_ms']} | " - f"{r['max_ms']} | {r['app_cpu_cores']} | {r['rss_end_mib']} " + f"{r['max_ms']} | {r['app_cpu_cores']} | " + f"{r['db_cpu_cores']} | {r['rss_end_mib']} " f"| {r['flags'] or '—'} |", ) lines.append("") @@ -887,7 +1429,8 @@ class Bench: continue filled = self.prefilled if current else 0 left += (size - filled) / self.prefill_rate + size / 100 / 500 - left += 15 + # стенд, миграции, обслуживание БД и план + left += 30 per_size = len(p.concurrency) * p.repeats reads_left = writes_left = per_size * (len(p.sizes) - self.done_sizes) done_in_size = self.runs_done - self.done_sizes * per_size * 2 @@ -932,23 +1475,42 @@ class Bench: def run_size(self, index: int, size: int) -> None: stand = self.stand - self.stage = f"size {human(size)}: start" - stand.start() + name = human(size) + self.stage = f"size {name}: start" + self.say(f"size {name} ({index}/{len(self.profile.sizes)}): start") + stand.start(lambda text: self.say(f"size {name}: {text}")) limits = stand.limits() self.results.meta.setdefault("limits", limits) if limits != self.results.meta["limits"]: raise BenchError(f"limits changed between sizes: {limits}") + if "stand" not in self.results.meta: + self.results.meta["stand"] = stand.passport() + self.results.write_meta() rss_start = stand.snapshot()["rss_kib"] - self.say( - f"size {human(size)} ({index}/{len(self.profile.sizes)}): " - f"app started, RSS {mib(rss_start)} MiB", - ) + self.say(f"size {name}: app started, RSS {mib(rss_start)} MiB") stand.k6("prepare.js", {"MEMBERS": self.profile.members}) self.progress() rss_before = stand.snapshot()["rss_kib"] prefill_seconds = self.run_prefill(size) after = stand.snapshot() rss_after = after["rss_kib"] + self.stage = f"size {name}: maintenance" + self.progress() + seconds = stand.maintain() + storage = stand.storage() + if storage["messages_rows"] != size: + raise BenchError( + f"messages table has {storage['messages_rows']} rows after " + f"prefill, expected {size}", + ) + self.say( + f"size {name}: VACUUM (ANALYZE) and CHECKPOINT in {seconds:.1f}s; " + f"messages {mib_bytes(storage['messages_table_bytes'])} MiB + " + f"indexes {mib_bytes(storage['messages_indexes_bytes'])} MiB, " + f"{storage['db_bytes_per_message']} B/msg", + ) + self.stage = f"size {name}: cursors" + self.progress() stand.k6( "cursors.js", { @@ -961,6 +1523,10 @@ class Bench: raise BenchError( f"read chat has {pool['walked']} messages, expected {size}", ) + self.say(f"size {name}: cursors {len(pool['cursors'])}") + self.stage = f"size {name}: query plan" + self.progress() + plans = self.explain(size, pool) info = { "size": size, "rss_before_mib": mib(rss_before), @@ -971,14 +1537,16 @@ class Bench: "prefill_seconds": round(prefill_seconds, 1), "prefill_rate": round(size / prefill_seconds), "cursors": len(pool["cursors"]), + "maintenance_seconds": round(seconds, 1), + **storage, + "plans": plans, } self.results.sizes.append(info) self.results.write_meta() self.prepared = True self.say( - f"size {human(size)}: prefill done, RSS {info['rss_after_mib']} " - f"MiB (+{info['bytes_per_message']} B/msg); " - f"cursors {info['cursors']}", + f"size {name}: prefill done, app RSS {info['rss_after_mib']} " + f"MiB (+{info['bytes_per_message']} B/msg)", ) store = size for scenario in ("read", "write"): @@ -989,7 +1557,8 @@ class Bench: self.check_read_chat(size) info["rss_peak_mib"] = mib(stand.snapshot()["hwm_kib"]) self.results.write_meta() - stand.stop() + if not stand.stop(): + raise BenchError(f"stand of size {name} was not removed") def check_read_chat(self, size: int) -> None: """После блока чтения в читаемом чате по-прежнему ровно N. @@ -1007,6 +1576,136 @@ class Bench: ) self.say(f"size {human(size)}: read chat unchanged, {total} messages") + def explain(self, size: int, pool: dict[str, Any]) -> list[dict[str, Any]]: + """Этап плана: EXPLAIN (ANALYZE, BUFFERS) запросов истории приложения. + + auto_explain включается между маркерами, `explain.js` читает первую, + среднюю и последнюю полную страницу; планы берутся из журнала + Postgres. Затем средняя страница в psql с индексом и без него + (`DROP INDEX` в откатываемой транзакции). Решение 5 design change + `bench-postgres`. + """ + stand = self.stand + marker = f"bench-explain {uuid.uuid4().hex}" + enable = "".join( + f"ALTER SYSTEM SET {key} = '{value}';\n" + for key, value in EXPLAIN_SETTINGS.items() + ) + disable = "".join( + f"ALTER SYSTEM RESET {key};\n" for key in EXPLAIN_SETTINGS + ) + stand.psql( + f"DO $$ BEGIN RAISE LOG '{marker} start'; END $$;\n" + f"{enable}SELECT pg_reload_conf();\n", + ) + time.sleep(RELOAD_PAUSE_S) + try: + stand.k6("explain.js", {}) + finally: + stand.psql( + f"{disable}SELECT pg_reload_conf();\n" + f"DO $$ BEGIN RAISE LOG '{marker} end'; END $$;\n", + ) + # соединения пула API должны получить выключение до прогонов + time.sleep(RELOAD_PAUSE_S) + entries = [ + entry + for entry in plan_entries(stand.db_log(), marker) + if is_history(entry) + ] + if len(entries) != len(EXPLAIN_PAGES): + raise BenchError( + f"size {human(size)}: expected {len(EXPLAIN_PAGES)} history " + f"query plans in the PostgreSQL log, found {len(entries)}", + ) + afters = pool["afters"] + positions = dict( + zip( + EXPLAIN_PAGES, + (0, afters[len(afters) // 2], afters[-1]), + strict=True, + ), + ) + plans = [] + for page, entry in zip(EXPLAIN_PAGES, entries, strict=True): + parts = plan_parts(entry) or {"plan": entry} + plans.append( + { + "page": page, + "after": positions[page], + "source": "app", + **plan_summary(parts["plan"], entry_duration(entry)), + }, + ) + contrast = self.explain_without_index(entries[1]) + if contrast is not None: + for key, source in ( + ("with_index", "psql"), + ("without_index", "psql, no index"), + ): + plans.append( + { + "page": "middle", + "after": positions["middle"], + "source": source, + **plan_summary(contrast[key], None), + }, + ) + text = render_explain( + size, + self.results.meta["git"], + positions, + entries, + contrast, + ) + path = self.results.dir / f"explain-{human(size)}.txt" + path.write_text(text, encoding="utf-8") + for plan in plans: + self.say( + f"size {human(size)}: plan {plan['page']} ({plan['source']}): " + f"{plan['node']}, shared hit={plan['shared_hit']} " + f"read={plan['shared_read']}, {plan['time_ms']} ms", + ) + return plans + + def explain_without_index(self, entry: str) -> dict[str, str] | None: + """Тот же запрос и параметры в psql: с индексом и без него. + + `DROP INDEX` идёт внутри транзакции, которая откатывается: индекс + остаётся, что проверяется по `pg_indexes`. Нагрузки в этот момент + нет. План приложения без индекса — сравнения нет, None. + """ + parts = plan_parts(entry) + index = index_name(parts["plan"]) if parts else None + if parts is None or index is None: + return None + args = ", ".join( + "'" + value.replace("'", "''") + "'" for value in parts["params"] + ) + out = self.stand.psql( + "SET lock_timeout = '5s';\n" + "BEGIN;\n" + f"PREPARE page AS {parts['text']};\n" + "\\echo @@with-index\n" + f"EXPLAIN (ANALYZE, BUFFERS) EXECUTE page({args});\n" + f'DROP INDEX "{index}";\n' + "\\echo @@without-index\n" + f"EXPLAIN (ANALYZE, BUFFERS) EXECUTE page({args});\n" + "ROLLBACK;\n", + ) + with_index, _, without_index = out.partition("@@without-index") + kept = self.stand.psql( + "SELECT count(*) FROM pg_indexes WHERE tablename = 'messages' " + f"AND indexname = '{index}';\n", + ) + if kept != "1": + raise BenchError(f"index {index} is missing after the rollback") + return { + "index": index, + "with_index": with_index.replace("@@with-index", "").strip(), + "without_index": without_index.strip(), + } + def run_prefill(self, size: int) -> float: chunk_size = self.profile.prefill_chunk total_seconds = 0.0 @@ -1026,7 +1725,13 @@ class Bench: self.results.dir / "raw" / f"{name}.json", ) summary = measured.summary - flags = run_flags(self.profile, measured, self.stand.app_state()) + down = self.stand.down_storages() + flags = run_flags( + self.profile, + measured, + self.stand.state(APP), + down, + ) self.results.add_prefill( { **summary, @@ -1041,8 +1746,14 @@ class Bench: ), "generator_cpu_cores": measured.generator_cpu, "flags": " ".join(flags), + "db_cpu_cores": measured.db_cpu, }, ) + if down: + raise BenchError( + f"{', '.join(down)} went down during prefill chunk " + f"{chunk}: matrix stopped", + ) if summary["requests_ok"] != count: raise BenchError( f"prefill chunk {chunk}: {summary['requests_ok']} of " @@ -1099,8 +1810,9 @@ class Bench: self.results.dir / "raw" / f"{name}.json", ) summary = measured.summary - app = self.stand.app_state() - flags = run_flags(p, measured, app) + app = self.stand.state(APP) + down = self.stand.down_storages() + flags = run_flags(p, measured, app, down) end = store + (summary["requests_ok"] if scenario == "write" else 0) row = { **summary, @@ -1118,6 +1830,7 @@ class Bench: "store_messages_end": end, "generator_cpu_cores": measured.generator_cpu, "flags": " ".join(flags), + "db_cpu_cores": measured.db_cpu, } self.results.add_run(row) self.runs_done += 1 @@ -1133,7 +1846,8 @@ class Bench: f"c={conc:<2} r{repeat}: {fmt(summary['rps'])} rps " f"p50 {summary['p50_ms']} p95 {summary['p95_ms']} " f"p99 {summary['p99_ms']} ms cpu {measured.app_cpu} " - f"rss {row['rss_end_mib']} MiB err {errors} " + f"db {measured.db_cpu} rss {row['rss_end_mib']} MiB " + f"err {errors} " f"~{fmt_left(self.eta())} left" + (f" [{' '.join(flags)}]" if flags else ""), ) @@ -1143,6 +1857,10 @@ class Bench: f"{APP} is down after {name} ({' '.join(flags)}): " "matrix stopped", ) + if down: + raise BenchError( + f"{', '.join(down)} went down during {name}: matrix stopped", + ) return end @@ -1192,7 +1910,11 @@ def main(argv: list[str]) -> int: profile, overrides = apply_overrides(PROFILES[args.profile], args) git = git_info() state = host_state() - warnings = host_warnings(state) + try: + warnings = host_warnings(state) + vm_warnings(profile) + except BenchError as exc: + print(f"bench failed: {exc}", flush=True) + return 2 meta: dict[str, Any] = { "label": args.label, "status": "incomplete", @@ -1228,7 +1950,7 @@ def main(argv: list[str]) -> int: except BenchError as exc: print(f"bench failed: {exc}", flush=True) return 1 - say(f"image {APP_IMAGE} built ({image[:19]}…), network {NETWORK}") + say(f"image {APP_IMAGE} built ({image[:19]}…), compose project {PROJECT}") meta.update(static_passport(profile)) results = Results(label_dir, meta) bench = Bench(profile, args.label, results) @@ -1254,7 +1976,10 @@ def main(argv: list[str]) -> int: finally: # повторный Ctrl+C не должен оборвать уборку стенда signal.signal(signal.SIGINT, signal.SIG_IGN) - bench.stand.stop() + if not bench.stand.stop(): + say(f"cleanup incomplete: {leftovers()}") + code = code or 1 + # fixture.json с токенами — только здесь, в результаты не попадает shutil.rmtree(bench.stand.work_dir, ignore_errors=True) meta["finished_at"] = datetime.now(UTC).isoformat(timespec="seconds") meta["host_state"]["end"] = host_state() diff --git a/openspec/changes/bench-postgres/.openspec.yaml b/openspec/changes/bench-postgres/.openspec.yaml new file mode 100644 index 00000000..ad94bada --- /dev/null +++ b/openspec/changes/bench-postgres/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-02 diff --git a/openspec/changes/bench-postgres/design.md b/openspec/changes/bench-postgres/design.md new file mode 100644 index 00000000..3955130e --- /dev/null +++ b/openspec/changes/bench-postgres/design.md @@ -0,0 +1,439 @@ +# Design + +## Context + +Мотивация — `proposal.md`, требования — дельта `load-benchmark`. Что +есть сейчас: + +- `bench/run.py` (оркестратор, только stdlib) поднимает сеть + `mtusi-bench` и два контейнера через `docker run`: + - `mtusi-bench-api` — образ `mtusi-messenger:bench`, `--cpus=1 + --memory=2g --memory-swap=2g --no-healthcheck`; + - `mtusi-bench-k6` — `grafana/k6` с пином, `sleep infinity`, сценарии + запускаются через `docker exec`. + + Каждый размер — новый контейнер API, то есть пустой `MemoryStore`. + Методика (размеры, конкуренция, повторы, прогрев, лимиты) — поля + `Profile`, они целиком пишутся в `meta.json`. +- `bench/k6/lib.js` собирает заголовок `X-User-Id`, а регистрация в + `prepare.js` идёт без пароля. На коде лабы 2 первый же запрос + `prepare.js` получает 400, следующие — 401. +- `bench/inproc.py` в режиме `--child` импортирует + `src.infra.memory.MemoryStore`, которого больше нет. +- Рабочий стенд — `docker-compose.yml`, проект `mtusi-lab2`: Postgres + 18.6 и Valkey 9.1.2 с пинами, healthcheck и одноразовый `migrate`; + значения из `.env`, `config.toml` монтируется. У `make + failure_checks` уже есть образец отдельного проекта с override + (`student-tests/failures.compose.yml`, `ports: !reset []`). +- Настройки приложения по умолчанию (`src/config/settings.py`): пул + 10 + 5, `pool_timeout` 5 с, `statement_timeout` 5 с, срок сессии + 3600 с, кэш с таймаутом 0,2 с. +- Запрос страницы истории (`get_chat_messages_page`): + `WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY + created_at, id LIMIT $4` по индексу + `ix_messages_chat_id_created_at_id`. asyncpg выполняет его как + prepared statement. +- В закреплённом образе Postgres есть `auto_explain.so` (проверено + `ls /usr/lib/postgresql/18/lib/`). + +## Goals / Non-Goals + +**Goals:** + +- `make bench` и `make bench_quick` работают на коде лабы 2 и меряют + систему в том составе, в котором она развёрнута: API, PostgreSQL, + Valkey. +- План запроса истории — часть каждой метки. Его снимают с того + запроса, который выполнило приложение, а не с копии SQL. +- Метки сравнимы между собой: лимиты, образы и настройки хранилищ + входят в методику и проверяются `make bench_compare`. + +**Non-Goals:** + +- Неравномерные размеры чатов, сравнение ≥2 индексов или запросов, + стоимость записи по вариантам индекса — change `track2-query-plans`. + Здесь читаемый чат один и большой. +- Backup и восстановление — `track2-backup-restore`. +- Изменения `src/`, миграций, контракта и `student-tests/`. +- Настройка Postgres (`shared_buffers` и т.п.): в стенде действуют + настройки образа, как у рабочего стенда. Подбор параметров — не цель + этого change. +- Сравнение с метками лабы 1: другое хранилище — другая методика. + +## Decisions + +### 1. Стенд — отдельный проект compose `mtusi-bench` с override + +Стенд поднимается из того же `docker-compose.yml` под проектом +`mtusi-bench` с override `bench/bench.compose.yml`, по образцу +`make failure_checks`. Override задаёт следующее. + +- **Имена.** `container_name: mtusi-bench-<сервис>` для postgres, + valkey и api; сеть `networks.default.name: mtusi-bench`. Имена + остаются в префиксе `mtusi-bench-*` из `bench.md`. Watcher, снимки + cgroup и k6 (`docker run --network mtusi-bench`) работают по прежним + именам. +- **Без портов на хосте:** `ports: !reset []` у всех сервисов. +- **Без файлов рабочего стенда.** `volumes: !reset []` у `api` и + `migrate` убирает монтирование `config.toml`. Образ для обоих — + `mtusi-messenger:bench`, оркестратор собирает его сам, как сейчас. +- **У api:** `healthcheck: disable: true`, `restart: "no"`, лимиты + `cpus`, `mem_limit` и `memswap_limit` из переменных. +- **У postgres и valkey:** `restart: "no"` и свои лимиты. У postgres + ещё `command: ["postgres", "-c", + "shared_preload_libraries=auto_explain"]` (решение 5). + +Окружение compose собирает оркестратор: + +- `--env-file bench/bench.env` заменяет `.env` рабочего стенда. + Проектный каталог — корень репозитория, и без флага compose прочитал + бы рабочий `.env` для подстановок. В `bench/bench.env` — только + несекретные имена и порты: `POSTGRES_USER`, `POSTGRES_DB`, + `APP__PORT=8080` и т.п. +- `POSTGRES_PASSWORD` и `VALKEY_PASSWORD` генерирует `secrets` на + каждый прогон. Они передаются в окружение процесса `docker compose`, + никуда не пишутся и в паспорт не попадают (решение 7). +- Лимиты и срок сессии приходят из полей `Profile` переменными + `BENCH_*`. Override ссылается на них с `:?`, поэтому без оркестратора + стенд не поднимется. +- Процесс `docker compose` получает собранное окружение, а не + `os.environ`: случайная переменная `POSTGRES_*` из shell пользователя + не попадёт в стенд. + +Все вызовы идут через одну функцию с `-p mtusi-bench` и обоими `-f`. + +На каждый размер: +1. `down -v --remove-orphans` — прежний стенд и volume; +2. `up -d --wait postgres valkey`; +3. `run --rm migrate`; +4. `up -d --no-deps --no-build api`; +5. ожидание `/health/ready` изнутри контейнера, как сейчас. + +`check_free` отказывается стартовать, если остались контейнеры проекта +или `mtusi-bench-k6`, и печатает команду уборки. Уборка в `finally` — +`down -v` и `docker rm -f mtusi-bench-k6`. + +**Альтернативы:** + +- Оставить `docker run` и добавить Postgres и Valkey так же. Тогда пины, + healthcheck, пароль Valkey через `sh -c` и запуск миграций + дублировались бы в `run.py` и расходились бы с compose при обновлении + образа. Требование «тот же пин, что в compose» держалось бы на памяти. +- Рабочий стенд или `make run_docker` — нельзя: спек запрещает трогать + его базу и кэш, а его настройки зависят от `.env`. + +### 2. Лимиты хранилищ и настройки приложения — поля `Profile` + +Новые поля `Profile`. Они одинаковы у `full` и `quick` и пишутся в +`meta.json` вместе с остальными. + +| Поле | Значение | Зачем | +|---|---|---| +| `db_cpus`, `db_memory` | `"4"`, `"3g"` (swap = память) | объект замера — API на 1 CPU, как на лабе 1. Postgres не должен быть первым ограничением: у приложения пул до 15 соединений, то есть до 15 активных процессов БД, а 4 CPU хватает с запасом. Кто упёрся первым, видно по столбцам CPU (решение 6) | +| `cache_cpus`, `cache_memory` | `"2"`, `"512m"` | Valkey выполняет команды в одном потоке, и лимит в 2 CPU не даёт квоте cgroup притормаживать его вместе с фоновыми потоками. Данные ограничивает `maxmemory 64mb` из `valkey.conf`, остальное — запас на процесс | +| `session_ttl_seconds` | `21600` | размер 1M с наполнением идёт до ~40 мин. Срок 3600 с по умолчанию на медленном хосте мог бы истечь посреди прогона и дать 401 | + +Остальные настройки приложения — значения по умолчанию из +`settings.py`: пул 10 + 5, таймауты и кэш. Их видно в паспорте +(`app_env` и версия кода). Postgres работает на настройках образа +(`shared_buffers` 128 МБ и т.д.). Свой `postgresql.conf` не +монтируется: настройки — как у рабочего стенда, отличие одно — +`shared_preload_libraries` (решение 5). + +Что даёт память Postgres при настройках образа. Свои буферы Postgres — +128 МБ, остальное читается через кэш страниц ОС. Кэш страниц входит в +лимит памяти cgroup контейнера. Таблица `messages` на 1M с индексами — +ориентировочно 250–350 МБ, так что в 3 ГБ она помещается целиком +вместе с WAL. Больший лимит без изменения `shared_buffers` результат +не изменит. Настройка Postgres — Non-Goal. + +**Бюджет VM.** Docker Desktop на машине автора — 12 CPU и 7,75 ГиБ. + +| Контейнер | CPU | Память | +|---|---|---| +| API | 1 | 2 ГБ | +| Postgres | 4 | 3 ГБ | +| Valkey | 2 | 0,5 ГБ | +| Итого лимиты | 7 | 5,5 ГБ | + +k6 работает без лимита, порог пометки `generator` — 4 ядра. На k6, ядро +VM и сам Docker остаётся около 2 ГиБ и 5 CPU. Если сумма лимитов +памяти превышает память VM без запаса 1,5 ГиБ (VM уменьшили в +настройках Docker Desktop), лимит перестаёт быть гарантией. Тогда +оркестратор пишет предупреждение в вывод и `host_warnings`, как о swap. + +**Альтернативы:** + +- Тот же 1 CPU у Postgres: уже на `c=10` неясно, кто ограничивает + throughput. +- 2 CPU / 2 ГБ (первый вариант): хватает по оценке, но запас меньше. + Пользователь попросил дать хранилищам больше. +- Без лимитов у хранилищ: тогда их ресурсы зависят от того, что ещё + запущено в VM, и метки разных дней перестают быть сравнимыми. + +### 3. Идентификация в k6: регистрация с паролем, Basic, Bearer + +- `prepare.js` для каждого пользователя: + - генерирует пароль `crypto.randomBytes` (`k6/crypto`); + - регистрирует пользователя с паролем; + - входит по `Authorization: Basic` (`k6/encoding`, UTF-8 base64); + - кладёт токен в `fixture.json` рядом с id. +- `lib.js`: `authHeaders(token)` → `Authorization: Bearer `, как + `Actor.headers()`. `createChat` и `sendMessage` принимают токен + отправителя. `read.js`, `cursors.js`, `tail.js` и новый `explain.js` + читают историю токеном читателя. +- `fixture.json` лежит в рабочем каталоге `.work/`, а его оркестратор + удаляет в `finally`. Сырые итоги k6 (`raw/*.json`) пишутся только + сценариями без `setup()`, поэтому `setup_data` с токенами в них не + попадает. Задача проверки — `grep` по каталогу метки на значения + токенов и паролей после короткого прогона. +- Срок сессии стенда — `session_ttl_seconds` из `Profile` (решение 2). + Логин один на пользователя на размер. KDF (Argon2id, ~11 входов на + размер) в замер не попадает. + +### 4. Обслуживание БД после наполнения: `VACUUM (ANALYZE)` и `CHECKPOINT` + +После последней порции наполнения оркестратор выполняет `VACUUM +(ANALYZE)` по базе стенда, затем `CHECKPOINT`. Обе команды идут через +`docker exec mtusi-bench-postgres psql -U "$POSTGRES_USER" -d +"$POSTGRES_DB"` от пользователя контейнера, без пароля в командной +строке. + +Зачем: + +- после массовой вставки autovacuum и autoanalyze запускаются когда + захотят, в том числе посреди измеряемого прогона. План и время + зависели бы от того, успела ли статистика обновиться; +- явный `VACUUM (ANALYZE)` даёт всем меткам одинаковую статистику и + карту видимости; +- `CHECKPOINT` сбрасывает грязные страницы наполнения до замера, а не + во время первого прогона чтения. + +Это новый пункт «Что не меняется между метками» в `bench.md`. + +**Граница чёрного ящика** (`bench.md`, «Как писать»). Приложение +по-прежнему видит только HTTP от k6. Оркестратор обращается к +PostgreSQL стенда напрямую только для измерения и обслуживания: +- обслуживание (решение 4); +- размеры таблиц; +- включение и выключение `auto_explain`; +- журнал PostgreSQL; +- план без индекса в откатываемой транзакции. + +Данных, видимых приложению, он не меняет. Это исключение записывается в +правило рядом с прежним исключением для `--child` (которое уходит +вместе с `inproc.py`). + +### 5. План запроса истории — `auto_explain` на запросах приложения + +Postgres стенда запускается с `shared_preload_libraries=auto_explain`. +По умолчанию `auto_explain.log_min_duration = -1`, и модуль ничего не +делает: в измеряемых прогонах его нет. Этап «план» идёт после +обслуживания и сбора курсоров, до первого прогона размера. + +1. Маркер начала: `DO $$ BEGIN RAISE LOG 'bench-explain start'; + END $$`. +2. Включение: `ALTER SYSTEM SET auto_explain.log_min_duration = 0`, + `log_analyze = on`, `log_buffers = on`, `log_timing = on`, + `log_format = text`, затем `SELECT pg_reload_conf()`. SIGHUP + применяет настройки и в уже открытых соединениях пула приложения. +3. `k6/explain.js`, 1 VU, три последовательных запроса истории + читаемого чата с `limit` профиля, у каждого проверка 200 и полной + страницы: + - без курсора (первая страница); + - курсор из середины пула; + - последний курсор пула (последняя полная страница). +4. Выключение: `ALTER SYSTEM RESET` тех же параметров, + `pg_reload_conf()`, маркер конца. +5. Разбор `docker logs mtusi-bench-postgres` между маркерами. Записи + `LOG: duration: … plan:` с продолжением по строкам с табуляцией. + Берутся только записи, у которых `Query Text` читает `messages`; + запросы сессии и карточки чата отбрасываются. Записей должно быть + ровно три, в порядке запросов. Иначе — `BenchError` с размером, и + стенд убирается (сценарий «План не найден»). +6. Сравнение без индекса — для средней страницы. Из записи + берутся `Query Text`, `Query Parameters` (Postgres 16+ пишет их по + умолчанию) и имя индекса из узла `Index Scan using <имя>` или + `Index Only Scan` / `Bitmap Index Scan`. В psql (SQL через stdin, не + через shell): + + ```sql + BEGIN; + PREPARE page AS ; + EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(<параметры>); + DROP INDEX <имя>; + EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(<параметры>); + ROLLBACK; + ``` + + Первый `EXPLAIN` — тот же запрос с индексом в той же сессии psql, + чтобы пара отличалась только индексом. `DROP INDEX` берёт `ACCESS + EXCLUSIVE` на `messages` до `ROLLBACK`. Нагрузки в этот момент нет, + пул приложения простаивает. После `ROLLBACK` оркестратор проверяет + по `pg_indexes`, что индекс на месте (сценарий «Индекс остаётся»). + Если план приложения не использовал индекс, сравнения нет, а в + файле и сводке это сказано прямо. +7. Файл `explain-<размер>.txt` (`explain-10k.txt` и т.д.): + - шапка: размер, позиция каждой страницы (`after` из пула курсоров), + commit; + - три плана приложения как есть; + - вывод psql с индексом и без. + + В `summary.md` — раздел «Планы запроса истории»: размер, страница, + узел, `shared hit` / `read`, строки и время. + +**Почему не копия SQL в psql:** + +- копия запроса в `bench/` разошлась бы с + `src/core/repos/message.py` при первой правке, а стенд не может + импортировать `src`; +- запрос с литералами в psql даёт custom plan, а приложение выполняет + prepared statement asyncpg, и после пяти выполнений Postgres может + перейти на generic plan; +- `auto_explain` показывает именно тот план, который получило + приложение, с его параметрами. + +Сравнение без индекса всё равно идёт через psql, но текстом и +параметрами из записи приложения, без копии. Там custom plan — это +отмечается в файле. + +**Почему не `pg_stat_statements`:** он даёт текст и статистику, но не +план и не буферы одного выполнения. + +### 6. Метрики хранилища + +- `Stand.snapshot()` читает ещё `cpu.stat` контейнера + `mtusi-bench-postgres`. Новые столбцы `db_cpu_cores` дописываются в + конец `RUN_FIELDS` и `PREFILL_FIELDS` (`bench.md`: столбцы не + переименовываются, новые — в конце). Строка прогона в терминале + печатает и `db`. +- На размер после обслуживания: `pg_table_size('messages')`, + `pg_indexes_size('messages')`, `count(*)` и `db_bytes_per_message` = + (таблица + индексы) / число строк. На этот момент в таблице ровно N + сообщений читаемого чата: чат записи ещё пуст. Поля идут в + `meta.sizes` и в таблицу «Память и наполнение» сводки рядом с RSS. +- Сторож (`Watcher`) проверяет ещё `Running`, `OOMKilled` и + `RestartCount` контейнеров Postgres и Valkey. Если один из них упал, + прогон получает пометку `stand_down`, матрица останавливается, а + `BenchError` называет контейнер. При падении API, как и раньше, — `oom` + или `app_down`. + +### 7. Паспорт + +`static_passport` пополняется: + +- `stand.postgres`: + - образ из `docker compose config --format json` (тот же пин) и + `Image` контейнера; + - `SHOW server_version`; + - `settings` — значения из `pg_settings`: `shared_buffers`, + `effective_cache_size`, `work_mem`, `maintenance_work_mem`, + `max_connections`, `synchronous_commit`, `fsync`, `wal_level`, + `checkpoint_timeout`, `max_wal_size`, `random_page_cost`, `jit`, + `autovacuum`, `plan_cache_mode`, `shared_preload_libraries`; +- `stand.valkey`: образ, `valkey_version` из `INFO server`, + `maxmemory`, `maxmemory-policy`; +- `limits`: словарь по контейнерам `api`, `postgres`, `valkey`, а не + один словарь API. Значения читаются у запущенных контейнеров, как + сейчас; +- `app_env`: окружение контейнера API из `docker inspect`. Остаются + только ключи в формате настроек (`SECTION__FIELD`), из них удаляются + все, где есть `PASSWORD`; +- версии библиотек образа: к FastAPI, Starlette, pydantic и uvicorn + добавляются SQLAlchemy, asyncpg и redis. + +### 8. `make bench_compare` и `make bench_ab` + +- `methodology()` разворачивает вложенные словари в плоские ключи и + сравнивает: + - `profile.*`; + - `limits.<контейнер>.*`; + - `generator.image`; + - `stand.postgres.image` и `stand.valkey.image`; + - `stand.postgres.settings.*`; + - `stand.app_env.*` (окружение API лежит в паспорте под `stand`). + + Остальное поведение — как в спеке: отказ при различии, «не + проверено» для ключа одной метки. +- Таблица памяти: байты RSS на сообщение и байты на сообщение в БД в + обеих метках. +- `ab.py`: шаги без `bench_inproc`, `git add` только + `evidence/bench/`, проверка занятости — только каталог метки + стенда. +- Совместимость с метками лабы 1 не нужна: их в этом репозитории нет. + +### 9. Удаление `inproc.py` + +Удаляются `bench/inproc.py`, цель `bench_inproc`, строка +`evidence/profile/quick-*.txt` в `.gitignore` и раздел «Диагностика» в +`bench.md`. Упоминания уходят из `AGENTS.md` (команды, карта кода). +Скрипт остаётся в `7b775a2` (Migration в дельте спека). Формат времени, +который он сверял, проверяют `make test` и `student-tests` (`contract.py` +проверяет `created_at` по HTTP). + +### 10. Базовый замер и гипотезы + +Порядок: +1. Код стенда закоммичен после подтверждения пользователя. +2. `make bench_quick` проверяет стенд: метка `quick-*` в git не идёт. +3. Хост подготовлен (`bench.md`, «Результаты»). +4. С согласия пользователя запускается `make bench BENCH_LABEL=baseline`. +5. Доказательства коммитятся после подтверждения. +6. Числа и планы переносятся в `REPORT.md`. + +Гипотезы записываются в `REPORT.md` до запуска полной матрицы. По +`bench.md` результат пишется как получился: + +- **H1.** p50 чтения при той же конкуренции не растёт с 10k до 1M + больше чем на величину шума: страница — keyset по индексу. + `Buffers` средней и последней страницы того же порядка, что у первой, + на всех размерах. +- **H2.** Без индекса тот же запрос — `Seq Scan` и сортировка, буферы — + порядка размера таблицы, время растёт линейно с N. +- **H3.** На `c=10` и `c=50` чтение и запись упираются в CPU API + (`app_cpu_cores` ≈ 1), а Postgres загружен меньше (`db_cpu_cores`). +- **H4.** Скорость записи на кривой наполнения до 1M падает слабо: + глубина B-дерева растёт логарифмически. + +## Risks / Trade-offs + +- [`auto_explain` не запишет план: настройка не дошла до соединения + пула или формат журнала другой] → маркеры начала и конца, ровно три + ожидаемые записи, иначе отказ с размером. Первая задача реализации — + проба на `bench_quick` до остального. +- [Наполнение 1M через HTTP идёт дольше оценки (15–25 мин): запись — + это ещё проверка сессии, вставка и commit с fsync на диске VM Docker] + → ETA в выводе пересчитывается по факту. Если полная матрица + выходит заметно дольше часа, сказать пользователю до baseline, а не + менять методику молча. +- [Рабочие наборы 1M (таблица ~250–350 МБ с индексами) больше + `shared_buffers` 128 МБ: часть чтений идёт из кэша ОС внутри лимита + 3 ГБ контейнера] → это свойство стенда, видно по `shared read` в + планах. Прогрев перед каждым прогоном и одинаковое обслуживание + делают его одинаковым у меток. В ограничениях отчёта сказано, что + настройки Postgres — по умолчанию. +- [Один большой читаемый чат: селективность `chat_id` около 100%, план + может отличаться от плана при многих маленьких чатах] → в отчёте + это ограничение. Неравномерные чаты — `track2-query-plans`. +- [План приложения может быть generic, а сравнение в psql — custom] → + тип плана видно в выводе. В файле планов это отмечено, сравнение + «с индексом / без» идёт внутри одной сессии psql. +- [`DROP INDEX` в откатываемой транзакции блокирует `messages`] → только + на стенде, между прогонами, без нагрузки. После `ROLLBACK` индекс + проверяется. +- [`shared_preload_libraries=auto_explain` — отличие от рабочего + Postgres] → при `log_min_duration = -1` модуль ничего не делает. Оно + записано в паспорте (`settings.shared_preload_libraries`) и в спеке. +- [Сырые итоги 54 прогонов и ~25 порций наполнения в git] → как на + лабе 1, это килобайты на файл. `quick-*` в `.gitignore`. +- [Шум хоста macOS / Docker Desktop] → прежние меры `bench.md`: + состояние хоста в паспорте, A/A для уровня шума при сравнениях + трека 2. + +## Migration Plan + +Развёртывания нет: меняется только инструмент `bench/` и документация. +Порядок — по `tasks.md`: сначала проба `auto_explain`, затем стенд и k6, +`bench_quick`, коммит кода, `baseline`, отчёт. Откат — `git revert` +коммитов change. Рабочий стенд и его volume не затрагиваются ни на +одном шаге. diff --git a/openspec/changes/bench-postgres/proposal.md b/openspec/changes/bench-postgres/proposal.md new file mode 100644 index 00000000..9805c1ff --- /dev/null +++ b/openspec/changes/bench-postgres/proposal.md @@ -0,0 +1,109 @@ +# Proposal + +## Why + +Уровень «4» требует обосновать индекс истории запросом и +`EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях и показать, что +пагинация не просматривает всю историю на каждую страницу (`README.md`). +Наполнить такую историю и снять план должен нагрузочный стенд `bench/`, +но он перенесён из лабы 1 и на коде лабы 2 не работает: + +- `run.py` поднимает только контейнер API, без PostgreSQL, Valkey и + миграций; +- сценарии k6 ходят с `X-User-Id`, которого API больше не принимает; +- `inproc.py` собирает приложение над удалённым `MemoryStore`. + +Трек «5» №2 (`track2-query-plans`, `track2-backup-restore`) тоже стоит +на этом стенде: сравнение индексов и стоимости записи — это метки +`make bench`, а метки лабы 1 сюда не переносились. Поэтому сначала +стенду нужны базовый замер на PostgreSQL и план запроса истории. + +## What Changes + +- **Стенд на PostgreSQL.** `make bench` поднимает свой проект compose + `mtusi-bench` из того же `docker-compose.yml` с override: + - PostgreSQL и Valkey с теми же пинами и конфигурацией, что у рабочего + стенда, со своими лимитами CPU и памяти; + - миграции до наполнения; + - API с прежними лимитами (1 CPU, 2 ГБ без swap); + - без портов на хосте, без `.env` и `config.toml` рабочего стенда. + + Каждый размер истории начинается со свежего стенда: новый volume + Postgres, новые Valkey и API. Рабочий стенд, его база и кэш не + затрагиваются. +- **Идентификация как в контракте.** Сценарии k6 регистрируют + пользователей с паролем, входят по Basic и шлют Bearer. Срок сессии + стенда больше длительности размера. +- **Обслуживание БД перед замером.** После наполнения — `VACUUM + (ANALYZE)` и `CHECKPOINT`: статистика планировщика и состояние таблицы + одинаковы у всех меток. +- **План запроса истории.** На каждом размере стенд снимает + `EXPLAIN (ANALYZE, BUFFERS)` того запроса страницы истории, который + выполняет само приложение (`auto_explain` в Postgres стенда), для + первой, средней и последней страницы. Для сравнения снимается тот же + запрос без использованного индекса, в транзакции, которая + откатывается. Планы лежат в каталоге метки, сводка — в `summary.md`. +- **Метрики хранилища.** Новые столбцы в конце таблиц: CPU контейнера + Postgres на прогон и порцию наполнения. На размер — объём таблицы и + индексов `messages` и байты на сообщение. В паспорт идут образы, + версии, лимиты и настройки Postgres и Valkey, а также окружение API + без секретов. Пароли стенда генерируются на прогон и никуда не + пишутся. +- **BREAKING (инструменты стенда):** удаляются `bench/inproc.py` и цель + `make bench_inproc`. Разложение времени внутри процесса было + инструментом трека 1 лабы 1. На PostgreSQL время запроса уходит в + основном в БД, и его объясняет план запроса. `make bench_ab` снимает + только стенд. +- `make bench_compare` проверяет методику по лимитам всех контейнеров, + образам и настройкам Postgres и Valkey. Таблица памяти показывает + байты на сообщение в БД. +- **Базовый замер** `baseline` полной матрицы (10k, 100k, 1M) на + закоммиченном коде. По нему в `REPORT.md` пишутся раздел экспериментов + и строка уровня 4 «индекс истории и EXPLAIN». + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `load-benchmark`: + - изменённые требования: + - стенд из API, PostgreSQL и Valkey с миграциями, лимитами и + свежим volume на каждый размер; + - идентификация Bearer в сценариях; + - обслуживание БД после наполнения; + - метрики Postgres; + - паспорт со сведениями о хранилищах; + - пометка прогона при падении хранилища; + - проверка методики в сравнении меток; + - прогоны «до/после» без разложения; + - базовый замер на PostgreSQL; + - новое требование: план запроса истории; + - удалено требование: «Разложение стоимости запроса». + +## Impact + +- **Код стенда:** + - `bench/run.py` — стенд через compose, обслуживание БД, план, + метрики, паспорт; + - новый `bench/bench.compose.yml`, новый `bench/bench.env`; + - `bench/k6/` — `lib.js`, `prepare.js`, сценарии, новый `explain.js`; + - `bench/compare.py`, `bench/ab.py`; + - удаляется `bench/inproc.py`. +- **Makefile:** цели `bench*`, удаляется `bench_inproc`. +- **Код приложения (`src/`), миграции, контракт и тесты** не меняются. +- **Документация:** + - `.gitignore` (строки `evidence/profile`); + - `.claude/rules/bench.md` — раздел «Что доработать» закрывается, + «Что не меняется между метками» пополняется параметрами хранилищ, + раздел о диагностике удаляется; + - `AGENTS.md` — команды, карта кода, переходное состояние; + - `REPORT.md` — эксперименты, уровень 4, ограничения. +- **Доказательства:** `evidence/bench/baseline/`, включая + `explain-<размер>.txt`. +- **Время хоста:** полная матрица на PostgreSQL — ориентировочно около + часа (не измерено). Запуск — только с согласия пользователя и после + подготовки хоста (`bench.md`, «Результаты»). diff --git a/openspec/changes/bench-postgres/specs/load-benchmark/spec.md b/openspec/changes/bench-postgres/specs/load-benchmark/spec.md new file mode 100644 index 00000000..1e876509 --- /dev/null +++ b/openspec/changes/bench-postgres/specs/load-benchmark/spec.md @@ -0,0 +1,539 @@ +## ADDED Requirements + +### Requirement: Идентификация в сценариях + +Запросы стенда SHALL идентифицироваться так, как требует контракт. +Пользователи стенда регистрируются с паролем и получают сессию входом +по Basic. Создание чатов, отправка сообщений и чтение истории идут с +Bearer-токеном этой сессии. Срок сессии стенда SHALL быть больше +длительности одного размера матрицы. Пароли пользователей и токены +MUST NOT сохраняться в результатах. + +#### Scenario: Запросы с Bearer + +- **WHEN** выполняется любой сценарий стенда +- **THEN** запросы к API идут с `Authorization: Bearer`, без + `X-User-Id`, и ни один ответ не 401 + +#### Scenario: Сессия не истекает за размер + +- **WHEN** размер 1 000 000 от наполнения до последнего прогона идёт + дольше часа +- **THEN** ответов 401 в его прогонах нет + +#### Scenario: Секретов стенда нет в результатах + +- **WHEN** прогон завершён, в том числе с ошибкой или по Ctrl+C +- **THEN** в каталоге метки нет паролей и токенов пользователей стенда + и паролей его хранилищ + +### Requirement: План запроса истории + +Для каждого размера, после обслуживания БД и до измеряемых прогонов, +стенд SHALL сохранять в каталоге метки вывод `EXPLAIN (ANALYZE, +BUFFERS)` запроса страницы истории читаемого чата с `limit` профиля. +Это SHALL быть тот запрос и те параметры, которые выполнило само +приложение при обработке HTTP-запроса. Планы снимаются для трёх +страниц: +- первой; +- из середины истории; +- последней полной. + +Для страницы из середины SHALL сохраняться и план того же запроса с +теми же параметрами без индекса, который использовал план приложения. +Индекс при этом MUST NOT пропадать для приложения и следующих прогонов. + +Сводка метки SHALL показывать по каждому плану: +- узел доступа к таблице сообщений; +- число прочитанных страниц: из кэша и с диска; +- время выполнения. + +Если план запроса приложения не найден, команда SHALL завершаться с +ненулевым кодом и называть размер. + +#### Scenario: Планы на каждом размере + +- **WHEN** размер N наполнен и обслужен +- **THEN** в каталоге метки есть файл планов размера N: первая, средняя + и последняя полная страница и средняя страница без индекса + +#### Scenario: Запрос самого приложения + +- **WHEN** проверяющий открывает файл планов +- **THEN** в нём текст запроса и параметры, с которыми его выполнило + приложение, план с фактическим временем, числом строк и буферами + каждого узла + +#### Scenario: Индекс остаётся + +- **WHEN** снят план без индекса +- **THEN** индекс по-прежнему есть в базе стенда, и следующие прогоны + идут при той же схеме + +#### Scenario: План не найден + +- **WHEN** в окне снятия плана приложение не выполнило запрос истории + или его план не попал в журнал PostgreSQL +- **THEN** команда завершается с ненулевым кодом, называет размер, а + стенд удаляется + +## MODIFIED Requirements + +### Requirement: Запуск одной командой + +Полная матрица SHALL запускаться командой `make bench` с меткой +результата `BENCH_LABEL` (по умолчанию `baseline`), короткий прогон — +командой `make bench_quick`. Результаты SHALL сохраняться в +`evidence/bench/<метка>/`. Команда MUST NOT перезаписывать результаты +существующей метки. Она MUST NOT использовать порт 8080 хоста и MUST +NOT трогать контейнеры, базу и кэш рабочего стенда (`make run_dev` / +`make run_docker`). После завершения, в том числе с ошибкой или по +Ctrl+C, контейнеры, сеть и volume стенда SHALL удаляться. + +#### Scenario: Полная матрица + +- **WHEN** выполняется `make bench BENCH_LABEL=baseline` +- **THEN** прогоняется вся матрица, результаты лежат в + `evidence/bench/baseline/`, код выхода 0 + +#### Scenario: Метка уже занята + +- **WHEN** каталог `evidence/bench/<метка>/` уже существует +- **THEN** команда завершается с ненулевым кодом до запуска стенда и + называет каталог + +#### Scenario: Рабочий стенд не затронут + +- **WHEN** во время прогона запущен `make run_docker` на 8080 +- **THEN** он продолжает отвечать, а его контейнеры, база и кэш не + меняются + +#### Scenario: Прерывание + +- **WHEN** прогон прерван Ctrl+C +- **THEN** контейнеры, сеть и volume стенда удалены, частичные + результаты помечены как незавершённые + +### Requirement: Фиксированный стенд + +Стенд SHALL состоять из приложения, PostgreSQL и Valkey. Приложение +SHALL запускаться в контейнере из образа, собранного из текущего +checkout тем же `Dockerfile`. PostgreSQL и Valkey SHALL запускаться из +тех же образов, что у рабочего стенда. Valkey получает ту же +конфигурацию. PostgreSQL получает те же настройки образа плюс модуль +записи планов, выключенный вне снятия плана. Схема БД SHALL +применяться миграциями до наполнения. + +Лимиты SHALL быть одинаковыми во всех прогонах: +- у приложения — 1 CPU и 2 ГБ памяти без swap; +- у PostgreSQL и Valkey — свои лимиты CPU и памяти без swap, заданные + методикой. + +Healthcheck образа приложения SHALL быть отключён. Порты стенда на хост +MUST NOT публиковаться. Настройки приложения и хранилищ SHALL браться +из методики стенда, а не из `.env` и `config.toml` рабочего стенда. +Пароли хранилищ SHALL генерироваться на прогон. Генератор нагрузки SHALL +работать в той же docker-сети и обращаться к приложению по имени +контейнера, минуя проброс портов хоста. + +#### Scenario: Лимиты в паспорте + +- **WHEN** прогон завершён +- **THEN** паспорт стенда содержит лимиты CPU и памяти контейнеров + приложения, PostgreSQL и Valkey, прочитанные у запущенных + контейнеров, и они одинаковы для всех размеров + +#### Scenario: Нехватка памяти + +- **WHEN** процесс приложения превысил лимит памяти и был убит +- **THEN** прогон помечен как проваленный из-за OOM, а не записан как + обычный результат + +#### Scenario: Настройки рабочего стенда не влияют + +- **WHEN** `.env` и `config.toml` рабочего стенда изменены или + отсутствуют +- **THEN** стенд запускается с теми же настройками приложения и + хранилищ, а окружение приложения в паспорте то же + +#### Scenario: Схема до наполнения + +- **WHEN** начинается наполнение размера +- **THEN** миграции применены до последней ревизии, и приложение + отвечает готовностью + +### Requirement: Матрица и повторы + +Полная матрица SHALL включать размеры истории 10 000, 100 000 и +1 000 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных +клиентов и оба сценария, по 3 измеряемых прогона на ячейку. Перед +каждым измеряемым прогоном SHALL идти прогрев с той же нагрузкой, не +входящий в результат. + +Каждый размер SHALL начинаться со свежего стенда: +- новый процесс приложения; +- пустая база на новом volume с применёнными миграциями; +- пустой кэш. + +Стенд наполняется через HTTP API до ровно N сообщений в читаемом чате. +После наполнения, до сбора курсоров и первого прогона, SHALL +выполняться обслуживание БД: очистка и сбор статистики планировщика по +таблицам, затем контрольная точка. Так состояние таблиц и статистика +не зависят от того, когда сработали фоновые процессы БД. Рост +хранилища за прогоны `write` SHALL фиксироваться в результатах. + +#### Scenario: Состав матрицы + +- **WHEN** полная матрица завершена +- **THEN** в результатах 54 измеряемых прогона: 3 размера × 3 уровня + конкуренции × 2 сценария × 3 повтора + +#### Scenario: Свежий процесс на каждый размер + +- **WHEN** начинается размер N +- **THEN** контейнеры приложения, PostgreSQL и Valkey запущены заново, + volume базы новый, и перед первым прогоном в читаемом чате ровно N + сообщений + +#### Scenario: Обслуживание после наполнения + +- **WHEN** наполнение размера N завершено +- **THEN** до сбора курсоров выполнены очистка и сбор статистики + таблиц, затем контрольная точка, и это видно в выводе команды + +### Requirement: Метрики прогона + +Для каждого измеряемого прогона SHALL сохраняться: +- сценарий, размер истории, конкуренция, номер повтора, длительность; +- число успешных и неуспешных запросов, успешные RPS, доля ошибок; +- задержки p50, p95, p99 и max успешных запросов; +- потреблённое приложением CPU; +- RSS процесса приложения в начале, в конце и максимальный за прогон; +- число сообщений в хранилище в начале и в конце; +- загрузка CPU генератора и CPU контейнера PostgreSQL. + +Для каждого размера SHALL сохраняться: +- RSS приложения до и после наполнения; +- объём таблицы сообщений и её индексов после обслуживания БД; +- байты на сообщение в БД. + +Наполнение SHALL идти порциями. Для каждой порции SHALL сохраняться: +- размер и число сообщений в хранилище до и после; +- успешные RPS и доля ошибок; +- задержки p50, p95, p99 и max; +- CPU приложения и CPU PostgreSQL; +- RSS в конце порции. + +Так наполнение до 1 000 000 даёт кривую «запись при росте хранилища» +без дополнительного времени прогона. Новые метрики SHALL добавляться +новыми столбцами в конце таблиц. Прежние столбцы MUST NOT +переименовываться и удаляться. + +#### Scenario: Строка прогона + +- **WHEN** проверяющий открывает таблицу прогонов +- **THEN** у каждой строки заполнены все перечисленные поля + +#### Scenario: Память на сообщение + +- **WHEN** наполнение размера N завершено +- **THEN** в результатах есть прирост RSS приложения за наполнение, + объём таблицы и индексов сообщений и байты на сообщение в БД + +#### Scenario: Кривая наполнения + +- **WHEN** наполнение размера 1 000 000 завершено +- **THEN** в таблице наполнения есть строка на каждую порцию, от + пустого хранилища до 1 000 000 сообщений, с RPS, p95, p99, max, CPU + приложения и PostgreSQL и RSS + +### Requirement: Достоверность прогона + +Прогон SHALL помечаться в результатах, если его данные нельзя считать +замером сервера: +- процесс приложения перезапускался или был убит; +- контейнер PostgreSQL или Valkey перезапускался, был убит или + остановлен; +- генератор нагрузки был загружен настолько, что мог сам ограничивать + throughput; +- доля ошибок больше нуля. + +Сводка SHALL показывать эти пометки рядом со значениями. + +#### Scenario: Генератор упёрся в CPU + +- **WHEN** загрузка CPU генератора за прогон выше порога, заданного в + методике +- **THEN** прогон помечен, и в сводке рядом с его ячейкой видна пометка + +#### Scenario: Хранилище упало + +- **WHEN** во время прогона контейнер PostgreSQL или Valkey был убит + или перезапущен +- **THEN** прогон помечен, матрица останавливается, и команда называет + контейнер + +### Requirement: Ход прогона виден + +Во время прогона команда SHALL печатать строку на каждый этап с +временем от начала. Этапы: +- сборка образа и запуск стенда; +- миграции; +- наполнение; +- обслуживание БД; +- снятие плана; +- сбор курсоров; +- каждый измеряемый прогон. + +Наполнение SHALL показывать прогресс не реже раза в минуту: сколько +сообщений из N, скорость, оценку оставшегося времени. После каждого +измеряемого прогона SHALL печататься: +- его номер из общего числа и ячейка матрицы; +- основные результаты: RPS, p50, p95, p99, CPU приложения, RSS, доля + ошибок; +- пометки и оценка времени до конца матрицы. + +В каталоге метки SHALL поддерживаться файл текущего состояния, а строка +прогона SHALL дописываться в таблицу прогонов сразу после прогона. + +#### Scenario: Где мы сейчас + +- **WHEN** идёт наполнение размера 1M +- **THEN** в выводе не реже раза в минуту появляется строка с числом + отправленных сообщений, скоростью и оценкой оставшегося времени + +#### Scenario: Результат сразу после прогона + +- **WHEN** завершился измеряемый прогон +- **THEN** в выводе появляется строка вида «прогон k из 54, сценарий, + размер, конкуренция, повтор: RPS, p50/p95/p99, CPU, RSS, ошибки, + пометки, осталось ~T», а в таблице прогонов — его строка + +#### Scenario: Наблюдение из другого терминала + +- **WHEN** прогон запущен, и пользователь открывает файл состояния в + каталоге метки +- **THEN** там текущий этап, число завершённых прогонов из общего, + оценка оставшегося времени и результат последнего прогона + +#### Scenario: Частичные результаты + +- **WHEN** прогон прерван на середине матрицы +- **THEN** строки уже завершённых прогонов есть в таблице прогонов + +### Requirement: Сохранение результатов + +В каталоге метки SHALL лежать: +- сырой результат генератора для каждого прогона и каждой порции + наполнения; +- таблица всех прогонов в CSV; +- таблица порций наполнения в CSV; +- планы запроса истории по размерам; +- сводка по ячейкам матрицы (медиана и разброс min–max по повторам) и + по планам в Markdown; +- паспорт стенда; +- состояние хоста в начале и в конце прогона: занятый swap, доля + свободной памяти, питание от сети или от батареи. + +Паспорт стенда SHALL содержать: +- дату, commit и признак незакоммиченных изменений; +- digest образа приложения и версии его библиотек; +- образы и версии PostgreSQL и Valkey; +- настройки PostgreSQL, от которых зависят план запроса и стоимость + записи; +- окружение приложения без паролей; +- версии генератора и Python; +- лимиты всех контейнеров стенда; +- железо хоста и VM; +- параметры профиля и команду запуска. + +Если в начале прогона хост работает от батареи или swap занят сверх +порога методики, команда SHALL предупреждать об этом в выводе и в +паспорте, но не прерываться. Данные MUST быть синтетическими. +Результаты MUST NOT содержать секретов (паролей и токенов стенда), +`.env` и абсолютных путей домашнего каталога. + +#### Scenario: Повтор на другой машине + +- **WHEN** другой человек берёт паспорт и команду из каталога метки +- **THEN** он может запустить тот же профиль на своём checkout и + сравнить таблицы по тем же столбцам + +#### Scenario: Условия хоста для сравнения меток + +- **WHEN** проверяющий сравнивает две метки +- **THEN** по паспортам видно, одинаковы ли были swap, свободная + память и питание хоста в начале и в конце каждого прогона + +#### Scenario: Неподходящий хост + +- **WHEN** прогон запускается от батареи или с занятым swap выше порога +- **THEN** вывод команды и паспорт содержат предупреждение, а прогон + продолжается + +#### Scenario: Хранилища в паспорте + +- **WHEN** проверяющий открывает паспорт метки +- **THEN** в нём образы и версии PostgreSQL и Valkey, их лимиты, + настройки PostgreSQL и окружение приложения, а паролей нет + +### Requirement: Базовый замер в отчёте + +Результат полной матрицы текущего кода на PostgreSQL SHALL быть +сохранён под меткой `baseline`. `REPORT.md` SHALL описывать в разделе +экспериментов: +- гипотезы; +- стенд и лимиты всех контейнеров; +- профиль нагрузки; +- результаты по ячейкам со ссылкой на каталог + `evidence/bench/baseline/`; +- ограничения замера. + +Индекс истории SHALL обосновываться в `REPORT.md` планами из этой +метки на размерах от 10 000 сообщений. Для этого приводятся: +- запрос; +- узел доступа, буферы и время для первой, средней и последней + страницы; +- тот же запрос без индекса. + +#### Scenario: Проверяющий читает отчёт + +- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md` +- **THEN** в нём есть гипотезы, условия стенда, таблица результатов и + путь к сырым данным + +#### Scenario: Обоснование индекса истории + +- **WHEN** проверяющий ищет в `REPORT.md` обоснование индекса истории +- **THEN** он находит запрос и `EXPLAIN (ANALYZE, BUFFERS)` на + ≥10 000 сообщениях для разных позиций курсора и сравнение без + индекса, со ссылками на файлы планов метки `baseline` + +### Requirement: Сравнение двух меток + +Команда `make bench_compare BEFORE=<метка> AFTER=<метка>` SHALL +сравнивать результаты двух меток полной матрицы и сохранять таблицу в +`evidence/compare/<до>__<после>.md`. Для каждой ячейки матрицы таблица +SHALL содержать: +- медиану и разброс min–max повторов RPS в обеих метках; +- изменение медианы в процентах; +- медианы p50, p95 и p99; +- CPU приложения на один запрос. + +Для каждого размера истории таблица SHALL содержать байты RSS на +сообщение и байты на сообщение в БД в обеих метках. + +Команда SHALL отказываться сравнивать метки, снятые разной методикой. +Если различаются параметры профиля, лимиты любого контейнера стенда, +образы генератора, PostgreSQL или Valkey, настройки PostgreSQL или +окружение приложения, она завершается с ненулевым кодом, называет +различие и не создаёт таблицу. Параметр, записанный в паспорте только +одной из меток, SHALL перечисляться в таблице как непроверенный, без +отказа. В начале таблицы SHALL перечисляться незавершённая метка, +незакоммиченные изменения, предупреждения о хосте и помеченные +прогоны. + +С необязательным параметром `AA=<метка>` команда SHALL оценивать +уровень шума: наибольшее по ячейкам сценария изменение медианы RPS +между метками `AA` и `BEFORE`, снятыми на одном и том же коде +приложения. Изменение в ячейке SHALL называться эффектом, только если +разбросы повторов двух меток не пересекаются и изменение медианы +больше уровня шума её сценария. Иначе это изменение в пределах шума. + +#### Scenario: Сравнимые метки + +- **WHEN** сравниваются две завершённые метки одного профиля с + одинаковыми лимитами, образами и настройками +- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня + конкуренции) с медианами, разбросом и изменением в процентах, а в + начале — commit и условия хоста каждой метки + +#### Scenario: Разная методика + +- **WHEN** у меток различается параметр профиля, лимит контейнера, + образ генератора или хранилища, настройка PostgreSQL или переменная + окружения приложения +- **THEN** команда завершается с ненулевым кодом, называет параметр и + оба значения, таблица не создаётся + +#### Scenario: Параметр только в одной метке + +- **WHEN** параметр профиля записан в паспорте одной метки и отсутствует + в паспорте другой +- **THEN** сравнение выполняется, а параметр назван в таблице как + непроверенный + +#### Scenario: Уровень шума + +- **WHEN** задан `AA` — метка того же кода приложения, что и `BEFORE` +- **THEN** таблица содержит уровень шума по каждому сценарию и для + каждой ячейки вывод: эффект или изменение в пределах шума + +#### Scenario: Метка сама с собой + +- **WHEN** `BEFORE` и `AFTER` — одна и та же метка +- **THEN** изменение во всех ячейках равно нулю + +### Requirement: Прогоны «до» и «после» подряд + +Команда `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=` +SHALL снимать метки «до» и «после» одного изменения подряд, без работы +на хосте между ними. В рабочем дереве лежит код «до», а изменение +закоммичено и откачено отдельным commit; `REAPPLY` — commit отката. +Команда SHALL выполнить по порядку: +1. полную матрицу для `BEFORE`; +2. commit её результатов; +3. возврат изменения новым commit; +4. полную матрицу для `AFTER`. + +Команда SHALL отказываться стартовать, ничего не запустив, если: +- рабочее дерево не чистое; +- каталог одной из меток уже существует; +- метки совпадают; +- commit `REAPPLY` не найден в текущей ветке. + +Если шаг завершился с ошибкой, следующие шаги MUST NOT выполняться, а +команда SHALL назвать этот шаг. Команда создаёт commit в текущей ветке +и MUST NOT отправлять его в удалённый репозиторий. + +#### Scenario: Оба прогона без участия человека + +- **WHEN** на чистом рабочем дереве выполняется `make bench_ab` со + свободными метками и commit отката +- **THEN** обе метки сняты полностью, у обеих в паспорте нет признака + незакоммиченных изменений, а код приложения между их commit + отличается возвращённым изменением + +#### Scenario: Нечистое рабочее дерево + +- **WHEN** в рабочем дереве есть незакоммиченные изменения +- **THEN** команда завершается с ненулевым кодом до первого шага и + называет причину + +#### Scenario: Метка занята + +- **WHEN** каталог метки стенда одной из меток уже существует +- **THEN** команда завершается с ненулевым кодом до первого шага и + называет путь + +#### Scenario: Шаг завершился с ошибкой + +- **WHEN** один из шагов вернул ненулевой код +- **THEN** следующие шаги не выполняются, команда называет номер шага + и завершается с ненулевым кодом + +## REMOVED Requirements + +### Requirement: Разложение стоимости запроса + +**Reason**: инструмент трека 1 лабы 1 вызывал приложение над +`MemoryStore`, которого на лабе 2 нет. На PostgreSQL время запроса +уходит в основном в БД. Куда оно уходит, объясняет план запроса +(требование «План запроса истории»), а CPU приложения и PostgreSQL +видны в метриках прогона. + +**Migration**: `bench/inproc.py` и цель `make bench_inproc` удаляются, +`make bench_ab` снимает только стенд. Скрипт остаётся в истории git +(`git show 7b775a2:bench/inproc.py`), если разложение понадобится на +следующих лабах. Формат времени по-прежнему проверяют `make test` и +`student-tests` по HTTP. diff --git a/openspec/changes/bench-postgres/tasks.md b/openspec/changes/bench-postgres/tasks.md new file mode 100644 index 00000000..70d312d9 --- /dev/null +++ b/openspec/changes/bench-postgres/tasks.md @@ -0,0 +1,221 @@ +# 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` + +- [x] 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 + +- [x] 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` не правится). +- [x] 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 + +- [x] 3.1 `bench/k6/lib.js` и `prepare.js` (решение 3): + - `authHeaders(token)` — Bearer; + - регистрация с паролем из `crypto.randomBytes`, вход по Basic; + - токены в `fixture.json`; + - `createChat` и `sendMessage` с токеном. +- [x] 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. Обслуживание БД и метрики хранилища + +- [x] 4.1 Обслуживание после наполнения (решение 4): `VACUUM (ANALYZE)` + и `CHECKPOINT` через `docker exec … psql` от пользователя контейнера, + строка этапа в выводе. Затем размеры таблицы и индексов `messages`, + `count(*)`, `db_bytes_per_message` в `meta.sizes` и в сводку. + Проверка: в выводе короткого прогона строки этапов идут по порядку + наполнение → обслуживание → курсоры. В `meta.json` у каждого размера + поля объёма заполнены, `count(*)` = N. +- [x] 4.2 `db_cpu_cores` в конце `RUN_FIELDS` и `PREFILL_FIELDS`, `db` в + строке прогона (решение 6). Проверка: в `runs.csv` и `prefill.csv` + прежние столбцы на месте и в том же порядке, новый — последним и + заполнен. +- [x] 4.3 Сторож Postgres и Valkey: пометка `stand_down`, остановка + матрицы с именем контейнера (решение 6). Проверка: `docker kill + mtusi-bench-postgres` во время прогона чтения короткого профиля — + прогон помечен, команда называет контейнер, код ≠ 0, стенд убран. + +## 5. План запроса истории + +- [x] 5.1 `bench/k6/explain.js`: первая страница, середина и последний + курсор пула, проверка 200 и полной страницы. +- [x] 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. Паспорт и сравнение меток + +- [x] 6.1 Паспорт (решение 7): + - `stand.postgres`: образ, версия, настройки; + - `stand.valkey`: образ, версия, `maxmemory`; + - `limits` по трём контейнерам; + - `app_env` без `PASSWORD`; + - версии SQLAlchemy, asyncpg и redis. + + Проверка: в `meta.json` короткого прогона поля заполнены, `grep -i + password` по каталогу метки находит только имена ключей, не значения. +- [x] 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 + +- [x] 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. Проверка стенда и коммит кода + +- [x] 8.1 `make lint`. Проверка: без замечаний. +- [x] 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. Документация + +- [x] 9.1 `.claude/rules/bench.md`: + - раздел «Что доработать под лабу 2» убрать; + - в «Что не меняется между метками» — лимиты и образы Postgres и + Valkey, настройки Postgres образа с `auto_explain`, окружение + приложения из override, обслуживание после наполнения; + - в «Как писать» — граница чёрного ящика для Postgres стенда + (решение 4) вместо исключения `--child`; + - раздел «Диагностика» удалить; + - таблица инструментов без `inproc.py`. + + Проверка: правило не упоминает `MemoryStore`, `X-User-Id` и + `bench_inproc`. +- [x] 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` + есть. + + Предупреждение о хосте — переснять, а не игнорировать. +- [ ] 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` проходит.