docs: report track 2 history index comparison
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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/<файл>`. Закрытый
|
||||
пункт убрать отсюда, закрытый переход — удалить раздел.
|
||||
|
||||
@@ -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/`.
|
||||
|
||||
@@ -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` чистый.
|
||||
|
||||
Reference in New Issue
Block a user