24 KiB
Design
Context
Зачем — proposal.md, требования — дельта load-benchmark. Что есть
сейчас (archived change bench-postgres):
bench/run.pyна каждый размер поднимает свежий проект composemtusi-bench. Затем:prepare.js: 11 пользователей, читаемый чат и чат записи;prefill.js: N сообщений в читаемый чат порциями поprefill_chunk, 32 клиента;VACUUM (ANALYZE)иCHECKPOINT;cursors.js: пул курсоров читаемого чата;- этап плана:
explain.jsчитает три страницы,auto_explainпишет их планы в журнал Postgres. Средняя страница повторяется в psql с индексом и без него,DROP INDEX— в откатываемой транзакции; - матрица
read/write, затем уборка стенда.
- Методика — поля
Profile, целиком пишутся вmeta.json.make bench_compareотказывает, еслиprofile.*различается. - Запрос страницы (
src/core/repos/message.py) — сравнение кортежей(created_at, id) > ($2, $3)по индексуix_messages_chat_id_created_at_id. Длина текста по контракту — до 4000 символов (MESSAGE_TEXT_MAX_LENGTH). - Проба на закреплённом образе Postgres 18.6 (
postgres:18.6-trixie):- 210 000 строк: один чат на 200 000 и 1 000 чатов по 10;
CHECKPOINTвнутри транзакции выполняется;EXPLAIN (ANALYZE, WAL)дляINSERT … SELECTдаёт записи WAL, байты и полные образы страниц (FPI);- условие курсора через
OR—Index ScanсFilter: 96 198 строк отброшено, 2 634 буфера на середине большого чата; - покрывающий индекс с
INCLUDE (sender_id, text)— 32 МБ против 12 МБ у текущего. Текст из 4000 несжимаемых символов CJK (≈12 КБ) при нём не вставляется:index row requires 12072 bytes, maximum size is 8191. При текущем индексе — вставляется.
Goals / Non-Goals
Goals:
- Один прогон
make benchдаёт всё, что нужно треку 2 по плану запроса: набор ≥100 000 сообщений в чатах разного размера, планы приложения по уровням чатов, варианты индекса и запроса на тех же данных и стоимость записи по вариантам. - Варианты сравниваются на одних и тех же данных в одном состоянии стенда, поэтому шум между запусками стенда на сравнение не влияет.
Non-Goals:
- Менять индекс приложения в этом change. Если по правилу выбора
(решение 7) вариант окажется лучше, его внедрение — отдельный change с
миграцией и
make bench_ab. По пробе такого не ожидается. make bench_abи A/A-метка: код приложения не меняется, сравнивать нечего. Варианты сравниваются внутри одной метки.- Backup и восстановление — change
track2-backup-restore. - Настройка Postgres (
shared_buffers,random_page_costи т.п.). - Неравномерная нагрузка чтения по чатам в матрице. Сценарий
readпо-прежнему читает читаемый чат. Как стоят страницы маленьких чатов, показывают планы.
Decisions
1. Фоновые чаты — уровни в профиле
Новое поле Profile.background — кортеж пар «число чатов, сообщений в
чате»:
| Профиль | Уровни | Сообщений |
|---|---|---|
full |
10 × 5 000, 100 × 400, 1 000 × 10 | 100 000 |
quick |
2 × 1 000, 10 × 100, 50 × 10 | 3 500 |
Вместе с читаемым чатом на 10k / 100k / 500k в таблице 110 000 / 200 000 / 600 000 сообщений. Размеры чатов различаются от 10 до 500 000, в 50 000 раз.
Почему уровни, а не распределение Ципфа:
- у каждого уровня есть понятный представитель для плана;
- проверка распределения — точное сравнение чисел;
- результат читается как «маленький, средний, большой и огромный чат».
Ципф дал бы тот же разброс, но без очевидных точек для планов.
Фоновые чаты создаёт prepare.js. В каждом все 11 пользователей, как
в читаемом чате. Фикстура получает список bgChats: id и размер в
порядке уровней. Создание 1 110 чатов через HTTP занимает секунды и в
замер не входит.
2. Наполнение по расписанию
Оркестратор строит расписание: какой чат получает n-е сообщение наполнения. Длина расписания — N + сумма уровней.
- Чат с s сообщениями получает позиции (k + 0,5) / s, k = 0…s−1.
- Все позиции сортируются (при равенстве — по номеру чата).
Это stride scheduling: сообщения каждого чата равномерно размазаны по всему наполнению, а порядок детерминирован.
.work/schedule.json — массив номеров чатов: 0 — читаемый, дальше
фоновые в порядке фикстуры. prefill.js читает его через SharedArray
и шлёт сообщение n в чат schedule[n]. Порции, OFFSET, отправители
по кругу и столбцы prefill.csv остаются прежними. Только
messages_before / messages_after теперь считают всю таблицу, а
порций больше: (N + 100 000) / 25 000.
Альтернативы:
- Сначала фоновые чаты, потом читаемый: сообщения маленьких чатов лежали бы в начале таблицы, а читаемый чат — в конце, отдельно. Это нереалистично, и на соседство страниц в куче влиял бы порядок шагов.
- Случайный выбор чата на каждое сообщение: точное число сообщений в чате не гарантировано, нужен был бы добор.
После обслуживания БД оркестратор проверяет распределение:
SELECT chat_id, count(*) FROM messages GROUP BY chat_id;- в читаемом чате ровно N, у каждого фонового — его размер;
- всего строк N + фон.
Иначе — BenchError с размером, стенд убирается.
3. Страницы плана по уровням
-
Читаемый чат. Как раньше: первая, средняя и последняя страница из пула курсоров.
-
Фоновые уровни. Для первого чата каждого уровня новый
plan_cursors.jsпроходит историю страницами поwalk_limitи сохраняет позиции. Выбор — как у пула, только позиции с ≥page_limitсообщениями после них:- средняя — позиция из середины этого списка;
- последняя — его конец.
У чата без таких позиций (10 сообщений; 100 в
quick) — только первая страница.
Проход идёт до включения auto_explain, так что в журнал не попадает.
Попутно он прогревает страницы чата, как cursors.js прогревает
читаемый.
Оркестратор пишет .work/plan_pages.json: чат, уровень, страница,
позиция, курсор и ожидаемое число строк. explain.js читает файл и
запрашивает страницы по порядку. У каждой проверяется 200 и ожидаемое
число строк: полная страница или весь маленький чат. Записей
auto_explain по messages должно быть ровно столько, сколько страниц.
Сопоставление — по порядку, как раньше.
4. Варианты — в psql, в откатываемой транзакции
Для страницы сравнения каждого чата одна сессия psql, SQL — через stdin:
SET lock_timeout = '5s';
SET plan_cache_mode = force_custom_plan;
BEGIN;
PREPARE page AS <Query Text приложения>;
-- app: тот же запрос, тот же индекс
EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(...); -- прогрев
EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(...);
SET LOCAL plan_cache_mode = force_generic_plan;
-- generic
EXPLAIN … EXECUTE page(...); EXPLAIN … EXECUTE page(...);
SET LOCAL plan_cache_mode = force_custom_plan;
PREPARE page_or AS <тот же текст, условие курсора через OR>;
-- or-cursor (только если у страницы есть курсор)
EXPLAIN … EXECUTE page_or(...); EXPLAIN … EXECUTE page_or(...);
DROP INDEX <индекс плана приложения>;
-- no-index
EXPLAIN … EXECUTE page(...); EXPLAIN … EXECUTE page(...);
CREATE INDEX bench_variant_<имя> ON messages <столбцы варианта>;
-- <имя варианта>
EXPLAIN … EXECUTE page(...); EXPLAIN … EXECUTE page(...);
DROP INDEX bench_variant_<имя>;
-- … следующий вариант
ROLLBACK;
-
Каждый вариант выполняется дважды, в результат идёт второй. Только что построенный индекс ещё не в
shared_buffers(большая сборка пишет мимо них), и первое выполнение читало бы его с диска. Индекс приложения при этом прогрет. Без повтора сравнение было бы нечестным. -
Варианты индекса — поле
Profile.index_variants: пары «имя, столбцы». Тексты DDL пишутся в паспорт:chat_only—(chat_id);covering—(chat_id, created_at, id) INCLUDE (sender_id, text).
DROP INDEXиндекса приложения идёт до вариантов: иначе планировщик выбрал бы его, а не вариант. -
Форма с
ORполучается из текста приложения регулярной заменой(messages.created_at, messages.id) > ($2…, $3…)на(messages.created_at > $2… OR (messages.created_at = $2… AND messages.id > $3…)). Список столбцов,ORDER BYиLIMITостаются как в запросе приложения. Если шаблон не найден (приложение изменило запрос) —BenchError, а не тихая копия запроса. -
Generic plan —
force_generic_planдля того же prepared statement. Это проверка из ограниченийbaseline: какой план получит приложение после пяти выполнений. -
После
ROLLBACKоркестратор сравнивает список индексовmessages(pg_indexes) с тем, что был до этапа. При различии —BenchError.
Почему в psql, а не миграциями и make bench_ab:
- варианты сравниваются на одних данных и в одном состоянии кэша;
- нужна одна метка (~35 мин), а не по метке на вариант (по ~35 мин и A/A для шума);
- HTTP-уровень у этого стенда упирается в CPU API (H3
baseline): 0,05 мс БД из ~1,3 мс CPU на чтение, и разница индексов в RPS утонула бы в шуме.
Минус: psql делает custom plan с литералами, а приложение — prepared
statement asyncpg. Это закрыто сравнением app (psql) с планом
auto_explain той же страницы и вариантом generic.
5. Стоимость записи — откатываемые вставки в конце размера
После матрицы размера и до уборки стенда для каждой конфигурации — app
(индекс приложения, построенный заново), каждого варианта из профиля и
none — write_probe_repeats раз (3):
BEGIN;
CREATE TEMP TABLE probe_src ON COMMIT DROP AS
SELECT chat_id, sender_id, row_number() OVER (ORDER BY created_at, id) AS g
FROM (SELECT chat_id, sender_id, created_at, id FROM messages
ORDER BY created_at, id LIMIT <write_probe_rows>) s;
DROP INDEX <индекс приложения>;
CREATE INDEX bench_probe ON messages <столбцы конфигурации>; -- кроме none
SELECT pg_relation_size('bench_probe'), count(*) FROM messages;
CHECKPOINT;
EXPLAIN (ANALYZE, BUFFERS, WAL) INSERT INTO messages
SELECT gen_random_uuid(), chat_id, sender_id, rpad('probe-' || g, <text_length>, 'x'),
now() + g * interval '1 microsecond' FROM probe_src;
DO $$ BEGIN INSERT … <4000 несжимаемых символов>; RAISE NOTICE 'long-text: ok';
EXCEPTION WHEN others THEN RAISE NOTICE 'long-text: %', SQLERRM; END $$;
ROLLBACK;
VACUUM messages;
-
Источник чатов — первые
write_probe_rowsсообщений в порядке наполнения: 20 000 вfull, 5 000 вquick, где на размере 1k в таблице всего 4 500 строк. Чаты в той же пропорции и в том же перемешанном порядке, что у наполнения. Отправитель — тот же, он участник чата.created_at— после всех сообщений, вставка в конец диапазона каждого чата, как у новых сообщений. Временная таблица WAL не пишет. -
Индекс приложения строится заново (
DROP+CREATEпоpg_get_indexdef), как и варианты. Иначе текущий индекс с разделёнными после наполнения и прошлых проб страницами сравнивался бы со свежими компактными. -
CHECKPOINTперед вставкой: полные образы страниц пишутся при первом изменении страницы после контрольной точки. Без неё их число зависело бы от того, когда сработал фоновый checkpoint. -
VACUUM messagesпосле каждой пробы убирает строки откаченной вставки. Порядок конфигураций сдвигается на каждом повторе: индекс первичного ключа (случайный UUID) общий для всех и мог бы давать преимущество тем, кто идёт позже. -
Сообщение максимальной длины — 4000 символов CJK из
md5номера символа. Текст детерминирован и не сжимается, около 12 КБ UTF-8. Ошибка ловится вDO,NOTICEберётся из stderr psql. -
После всех проб число строк и список индексов
messagesдолжны совпасть с тем, что было до них. -
Метрики конфигурации — медиана и min–max повторов:
- время вставки на сообщение (
Execution Time/ строк); - WAL байт на сообщение, FPI на 1 000 сообщений;
- размер индекса и байты индекса на сообщение;
- результат длинного сообщения.
Пишутся в
meta.sizes[].write_costи в раздел сводки. - время вставки на сообщение (
Почему вставка в БД, а не HTTP-прогон write на каждый вариант:
- HTTP-запись ограничена CPU API и
fsyncкоммита каждого сообщения: ~1 мс на запрос; - стоимость индекса — десятки микросекунд на строку. Её видно только без этих слагаемых.
HTTP-запись с индексом приложения по-прежнему меряет сценарий write.
Обе цифры в отчёте рядом.
6. Граница чёрного ящика
Исключения для PostgreSQL стенда (bench.md, «Как писать»)
пополняются:
- подсчёт сообщений по чатам;
- варианты индекса и формы запроса в откатываемой транзакции;
- пробные вставки в откатываемой транзакции с
VACUUMпосле.
Приложение в эти моменты не нагружено. Данные и схема для него после этапа те же: это проверяется (решения 4 и 5). Приложение по-прежнему видит только HTTP от k6.
7. Гипотезы и правило выбора
Гипотезы записываются в REPORT.md до полной матрицы, по make bench_quick и пробе (Context):
- P1. Индекс приложения со сравнением кортежей: страница любого чата на любой глубине стоит ограниченно — до ~60 буферов и долей миллисекунды. От размера чата и таблицы это не зависит.
- P2.
chat_only: маленький чат стоит как с индексом приложения, плюс сортировка ≤400 строк. Огромный чат читает весь чат и сортирует. Время растёт с размером чата: ×≥20 от 10k к 500k. - P3. Курсор через
ORпри индексе приложения: буферы растут с числом сообщений до курсора. На середине 500k их в ≥100 раз больше, чем у сравнения кортежей. - P4.
covering:Index Only Scanбез чтения кучи, буферов средней страницы в ≥5 раз меньше;- индекс в ≥2 раза больше, WAL на сообщение в ≥1,5 раза больше;
- сообщение из 4000 символов не вставляется.
- P5. Generic plan индекса приложения — тот же
Index Scanна всех уровнях. - P6. Стоимость записи (WAL и время на сообщение) растёт в порядке
none<chat_only<app<covering.
Правило выбора записывается вместе с гипотезами. Вариант заменяет индекс приложения, только если выполнены все три условия:
- сообщение максимальной длины вставляется;
- буферы страницы сравнения на каждом уровне — не больше половины,
чем у
app; - время вставки и WAL на сообщение — не больше ×1,5 от
app.
Форма запроса меняется, только если вариант с OR читает меньше
буферов на всех уровнях. Иначе приложение не меняется, и отчёт так и
пишет.
Risks / Trade-offs
- [Время EXPLAIN одного выполнения на долях миллисекунды шумит] → основная метрика — буферы, они детерминированы. Время — второе. Варианты — второе выполнение из двух, на прогретых страницах.
- [Generic plan под
force_generic_plan— не обязательно тот, что выберетauto] → это верхняя граница риска: вautoPostgres берёт generic, только если тот не дороже custom. Так и записывается в отчёт. - [Вставка
INSERT … SELECTодной транзакцией дешевле, чем 20 000 коммитов] → сравниваются варианты между собой при одинаковой процедуре. Абсолютная стоимость HTTP-записи — сценарийwrite. Ограничение — в отчёте. - [Индекс первичного ключа на случайном UUID разделяет страницы при
каждой пробе, и порядок даёт смещение] →
VACUUMмежду пробами, сдвиг порядка на каждом повторе, медиана и разброс. - [Сборка покрывающего индекса на 600k строк — секунды, повторяется на каждой странице сравнения и пробе] → +2–3 минуты на матрицу. Это записано в оценке времени.
- [Расписание на 600 000 номеров в
.work/] → ~3,5 МБ JSON, удаляется вместе с.work/. В k6 —SharedArray, одна копия на все VU. - [Чат записи пуст при проверке распределения] → он ожидается с 0 сообщений и проверяется так же.
- [Методика меняется,
baselineиtrack2несравнимы] →make bench_compareотказывает поprofile.background. Отчёт сравнивает их только описательно, с этой оговоркой.
Migration Plan
Развёртывания нет: меняются только bench/, документация и отчёт.
Порядок — tasks.md:
- код стенда и
make bench_quick; - коммит кода;
- гипотезы и правило выбора в
REPORT.md, коммит; - подготовка хоста и
make bench BENCH_LABEL=track2; - коммит доказательств;
- отчёт.
Откат — git revert коммитов change. Рабочий стенд не затрагивается.