Files
mtusi2026lab2/openspec/changes/bench-postgres/design.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

440 lines
29 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.
# 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 не затрагиваются ни на
одном шаге.