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 <noreply@anthropic.com>
This commit is contained in:
2026-10-02 01:21:15 +03:00
co-authored by Claude Opus 5.5
parent 5582302d68
commit e76eed789f
23 changed files with 2443 additions and 1084 deletions
+77 -65
View File
@@ -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` не переименовываются и не
удаляются: по ним сравниваются метки. Новая метрика — новый столбец
в конце.
+1 -2
View File
@@ -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.
+12 -15
View File
@@ -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_<db>` с 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=<commit>` | «до» и «после» одного изменения подряд (~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=<commit>` | «до» и «после» одного изменения подряд (два прогона `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 # найденные попутно дефекты, не исправленные без просьбы
```
+8 -13
View File
@@ -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:
+9 -19
View File
@@ -3,10 +3,11 @@
Запуск — `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`.
В рабочем дереве должен лежать код «до», а изменение — быть
закоммиченным и откаченным отдельным 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}"],
]
+52
View File
@@ -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
+11
View File
@@ -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
+41 -13
View File
@@ -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
-845
View File
@@ -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:]))
+3 -1
View File
@@ -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),
};
}
+49
View File
@@ -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 {};
}
+28 -9
View File
@@ -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),
},
);
+5 -1
View File
@@ -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) {
+15 -8
View File
@@ -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),
};
}
+1 -1
View File
@@ -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),
};
+1 -1
View File
@@ -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;
+5 -1
View File
@@ -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) {
+815 -90
View File
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-02
+439
View File
@@ -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 <token>`, как
`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 <uuid> 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 <Query Text>;
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/<BEFORE>`, проверка занятости — только каталог метки
стенда.
- Совместимость с метками лабы 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 не затрагиваются ни на
одном шаге.
+109
View File
@@ -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`, «Результаты»).
@@ -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=<commit>`
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.
+221
View File
@@ -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` проходит.