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:
@@ -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