Files
mtusi2026lab2/openspec/changes/bench-postgres/proposal.md
T
ricoromaandClaude Opus 5.5 e76eed789f 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>
2026-10-02 01:21:15 +03:00

110 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`, «Результаты»).