docs: report track 2 history index comparison

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-02 05:01:47 +03:00
co-authored by Claude Opus 5.5
parent 159001e781
commit 472ed0bca5
3 changed files with 155 additions and 27 deletions
+8 -7
View File
@@ -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/<файл>`. Закрытый
пункт убрать отсюда, закрытый переход — удалить раздел.
+145 -18
View File
@@ -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/`.
+2 -2
View File
@@ -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` чистый.