From 472ed0bca5cb966b2c8b9f79268c03abc64f0f7f Mon Sep 17 00:00:00 2001 From: roman Date: Fri, 2 Oct 2026 05:01:47 +0300 Subject: [PATCH] docs: report track 2 history index comparison Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 15 +- REPORT.md | 163 +++++++++++++++++-- openspec/changes/track2-query-plans/tasks.md | 4 +- 3 files changed, 155 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 32883298..344cc39c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,17 +83,18 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey). PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change `session-auth`, кэш Valkey — change `membership-cache`, автоматические проверки отказов — change `failure-checks`, нагрузочный стенд на -PostgreSQL с планами запроса — change `bench-postgres`. Этот файл и -`.claude/rules/` описывают целевое состояние лабы 2, поэтому в -остальном код с ними пока расходится: +PostgreSQL с планами запроса — change `bench-postgres`, трек 2 часть 1 +(индексы и запросы на чатах разного размера, стоимость записи) — +change `track2-query-plans`. Этот файл и `.claude/rules/` описывают +целевое состояние лабы 2, поэтому в остальном код с ними пока +расходится: - в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления базы: иначе в кэше останутся карточки чатов, созданных после снятия backup (design change `membership-cache`, Risks); -- в `REPORT.md` нет трека «5» №2: сравнение индексов и стоимости - записи (`track2-query-plans`, метки «до» и «после» — `make - bench_ab`) и backup с восстановлением (`track2-backup-restore`). - Уровень 4 в отчёте заполнен целиком. +- в `REPORT.md` нет трека «5» №2, часть 2: backup с восстановлением + (`track2-backup-restore`). Уровень 4 и часть 1 трека в отчёте + заполнены целиком. Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый пункт убрать отсюда, закрытый переход — удалить раздел. diff --git a/REPORT.md b/REPORT.md index ecaf5bee..6f543c81 100644 --- a/REPORT.md +++ b/REPORT.md @@ -10,8 +10,10 @@ (`session-auth`), кэш карточки чата в Valkey (`membership-cache`), автоматические проверки отказов уровня 4 (`failure-checks`), нагрузочный стенд на PostgreSQL и обоснование индекса истории планами -`EXPLAIN (ANALYZE, BUFFERS)` (`bench-postgres`). Впереди: трек 2 -(`track2-query-plans`, `track2-backup-restore`). +`EXPLAIN (ANALYZE, BUFFERS)` (`bench-postgres`), трек 2 часть 1 — +индексы и запросы истории на чатах разного размера и стоимость записи +(`track2-query-plans`). Впереди: трек 2 часть 2 — backup и +восстановление (`track2-backup-restore`). ## Запуск из чистого clone @@ -289,8 +291,10 @@ Postgres спускается по B-дереву к курсору и чита буферов на 51 строку). Вероятная причина, отдельно не проверенная: соседние сообщения чата лежат на разных страницах, потому что их вставляли 32 клиента наполнения через разные соединения. - Покрывающий индекс (`Index Only Scan`) убрал бы чтения таблицы — это - кандидат для сравнения в треке 2. + Покрывающий индекс (`Index Only Scan`) убрал бы чтения таблицы. Трек 2 + его сравнил: 5 буферов вместо ~50, но сообщение из 4000 символов в + строку такого индекса не влезает, и индекс оставлен прежним (раздел + «Трек 2, часть 1»). Файлы: `evidence/bench/baseline/explain-{10k,100k,500k}.txt` — планы целиком. Сводка — раздел «Планы запроса истории» в @@ -462,7 +466,8 @@ Valkey приходят из `environment` compose. В compose нет литер | Уровень 4: гонка регистрации одного `username` | `test_same_username_at_once` в `make test_isolated` | 10 клиентов, в полёте одновременно 10: одна 201, девять 409 | `evidence/tests/test-isolated.md` | | Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | `src/core/repos/` | | Уровень 4: индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация без полного scan | `make bench BENCH_LABEL=baseline`: `auto_explain` запроса приложения на 10k / 100k / 500k; тот же запрос без индекса в откатываемой транзакции | `Index Scan` по `(chat_id, created_at, id)`: 3–4 буфера на первую страницу, 47–55 на среднюю и последнюю на любом размере, около 0,05 мс. Без индекса — скан всей таблицы: 9 678 буферов и 20 мс на 500k. p50 чтения на 500k выше, чем на 10k, на 1–4% | `evidence/bench/baseline/explain-*.txt`, `summary.md`; раздел «Индекс истории» | -| Трек 5 | — | TODO | TODO | +| Трек 5 №2, часть 1: ≥100 000 сообщений в чатах разного размера, ≥2 индекса и запроса, стоимость записи | `make bench BENCH_LABEL=track2`: 110 000 / 200 000 / 600 000 сообщений в 1 111 чатах от 10 до 500 000; планы приложения по уровням чатов, 6 вариантов страницы сравнения в откатываемой транзакции, пробы записи по 4 вариантам индекса | индекс приложения — 5–55 буферов на любой странице любого чата; `or-cursor` — 252 338 буферов и 44 мс на середине чата 500k; `chat_only` — до 11 590; `covering` — 5 буферов, но +100 байт индекса и +17–34% WAL на сообщение, а сообщение из 4000 символов не вставляется. Индекс и запрос приложения оставлены по правилу выбора, записанному до замера | `evidence/bench/track2/summary.md`, `explain-*.txt`; раздел «Трек 2, часть 1» | +| Трек 5 №2, часть 2: backup → восстановление в новое хранилище → сверка | — | TODO (change `track2-backup-restore`) | TODO | ## Эксперименты и отказы @@ -596,14 +601,15 @@ bench_quick` (1k–10k, от батареи). Там API на 4–16 клиен ~5 МБ. Объём на сообщение — байты в БД: 256–274. Ограничения замера: -- Один чат со всей историей: селективность `chat_id` около 100%. Как - план меняется у маленьких и больших чатов, проверяет трек 2. +- Один чат со всей историей: селективность `chat_id` около 100%. Чаты + разного размера — в треке 2, часть 1: план индекса приложения тот же. - Настройки Postgres — по умолчанию образа (`shared_buffers` 128 МБ). Таблица с индексами на 500k (122 МБ) целиком в памяти, чтения с диска не измерялись. -- Все планы приложения — custom: параметры подставлены в условия. Какой - generic plan Postgres выбрал бы для prepared statement asyncpg после - многих выполнений, не проверялось. +- Все планы приложения в этой метке — custom: параметры подставлены в + условия. Generic plan проверен в треке 2, часть 1: на 10k и 100k с + чатами разного размера приложение получило его само, и это тот же + `Index Scan` с теми же буферами. - Docker Desktop на ноутбуке (macOS, Apple M3 Pro): числа сравнимы только между метками этой методики, а не с другими машинами. @@ -680,6 +686,124 @@ bench_quick` (1k–10k, от батареи). Там API на 4–16 клиен Форма запроса меняется, только если `or-cursor` читает меньше буферов на всех уровнях. Иначе приложение не меняется. +**Результаты.** Метка `evidence/bench/track2/`: commit `67be41e` (код +стенда `d2656ab` и гипотезы), 2026-10-02, 32 минуты. +- Хост в начале и в конце — от сети, swap 0, свободно 76% и 67% + памяти; посторонних контейнеров нет. +- 54 прогона без пометок и ошибок. +- Распределение по чатам совпало на всех размерах: 1 111 чатов от 10 + до N сообщений. + +Планы страниц сравнения. Ячейка — буферы `shared hit` верхнего узла / +время, мс; чтений с диска нет. Узел — индекс приложения (`Index Scan`), +если не сказано иначе. Файлы — `explain-{10k,100k,500k}.txt`, сводка — +раздел «Планы запроса истории» в `summary.md`. + +| Таблица | Чат, страница (после скольких) | `psql` | `generic` | `or-cursor` | `chat_only` | `covering` | `no-index` | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 600 000 | 500 000, средняя (250 000) | 49 / 0,023 | 49 / 0,029 | 252 338 / 44,023 | `Parallel Seq Scan` 11 590 / 18,405 | `Index Only Scan` 5 / 0,020 | `Parallel Seq Scan` 11 590 / 20,463 | +| | 5 000, средняя (2 500) | 52 / 0,024 | 52 / 0,038 | 2 441 / 0,557 | 4 176 / 1,328 | `Index Only Scan` 5 / 0,013 | `Parallel Seq Scan` 11 590 / 11,077 | +| | 400, средняя (200) | 55 / 0,030 | 55 / 0,030 | `Bitmap Heap Scan` 208 / 0,135 | 403 / 0,129 | `Index Only Scan` 5 / 0,020 | `Parallel Seq Scan` 11 560 / 10,731 | +| | 10, первая | 13 / 0,011 | 13 / 0,012 | — | 13 / 0,013 | `Index Only Scan` 5 / 0,006 | `Parallel Seq Scan` 11 650 / 9,996 | +| 110 000 | 10 000, средняя (5 000) | 53 / 0,027 | 53 / 0,026 | 4 979 / 0,847 | `Bitmap Heap Scan` 2 036 / 2,017 | `Index Only Scan` 5 / 0,016 | `Seq Scan` 2 129 / 4,023 | +| | 5 000, средняя (2 500) | 51 / 0,025 | 51 / 0,027 | 2 427 / 0,359 | `Bitmap Heap Scan` 1 876 / 1,092 | `Index Only Scan` 5 / 0,017 | `Seq Scan` 2 129 / 3,167 | +| | 400, средняя (200) | 51 / 0,021 | 51 / 0,024 | 249 / 0,065 | `Bitmap Heap Scan` 378 / 0,151 | `Index Only Scan` 5 / 0,015 | `Seq Scan` 2 129 / 2,835 | +| | 10, первая | `Bitmap Heap Scan` 13 / 0,022 | 13 / 0,009 | — | `Bitmap Heap Scan` 12 / 0,020 | `Index Only Scan` 4 / 0,011 | `Seq Scan` 2 129 / 2,526 | + +Планы самого приложения (`auto_explain`), все 30 страниц на трёх +размерах: +- `Index Scan` по индексу приложения, кроме первой страницы чата из 10 + на 10k (`Bitmap Heap Scan`); +- 5–55 буферов и 0,029–0,149 мс. + +Страницы с курсором на 10k и 100k приложение выполнило generic-планом, +на 500k — custom. Выбор зависит от истории выполнений на соединении +пула, а узел и буферы в обоих случаях те же. + +Стоимость записи — медиана трёх повторов, вставка 20 000 сообщений +(раздел «Стоимость записи по вариантам индекса» в `summary.md`): + +| Вариант | Индекс, байт на сообщение | мкс на сообщение (10k / 100k / 500k) | WAL байт на сообщение (10k / 100k / 500k) | Сообщение из 4000 символов | +| --- | --- | --- | --- | --- | +| `none` | 0 | 5,09 / 4,93 / 5,28 | 495 / 621 / 1 185 | вставляется | +| `chat_only` | 7,4 / 7,3 / 7,2 | 5,46 / 5,55 / 5,93 | 601 / 720 / 1 284 | вставляется | +| `app` | 59,1 / 59,0 / 58,9 | 5,90 / 6,03 / 6,48 | 740 / 865 / 1 375 | вставляется | +| `covering` | 158,7 / 158,7 / 158,6 | 6,46 / 6,37 / 6,79 | 991 / 1 080 / 1 604 | **не вставляется**: `index row requires 12072 bytes, maximum size is 8191` | + +На 500k индекс `covering` занимает 98,2 МиБ — больше самой таблицы +(90,4 МиБ). Индекс приложения — 36,5 МиБ, `chat_only` — 4,4 МиБ. + +WAL на сообщение растёт с таблицей у всех вариантов. После `CHECKPOINT` +каждая впервые изменённая страница пишет полный образ (FPI): +- у `app` — 65 FPI на 1 000 сообщений на 10k и 180 на 500k; +- добавка `covering` к `app` в абсолютных числах почти постоянна: + +251 / +215 / +229 байт. + +HTTP-матрица (`summary.md`, сценарии `read` и `write`): +- `read` 595–620 RPS при одном клиенте и 757–789 при 10; +- `write` 998–1 056 RPS при 10 клиентах; +- API занимает 1,00 ядра с 10 клиентов, Postgres — 0,12–0,23; +- наполнение — 934–959 сообщений в секунду без тренда до 600 000. + +Это тот же порядок, что у `baseline`. Сравнивать их таблицей нельзя: +методика другая, `make bench_compare` откажет по `profile.background`. + +Итог по гипотезам: + +| | Итог | Числа | +| --- | --- | --- | +| P1 | подтверждена | планы приложения — 5–55 буферов и до 0,149 мс на всех уровнях и размерах; середина и конец чата 500k — 49 и 54 буфера против 53 и 53 на 10k | +| P2 | **опровергнута** | середина чата 500k — 11 590 буферов против 49 (×237, порог ×20), но время от 10k к 500k выросло в 9,1 раза (2,017 → 18,405 мс) при пороге ×10. Причина: `chat_only` читает все сообщения чата, а они перемешаны с другими чатами и лежат почти каждое на своей странице. Поэтому стоимость близка к числу страниц с сообщениями чата: чат из 5 000 на 500k — 4 176 буферов, а чат из 10 000 на 10k читает почти всю таблицу (2 036 буферов при 2 129 страницах таблицы). Неверна и первая часть: чат из 400 читает 378–403 буфера против 51–55 у индекса приложения, так же дёшево только чат из 10 | +| P3 | подтверждена | середина чата 500k — 252 338 буферов и 44 мс против 49 и 0,023 мс (×5 150, порог ×100). Это хуже полного скана (11 590 буферов): Postgres идёт по индексу чата с начала и отбрасывает фильтром все 250 000 сообщений до курсора. На маленьких чатах вреда почти нет (400: 208–253 буфера) | +| P4 | подтверждена по условию опровержения, часть про WAL — только на 10k | `Index Only Scan`, 4–5 буферов против 13–55 (в 10 раз меньше на страницах с курсором); индекс в 2,7 раза больше (158,6 против 58,9 байт на сообщение); сообщение из 4000 символов не вставляется. WAL — ×1,34 на 10k, но ×1,25 на 100k и ×1,17 на 500k: при росте таблицы FPI становится больше, и добавка покрывающего индекса в доле меньше | +| P5 | формально опровергнута в одной точке | у `generic` везде `Index Scan` по индексу приложения и те же буферы, что у `psql`. Но на 10k у чата из 10 custom-план — `Bitmap Heap Scan`, а generic — `Index Scan` при тех же 13 буферах (generic даже быстрее: 0,009 против 0,022 мс). Неравномерные чаты generic-план не портят. Часть «приложение после прогрева получает generic» верна на 10k и 100k, на 500k приложение осталось на custom | +| P6 | подтверждена | на каждом размере медианы времени и WAL идут по порядку `none` < `chat_only` < `app` < `covering`; `covering` дороже `app` на 0,31–0,56 мкс на сообщение (порог 13 мкс) | + +**Решение по правилу выбора — индекс и запрос приложения не меняются.** +- `covering` не проходит условие 1: контракт разрешает текст до 4000 + символов, а такой несжимаемый текст в строку индекса не влезает, и + `POST` сообщения получил бы 500. Выигрыш — около 0,01 мс БД на + страницу, меньше 1% от ~1,3 мс CPU API на запрос, а платить пришлось + бы +100 байт индекса на сообщение и +17–34% WAL. +- `chat_only` не проходит условие 2: на всех уровнях, кроме чата из 10, + буферов в 7–237 раз больше. +- `or-cursor` дороже на всех страницах с курсором, на большом чате — на + три порядка. + +Что ещё видно: +- **Индекс приложения читает примерно одну страницу таблицы на строку + страницы** (47–55 буферов на 51 строку) на любом уровне. Сообщения + чата лежат на разных страницах кучи: их вставляли вперемешку с + сообщениями других чатов. В `baseline`, с одним чатом, было так же: + там сообщения перемешивали 32 клиента наполнения. Прогон с одним + клиентом наполнения, который проверил бы это напрямую, не делался. +- **Форма запроса важнее выбора между близкими индексами.** Условие + через `OR` даёт верный результат, но превращает keyset-пагинацию в + скан всего, что до курсора. Сравнение кортежей — не стилистика, а + граница диапазона для индекса. + +Ограничения: +- Вся таблица и индексы в памяти (`read` = 0, кроме одной страницы). + При холодном кэше выигрыш `covering` по вводу-выводу был бы больше: + 5 случайных чтений против ~50. Не измерялось. +- Стоимость записи по вариантам — одна вставка `INSERT … SELECT` в + транзакции, без `fsync` коммита на каждое сообщение. HTTP-запись меряет + сценарий `write`, и только для индекса приложения. +- Варианты в psql — custom-планы с литералами, а приложение выполняет + prepared statement. Generic-план проверен через `force_generic_plan`; + какой план выберет `auto` на другой истории выполнений, зависит от + соединения. +- Данные синтетические: три уровня размеров, равномерное перемешивание, + тексты по 64 символа. Длинные реальные тексты увеличили бы + `covering` ещё сильнее. +- В планах варианты индекса построены заново и компактны, а индекс + приложения — живой, после наполнения. Это сравнение в пользу + вариантов. В пробах записи индекс приложения тоже строится заново, + там условия равные. +- Один прогон без A/A. Варианты сравниваются на одних данных в одном + состоянии стенда, а буферы детерминированы. Шум между прогонами + влияет только на время. + ## Ограничения и следующие шаги - Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не @@ -724,11 +848,10 @@ bench_quick` (1k–10k, от батареи). Там API на 4–16 клиен - Пропускную способность стенда ограничивает CPU единственного процесса API (на стенде замеров — 1 ядро), Postgres загружен на 0,2 ядра. Это ожидаемо для одного worker; масштабирование репликами — лаба 3. -- Планы и нагрузка сняты на одном большом чате и с настройками Postgres - по умолчанию, вся таблица в памяти (раздел «Нагрузочный стенд на - PostgreSQL», ограничения замера). -- Не реализовано: трек 2 — сравнение индексов на чатах разного размера - и backup с восстановлением (changes `track2-query-plans` и +- Планы и нагрузка сняты с настройками Postgres по умолчанию, вся + таблица в памяти: выигрыш покрывающего индекса при холодном кэше не + измерялся (раздел «Трек 2, часть 1», ограничения). +- Не реализовано: трек 2, часть 2 — backup с восстановлением (change `track2-backup-restore`). ## Источники, библиотеки и использование ИИ @@ -744,12 +867,16 @@ bench_quick` (1k–10k, от батареи). Там API на 4–16 клиен `requirepass`, образ `valkey/valkey` и его `docker-entrypoint.sh`), redis-py (`redis.asyncio`, `Retry`, `BlockingConnectionPool`), PostgreSQL (`pg_stat_user_tables`, задержка статистики). +- Документация по планам и записи: PostgreSQL 18 (`EXPLAIN` с `BUFFERS` + и `WAL`, `auto_explain`, `plan_cache_mode`, индексы с `INCLUDE` и + `Index Only Scan`, предел размера строки B-дерева, сравнение + кортежей в условиях), k6 (`SharedArray`, `shared-iterations`). - Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn; в тестах — - pytest и httpx. + pytest и httpx; в нагрузочном стенде — k6. - ИИ: Claude (Claude Code) помогал проектировать changes - `postgres-storage`, `session-auth`, `membership-cache` и - `failure-checks` (OpenSpec), + `postgres-storage`, `session-auth`, `membership-cache`, + `failure-checks`, `bench-postgres` и `track2-query-plans` (OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат в `evidence/`. diff --git a/openspec/changes/track2-query-plans/tasks.md b/openspec/changes/track2-query-plans/tasks.md index 372e7355..a761a447 100644 --- a/openspec/changes/track2-query-plans/tasks.md +++ b/openspec/changes/track2-query-plans/tasks.md @@ -119,7 +119,7 @@ Предупреждение о хосте — переснять, а не игнорировать. - [x] 6.3 Закоммитить `evidence/bench/track2/` (`docs: add track 2 query plan bench evidence`). Проверка: `git status` чистый. -- [ ] 6.4 `REPORT.md`, трек 2 «план запроса»: +- [x] 6.4 `REPORT.md`, трек 2 «план запроса»: - набор данных; - таблица планов по уровням и вариантам (500k и выборочно 10k); - стоимость записи; @@ -130,6 +130,6 @@ `AGENTS.md` закрыть пункт трека 2 «план запроса» в «Переходном состоянии». Проверка: каждое число в тексте есть в `summary.md` или `explain-*.txt` метки `track2`, commit метки указан. -- [ ] 6.5 Закоммитить отчёт (`docs: report track 2 history index +- [x] 6.5 Закоммитить отчёт (`docs: report track 2 history index comparison`). `openspec validate track2-query-plans --strict` проходит, `git status` чистый.