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

114 lines
7.7 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. Таблица памяти показывает
байты на сообщение в БД.
- **Матрица короче, чем на лабе 1:** размеры 10k, 100k и 500k вместо
1M, порция наполнения 25 000 вместо 50 000. Полный прогон — около
30 минут вместо 45. 500k ≥ 100k трека 2 и ≥ 10k уровня 4.
- **Базовый замер** `baseline` полной матрицы на закоммиченном коде. По
нему в `REPORT.md` пишутся раздел экспериментов и строка уровня 4
«индекс истории и EXPLAIN».
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `load-benchmark`:
- изменённые требования:
- стенд из API, PostgreSQL и Valkey с миграциями, лимитами и
свежим volume на каждый размер;
- матрица: наибольший размер 500 000 вместо 1 000 000;
- идентификация 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 — около 30 минут (оценка
по скоростям `make bench_quick`). Запуск — только с согласия пользователя и после
подготовки хоста (`bench.md`, «Результаты»).