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:
+77
-65
@@ -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
@@ -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.
|
||||
|
||||
@@ -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 # найденные попутно дефекты, не исправленные без просьбы
|
||||
```
|
||||
|
||||
@@ -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
@@ -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}"],
|
||||
]
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
@@ -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
@@ -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
@@ -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),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-02
|
||||
@@ -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 не затрагиваются ни на
|
||||
одном шаге.
|
||||
@@ -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.
|
||||
@@ -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` проходит.
|
||||
Reference in New Issue
Block a user