30 KiB
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_timeout5 с,statement_timeout5 с, срок сессии 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.
На каждый размер:
down -v --remove-orphans— прежний стенд и volume;up -d --wait postgres valkey;run --rm migrate;up -d --no-deps --no-build api;- ожидание
/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 |
размер 500k с наполнением идёт ~20 мин на машине автора. На медленном хосте срок 3600 с по умолчанию мог бы истечь посреди прогона и дать 401 |
sizes (профиль full) |
10k, 100k, 500k |
вместо 1M лабы 1, по просьбе пользователя сократить прогон: ~30 мин вместо ~45. Диапазон ×50 достаточен, чтобы увидеть, растёт ли страница с длиной истории; 500k ≥ 100k трека 2 |
prefill_chunk |
25000 |
вместо 50 000: на Postgres наполнение ~850 сообщ/с, и порция в 50 000 шла бы ~59 с, на границе требования «прогресс не реже раза в минуту». Заодно кривая наполнения в два раза подробнее |
Остальные настройки приложения — значения по умолчанию из
settings.py: пул 10 + 5, таймауты и кэш. Их видно в паспорте
(app_env и версия кода). Postgres работает на настройках образа
(shared_buffers 128 МБ и т.д.). Свой postgresql.conf не
монтируется: настройки — как у рабочего стенда, отличие одно —
shared_preload_libraries (решение 5).
Что даёт память Postgres при настройках образа. Свои буферы Postgres —
128 МБ, остальное читается через кэш страниц ОС. Кэш страниц входит в
лимит памяти cgroup контейнера. Таблица messages на 500k с индексами —
ориентировочно 130–150 МБ (bench_quick: 272 байта на сообщение на
10k), так что в 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, и модуль ничего не
делает: в измеряемых прогонах его нет. Этап «план» идёт после
обслуживания и сбора курсоров, до первого прогона размера.
-
Маркер начала:
DO $$ BEGIN RAISE LOG 'bench-explain <uuid> start'; END $$. -
Включение:
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 применяет настройки и в уже открытых соединениях пула приложения. -
k6/explain.js, 1 VU, три последовательных запроса истории читаемого чата сlimitпрофиля, у каждого проверка 200 и полной страницы:- без курсора (первая страница);
- курсор из середины пула;
- последний курсор пула (последняя полная страница).
-
Выключение:
ALTER SYSTEM RESETтех же параметров,pg_reload_conf(), маркер конца. -
Разбор
docker logs mtusi-bench-postgresмежду маркерами. ЗаписиLOG: duration: … plan:с продолжением по строкам с табуляцией. Берутся только записи, у которыхQuery Textчитаетmessages; запросы сессии и карточки чата отбрасываются. Записей должно быть ровно три, в порядке запросов. Иначе —BenchErrorс размером, и стенд убирается (сценарий «План не найден»). -
Сравнение без индекса — для средней страницы. Из записи берутся
Query Text,Query Parameters(Postgres 16+ пишет их по умолчанию) и имя индекса из узлаIndex Scan using <имя>илиIndex Only Scan/Bitmap Index Scan. В psql (SQL через stdin, не через shell):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, что индекс на месте (сценарий «Индекс остаётся»). Если план приложения не использовал индекс, сравнения нет, а в файле и сводке это сказано прямо. -
Файл
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. Базовый замер и гипотезы
Порядок:
- Код стенда закоммичен после подтверждения пользователя.
make bench_quickпроверяет стенд: меткаquick-*в git не идёт.- Хост подготовлен (
bench.md, «Результаты»). - С согласия пользователя запускается
make bench BENCH_LABEL=baseline. - Доказательства коммитятся после подтверждения.
- Числа и планы переносятся в
REPORT.md.
Гипотезы записываются в REPORT.md до запуска полной матрицы. По
bench.md результат пишется как получился:
- H1. p50 чтения при той же конкуренции не растёт с 10k до 500k
больше чем на величину шума: страница — keyset по индексу.
Buffersсредней и последней страницы того же порядка, что у первой, на всех размерах. - H2. Без индекса тот же запрос —
Seq Scanи сортировка, буферы — порядка размера таблицы, время растёт линейно с N. - H3. На
c=10иc=50чтение и запись упираются в CPU API (app_cpu_cores≈ 1), а Postgres загружен меньше (db_cpu_cores). - H4. Скорость записи на кривой наполнения до 500k падает слабо: глубина B-дерева растёт логарифмически.
Risks / Trade-offs
- [
auto_explainне запишет план: настройка не дошла до соединения пула или формат журнала другой] → маркеры начала и конца, ровно три ожидаемые записи, иначе отказ с размером. Первая задача реализации — проба наbench_quickдо остального. - [Наполнение 500k через HTTP идёт дольше оценки (~10 мин): запись — это ещё проверка сессии, вставка и commit с fsync на диске VM Docker] → ETA в выводе пересчитывается по факту. Если полная матрица выходит заметно дольше 30 минут, сказать пользователю, а не менять методику молча.
- [Рабочий набор 500k (таблица с индексами ~130–150 МБ) около
shared_buffers128 МБ: часть чтений может идти из кэша ОС внутри лимита 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 не затрагиваются ни на
одном шаге.