chore: archive bench-postgres change

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-02 04:04:15 +03:00
co-authored by Claude Opus 5.5
parent 23ceedb954
commit 3f3acc95b8
7 changed files with 321 additions and 169 deletions
+4 -3
View File
@@ -90,9 +90,10 @@ PostgreSQL с планами запроса — change `bench-postgres`. Это
- в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления
базы: иначе в кэше останутся карточки чатов, созданных после снятия
backup (design change `membership-cache`, Risks);
- `REPORT.md` заполнен по уровню 4 целиком (включая индекс истории и
`EXPLAIN` по метке `evidence/bench/baseline/`); трек 2 —
следующие changes.
- в `REPORT.md` нет трека «5» №2: сравнение индексов и стоимости
записи (`track2-query-plans`, метки «до» и «после» — `make
bench_ab`) и backup с восстановлением (`track2-backup-restore`).
Уровень 4 в отчёте заполнен целиком.
Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый
пункт убрать отсюда, закрытый переход — удалить раздел.
@@ -176,7 +176,8 @@ VM и сам Docker остаётся около 2 ГиБ и 5 CPU. Если су
### 3. Идентификация в k6: регистрация с паролем, Basic, Bearer
- `prepare.js` для каждого пользователя:
- генерирует пароль `crypto.randomBytes` (`k6/crypto`);
- генерирует пароль из двух `crypto.randomUUID()` (WebCrypto k6, без
импорта): 73 символа, в пределах 12–128 контракта;
- регистрирует пользователя с паролем;
- входит по `Authorization: Basic` (`k6/encoding`, UTF-8 base64);
- кладёт токен в `fixture.json` рядом с id.
@@ -314,10 +315,13 @@ Postgres стенда запускается с `shared_preload_libraries=auto_e
(таблица + индексы) / число строк. На этот момент в таблице ровно N
сообщений читаемого чата: чат записи ещё пуст. Поля идут в
`meta.sizes` и в таблицу «Память и наполнение» сводки рядом с RSS.
- Сторож (`Watcher`) проверяет ещё `Running`, `OOMKilled` и
`RestartCount` контейнеров Postgres и Valkey. Если один из них упал,
прогон получает пометку `stand_down`, матрица останавливается, а
`BenchError` называет контейнер. При падении API, как и раньше, — `oom`
- Сторож (`Watcher`) раз в секунду проверяет ещё `Running` контейнеров
Postgres и Valkey и при падении останавливает k6. После каждого
прогона и порции `Stand.down_storages()` смотрит `Running`,
`OOMKilled` и `RestartCount`: при `restart: "no"` упавший контейнер
остаётся остановленным, так что живой проверки `Running` хватает.
Если хранилище упало, прогон получает пометку `stand_down`, матрица
останавливается, а `BenchError` называет контейнер. При падении API, как и раньше, — `oom`
или `app_down`.
### 7. Паспорт
@@ -353,6 +357,8 @@ Postgres стенда запускается с `shared_preload_libraries=auto_e
- `generator.image`;
- `stand.postgres.image` и `stand.valkey.image`;
- `stand.postgres.settings.*`;
- `stand.valkey.maxmemory*` — лимит и политика вытеснения из
`valkey.conf`: образ не ловит правку конфигурации;
- `stand.app_env.*` (окружение API лежит в паспорте под `stand`).
Остальное поведение — как в спеке: отказ при различии, «не
@@ -426,8 +426,9 @@ SHALL содержать:
Команда SHALL отказываться сравнивать метки, снятые разной методикой.
Если различаются параметры профиля, лимиты любого контейнера стенда,
образы генератора, PostgreSQL или Valkey, настройки PostgreSQL или
окружение приложения, она завершается с ненулевым кодом, называет
образы генератора, PostgreSQL или Valkey, настройки PostgreSQL, лимит
памяти и политика вытеснения Valkey или окружение приложения, она
завершается с ненулевым кодом, называет
различие и не создаёт таблицу. Параметр, записанный в паспорте только
одной из меток, SHALL перечисляться в таблице как непроверенный, без
отказа. В начале таблицы SHALL перечисляться незавершённая метка,
@@ -452,8 +453,8 @@ SHALL содержать:
#### Scenario: Разная методика
- **WHEN** у меток различается параметр профиля, лимит контейнера,
образ генератора или хранилища, настройка PostgreSQL или переменная
окружения приложения
образ генератора или хранилища, настройка PostgreSQL, `maxmemory`
или `maxmemory-policy` Valkey или переменная окружения приложения
- **THEN** команда завершается с ненулевым кодом, называет параметр и
оба значения, таблица не создаётся
+301 -157
View File
@@ -2,13 +2,13 @@
## Purpose
Воспроизводимый нагрузочный эксперимент трека 1: одной командой
поднимает стенд с фиксированными лимитами, прогоняет матрицу размеров
истории и уровней конкуренции для чтения и записи и сохраняет сырые
данные, сводку и паспорт стенда, чтобы сравнивать версии кода при
одинаковых условиях. К стенду прилагаются диагностика стоимости
запроса, сравнение двух меток и прогоны «до» и «после» одного
изменения подряд.
Воспроизводимый нагрузочный эксперимент: одной командой поднимает
стенд из приложения, PostgreSQL и Valkey с фиксированными лимитами,
прогоняет матрицу размеров истории и уровней конкуренции для чтения и
записи и сохраняет сырые данные, сводку, планы запроса истории и
паспорт стенда, чтобы сравнивать версии кода при одинаковых условиях.
К стенду прилагаются сравнение двух меток и прогоны «до» и «после»
одного изменения подряд.
## Requirements
@@ -18,10 +18,10 @@
результата `BENCH_LABEL` (по умолчанию `baseline`), короткий прогон —
командой `make bench_quick`. Результаты SHALL сохраняться в
`evidence/bench/<метка>/`. Команда MUST NOT перезаписывать результаты
существующей метки и MUST NOT использовать порт 8080 хоста и
контейнеры `make run_dev` / `make run_docker`. После завершения, в том
числе с ошибкой или по Ctrl+C, контейнеры и сеть стенда SHALL
удаляться.
существующей метки. Она MUST NOT использовать порт 8080 хоста и MUST
NOT трогать контейнеры, базу и кэш рабочего стенда (`make run_dev` /
`make run_docker`). После завершения, в том числе с ошибкой или по
Ctrl+C, контейнеры, сеть и volume стенда SHALL удаляться.
#### Scenario: Полная матрица
@@ -38,29 +38,43 @@
#### Scenario: Рабочий стенд не затронут
- **WHEN** во время прогона запущен `make run_docker` на 8080
- **THEN** он продолжает отвечать, его контейнер и данные не меняются
- **THEN** он продолжает отвечать, а его контейнеры, база и кэш не
меняются
#### Scenario: Прерывание
- **WHEN** прогон прерван Ctrl+C
- **THEN** контейнеры и сеть стенда удалены, частичные результаты
помечены как незавершённые
- **THEN** контейнеры, сеть и volume стенда удалены, частичные
результаты помечены как незавершённые
### Requirement: Фиксированный стенд
Приложение SHALL запускаться в контейнере из образа, собранного из
текущего checkout тем же `Dockerfile`, с одинаковыми во всех прогонах
лимитами: 1 CPU, 2 ГБ памяти без swap. Healthcheck образа SHALL быть
отключён, порты на хост MUST NOT публиковаться. Генератор нагрузки
SHALL работать в той же docker-сети и обращаться к приложению по имени
Стенд SHALL состоять из приложения, PostgreSQL и Valkey. Приложение
SHALL запускаться в контейнере из образа, собранного из текущего
checkout тем же `Dockerfile`. PostgreSQL и Valkey SHALL запускаться из
тех же образов, что у рабочего стенда. Valkey получает ту же
конфигурацию. PostgreSQL получает те же настройки образа плюс модуль
записи планов, выключенный вне снятия плана. Схема БД SHALL
применяться миграциями до наполнения.
Лимиты SHALL быть одинаковыми во всех прогонах:
- у приложения — 1 CPU и 2 ГБ памяти без swap;
- у PostgreSQL и Valkey — свои лимиты CPU и памяти без swap, заданные
методикой.
Healthcheck образа приложения SHALL быть отключён. Порты стенда на хост
MUST NOT публиковаться. Настройки приложения и хранилищ SHALL браться
из методики стенда, а не из `.env` и `config.toml` рабочего стенда.
Пароли хранилищ SHALL генерироваться на прогон. Генератор нагрузки SHALL
работать в той же docker-сети и обращаться к приложению по имени
контейнера, минуя проброс портов хоста.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит лимиты CPU и памяти контейнера
приложения, прочитанные у запущенного контейнера, и они одинаковы для
всех прогонов
- **THEN** паспорт стенда содержит лимиты CPU и памяти контейнеров
приложения, PostgreSQL и Valkey, прочитанные у запущенных
контейнеров, и они одинаковы для всех размеров
#### Scenario: Нехватка памяти
@@ -68,6 +82,19 @@ SHALL работать в той же docker-сети и обращаться к
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
#### Scenario: Настройки рабочего стенда не влияют
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
отсутствуют
- **THEN** стенд запускается с теми же настройками приложения и
хранилищ, а окружение приложения в паспорте то же
#### Scenario: Схема до наполнения
- **WHEN** начинается наполнение размера
- **THEN** миграции применены до последней ревизии, и приложение
отвечает готовностью
### Requirement: Сценарии нагрузки
Стенд SHALL поддерживать два сценария с синтетическими данными
@@ -110,16 +137,53 @@ SHALL проверяться на
- **THEN** они входят в долю ошибок прогона и не входят в перцентили
задержки успешных запросов
### Requirement: Идентификация в сценариях
Запросы стенда SHALL идентифицироваться так, как требует контракт.
Пользователи стенда регистрируются с паролем и получают сессию входом
по Basic. Создание чатов, отправка сообщений и чтение истории идут с
Bearer-токеном этой сессии. Срок сессии стенда SHALL быть больше
длительности одного размера матрицы. Пароли пользователей и токены
MUST NOT сохраняться в результатах.
#### Scenario: Запросы с Bearer
- **WHEN** выполняется любой сценарий стенда
- **THEN** запросы к API идут с `Authorization: Bearer`, без
`X-User-Id`, и ни один ответ не 401
#### Scenario: Сессия не истекает за размер
- **WHEN** размер от наполнения до последнего прогона идёт дольше
часа (срок сессии приложения по умолчанию), например на медленном
хосте
- **THEN** ответов 401 в его прогонах нет
#### Scenario: Секретов стенда нет в результатах
- **WHEN** прогон завершён, в том числе с ошибкой или по Ctrl+C
- **THEN** в каталоге метки нет паролей и токенов пользователей стенда
и паролей его хранилищ
### Requirement: Матрица и повторы
Полная матрица SHALL включать размеры истории 10 000, 100 000 и
1 000 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных
500 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных
клиентов и оба сценария, по 3 измеряемых прогона на ячейку. Перед
каждым измеряемым прогоном SHALL идти прогрев с той же нагрузкой, не
входящий в результат. Каждый размер SHALL начинаться с нового процесса
приложения, наполненного через HTTP API до ровно N сообщений в читаемом
чате. Рост хранилища за прогоны `write` SHALL фиксироваться в
результатах.
входящий в результат.
Каждый размер SHALL начинаться со свежего стенда:
- новый процесс приложения;
- пустая база на новом volume с применёнными миграциями;
- пустой кэш.
Стенд наполняется через HTTP API до ровно N сообщений в читаемом чате.
После наполнения, до сбора курсоров и первого прогона, SHALL
выполняться обслуживание БД: очистка и сбор статистики планировщика по
таблицам, затем контрольная точка. Так состояние таблиц и статистика
не зависят от того, когда сработали фоновые процессы БД. Рост
хранилища за прогоны `write` SHALL фиксироваться в результатах.
#### Scenario: Состав матрицы
@@ -130,25 +194,43 @@ SHALL проверяться на
#### Scenario: Свежий процесс на каждый размер
- **WHEN** начинается размер N
- **THEN** контейнер приложения запущен заново и перед первым прогоном
содержит ровно N сообщений в читаемом чате
- **THEN** контейнеры приложения, PostgreSQL и Valkey запущены заново,
volume базы новый, и перед первым прогоном в читаемом чате ровно N
сообщений
#### Scenario: Обслуживание после наполнения
- **WHEN** наполнение размера N завершено
- **THEN** до сбора курсоров выполнены очистка и сбор статистики
таблиц, затем контрольная точка, и это видно в выводе команды
### Requirement: Метрики прогона
Для каждого измеряемого прогона SHALL сохраняться: сценарий, размер
истории, конкуренция, номер повтора, длительность, число успешных и
неуспешных запросов, успешные RPS, доля ошибок, задержки p50, p95, p99
и max успешных запросов, потреблённое приложением CPU, RSS процесса
приложения в начале, в конце и максимальный за прогон, число сообщений
в хранилище в начале и в конце, загрузка CPU генератора. Для каждого
размера SHALL сохраняться RSS до и после наполнения и оценка байт RSS
на сообщение.
Для каждого измеряемого прогона SHALL сохраняться:
- сценарий, размер истории, конкуренция, номер повтора, длительность;
- число успешных и неуспешных запросов, успешные RPS, доля ошибок;
- задержки p50, p95, p99 и max успешных запросов;
- потреблённое приложением CPU;
- RSS процесса приложения в начале, в конце и максимальный за прогон;
- число сообщений в хранилище в начале и в конце;
- загрузка CPU генератора и CPU контейнера PostgreSQL.
Наполнение SHALL идти порциями, и для каждой порции SHALL сохраняться:
размер, число сообщений в хранилище до и после, успешные RPS, доля
ошибок, задержки p50, p95, p99 и max, CPU приложения и RSS в конце
порции. Так наполнение до 1 000 000 даёт кривую «запись при росте
хранилища» без дополнительного времени прогона.
Для каждого размера SHALL сохраняться:
- RSS приложения до и после наполнения;
- объём таблицы сообщений и её индексов после обслуживания БД;
- байты на сообщение в БД.
Наполнение SHALL идти порциями. Для каждой порции SHALL сохраняться:
- размер и число сообщений в хранилище до и после;
- успешные RPS и доля ошибок;
- задержки p50, p95, p99 и max;
- CPU приложения и CPU PostgreSQL;
- RSS в конце порции.
Так наполнение до 500 000 даёт кривую «запись при росте хранилища»
без дополнительного времени прогона. Новые метрики SHALL добавляться
новыми столбцами в конце таблиц. Прежние столбцы MUST NOT
переименовываться и удаляться.
#### Scenario: Строка прогона
@@ -158,23 +240,78 @@ SHALL проверяться на
#### Scenario: Память на сообщение
- **WHEN** наполнение размера N завершено
- **THEN** в результатах есть прирост RSS за наполнение и байты на
сообщение
- **THEN** в результатах есть прирост RSS приложения за наполнение,
объём таблицы и индексов сообщений и байты на сообщение в БД
#### Scenario: Кривая наполнения
- **WHEN** наполнение размера 1 000 000 завершено
- **WHEN** наполнение размера 500 000 завершено
- **THEN** в таблице наполнения есть строка на каждую порцию, от
пустого хранилища до 1 000 000 сообщений, с RPS, p95, p99, max и
RSS
пустого хранилища до 500 000 сообщений, с RPS, p95, p99, max, CPU
приложения и PostgreSQL и RSS
### Requirement: План запроса истории
Для каждого размера, после обслуживания БД и до измеряемых прогонов,
стенд SHALL сохранять в каталоге метки вывод `EXPLAIN (ANALYZE,
BUFFERS)` запроса страницы истории читаемого чата с `limit` профиля.
Это SHALL быть тот запрос и те параметры, которые выполнило само
приложение при обработке HTTP-запроса. Планы снимаются для трёх
страниц:
- первой;
- из середины истории;
- последней полной.
Для страницы из середины SHALL сохраняться и план того же запроса с
теми же параметрами без индекса, который использовал план приложения.
Индекс при этом MUST NOT пропадать для приложения и следующих прогонов.
Сводка метки SHALL показывать по каждому плану:
- узел доступа к таблице сообщений;
- число прочитанных страниц: из кэша и с диска;
- время выполнения.
Если план запроса приложения не найден, команда SHALL завершаться с
ненулевым кодом и называть размер.
#### Scenario: Планы на каждом размере
- **WHEN** размер N наполнен и обслужен
- **THEN** в каталоге метки есть файл планов размера N: первая, средняя
и последняя полная страница и средняя страница без индекса
#### Scenario: Запрос самого приложения
- **WHEN** проверяющий открывает файл планов
- **THEN** в нём текст запроса и параметры, с которыми его выполнило
приложение, план с фактическим временем, числом строк и буферами
каждого узла
#### Scenario: Индекс остаётся
- **WHEN** снят план без индекса
- **THEN** индекс по-прежнему есть в базе стенда, и следующие прогоны
идут при той же схеме
#### Scenario: План не найден
- **WHEN** в окне снятия плана приложение не выполнило запрос истории
или его план не попал в журнал PostgreSQL
- **THEN** команда завершается с ненулевым кодом, называет размер, а
стенд удаляется
### Requirement: Достоверность прогона
Прогон SHALL помечаться в результатах, если его данные нельзя считать
замером сервера: процесс приложения перезапускался или был убит,
генератор нагрузки был загружен настолько, что мог сам ограничивать
throughput, или доля ошибок больше нуля. Сводка SHALL показывать эти
пометки рядом со значениями.
замером сервера:
- процесс приложения перезапускался или был убит;
- контейнер PostgreSQL или Valkey перезапускался, был убит или
остановлен;
- генератор нагрузки был загружен настолько, что мог сам ограничивать
throughput;
- доля ошибок больше нуля.
Сводка SHALL показывать эти пометки рядом со значениями.
#### Scenario: Генератор упёрся в CPU
@@ -182,22 +319,39 @@ throughput, или доля ошибок больше нуля. Сводка SHA
методике
- **THEN** прогон помечен, и в сводке рядом с его ячейкой видна пометка
#### Scenario: Хранилище упало
- **WHEN** во время прогона контейнер PostgreSQL или Valkey был убит
или перезапущен
- **THEN** прогон помечен, матрица останавливается, и команда называет
контейнер
### Requirement: Ход прогона виден
Во время прогона команда SHALL печатать строку на каждый этап (сборка
образа, запуск стенда, наполнение, сбор курсоров, каждый измеряемый
прогон) с временем от начала. Наполнение SHALL показывать прогресс не
реже раза в минуту: сколько сообщений из N, скорость, оценку
оставшегося времени. После каждого измеряемого прогона SHALL
печататься его номер из общего числа, ячейка матрицы, основные
результаты (RPS, p50, p95, p99, CPU приложения, RSS, доля ошибок),
пометки и оценка времени до конца матрицы. В каталоге метки SHALL
поддерживаться файл текущего состояния, а строка прогона SHALL
дописываться в таблицу прогонов сразу после прогона.
Во время прогона команда SHALL печатать строку на каждый этап с
временем от начала. Этапы:
- сборка образа и запуск стенда;
- миграции;
- наполнение;
- обслуживание БД;
- снятие плана;
- сбор курсоров;
- каждый измеряемый прогон.
Наполнение SHALL показывать прогресс не реже раза в минуту: сколько
сообщений из N, скорость, оценку оставшегося времени. После каждого
измеряемого прогона SHALL печататься:
- его номер из общего числа и ячейка матрицы;
- основные результаты: RPS, p50, p95, p99, CPU приложения, RSS, доля
ошибок;
- пометки и оценка времени до конца матрицы.
В каталоге метки SHALL поддерживаться файл текущего состояния, а строка
прогона SHALL дописываться в таблицу прогонов сразу после прогона.
#### Scenario: Где мы сейчас
- **WHEN** идёт наполнение размера 1M
- **WHEN** идёт наполнение размера 500k
- **THEN** в выводе не реже раза в минуту появляется строка с числом
отправленных сообщений, скоростью и оценкой оставшегося времени
@@ -227,19 +381,30 @@ throughput, или доля ошибок больше нуля. Сводка SHA
наполнения;
- таблица всех прогонов в CSV;
- таблица порций наполнения в CSV;
- сводка по ячейкам матрицы (медиана и разброс min–max по повторам) в
Markdown;
- паспорт стенда: дата, commit и признак незакоммиченных изменений,
digest образа приложения, версии генератора и Python, лимиты, железо
хоста и VM, параметры профиля и команда запуска;
- планы запроса истории по размерам;
- сводка по ячейкам матрицы (медиана и разброс min–max по повторам) и
по планам в Markdown;
- паспорт стенда;
- состояние хоста в начале и в конце прогона: занятый swap, доля
свободной памяти, питание от сети или от батареи.
Паспорт стенда SHALL содержать:
- дату, commit и признак незакоммиченных изменений;
- digest образа приложения и версии его библиотек;
- образы и версии PostgreSQL и Valkey;
- настройки PostgreSQL, от которых зависят план запроса и стоимость
записи;
- окружение приложения без паролей;
- версии генератора и Python;
- лимиты всех контейнеров стенда;
- железо хоста и VM;
- параметры профиля и команду запуска.
Если в начале прогона хост работает от батареи или swap занят сверх
порога методики, команда SHALL предупреждать об этом в выводе и в
паспорте, но не прерываться. Данные MUST быть синтетическими;
результаты MUST NOT содержать секретов, `.env` и абсолютных путей
домашнего каталога.
паспорте, но не прерываться. Данные MUST быть синтетическими.
Результаты MUST NOT содержать секретов (паролей и токенов стенда),
`.env` и абсолютных путей домашнего каталога.
#### Scenario: Повтор на другой машине
@@ -259,12 +424,30 @@ throughput, или доля ошибок больше нуля. Сводка SHA
- **THEN** вывод команды и паспорт содержат предупреждение, а прогон
продолжается
#### Scenario: Хранилища в паспорте
- **WHEN** проверяющий открывает паспорт метки
- **THEN** в нём образы и версии PostgreSQL и Valkey, их лимиты,
настройки PostgreSQL и окружение приложения, а паролей нет
### Requirement: Базовый замер в отчёте
Результат полной матрицы текущего кода SHALL быть сохранён под меткой
`baseline`. `REPORT.md` SHALL описывать в разделе экспериментов
гипотезы, стенд и лимиты, профиль нагрузки, результаты по ячейкам со
ссылкой на каталог `evidence/bench/baseline/` и ограничения замера.
Результат полной матрицы текущего кода на PostgreSQL SHALL быть
сохранён под меткой `baseline`. `REPORT.md` SHALL описывать в разделе
экспериментов:
- гипотезы;
- стенд и лимиты всех контейнеров;
- профиль нагрузки;
- результаты по ячейкам со ссылкой на каталог
`evidence/bench/baseline/`;
- ограничения замера.
Индекс истории SHALL обосновываться в `REPORT.md` планами из этой
метки на размерах от 10 000 сообщений. Для этого приводятся:
- запрос;
- узел доступа, буферы и время для первой, средней и последней
страницы;
- тот же запрос без индекса.
#### Scenario: Проверяющий читает отчёт
@@ -272,99 +455,58 @@ throughput, или доля ошибок больше нуля. Сводка SHA
- **THEN** в нём есть гипотезы, условия стенда, таблица результатов и
путь к сырым данным
### Requirement: Разложение стоимости запроса
#### Scenario: Обоснование индекса истории
Команда `make bench_inproc` SHALL раскладывать время обработки одного
запроса внутри приложения на части, чтобы узкое место находилось
измерением, а не догадкой. Приложение SHALL вызываться в том же
процессе, без сервера и сети, на синтетических данных с фиксированным
зерном. Вывод SHALL содержать:
- время на запрос сценариев `read` и `write` при обычном уровне логов
и при выключенных записях уровня INFO; разница — цена логов, отдельно
сборка записи и запись в stdout контейнера;
- время частей построения ответа страницы истории, в том числе вариант
без форматирования времени в Python; разница — цена форматирования;
- функции с наибольшим собственным временем и числом вызовов на запрос;
- медиану и разброс min–max каждого измерения: по запускам процесса
для времени на запрос, по повторам для частей ответа;
- дату, commit, признак незакоммиченных изменений, версии Python и
библиотек, машину хоста.
Результат SHALL сохраняться в `evidence/profile/<метка>.txt`. Команда
MUST NOT перезаписывать файл существующей метки. Числа этой команды
MUST NOT выдаваться за результат стенда: она объясняет, куда уходит
время, а пропускную способность и задержки меряет только `make bench`.
Команда SHALL также сверять текущее форматирование времени с эталонной
записью формата `ГГГГ-ММ-ДДTЧЧ:ММ:СС.ffffffZ` на наборе значений,
включающем нулевые микросекунды и время в другом часовом поясе, и
проверять, что строка разбирается обратно в то же значение. При
расхождении команда SHALL завершаться с ненулевым кодом и называть
значение.
#### Scenario: Разложение чтения
- **WHEN** выполняется `make bench_inproc BENCH_LABEL=<метка>`
- **THEN** в `evidence/profile/<метка>.txt` есть время на запрос `read`
и `write`, цена логов, цена построения ответа и цена форматирования
времени, у каждого числа — медиана и разброс
#### Scenario: До и после изменения
- **WHEN** команда выполнена на коде до изменения и на коде после него
под разными метками
- **THEN** по двум файлам видно, какая часть запроса подешевела и на
сколько, а какие части не изменились
#### Scenario: Метка уже занята
- **WHEN** файл `evidence/profile/<метка>.txt` уже существует
- **THEN** команда завершается с ненулевым кодом и называет файл
#### Scenario: Формат времени изменился
- **WHEN** форматирование времени даёт строку, отличную от эталонной,
хотя бы для одного значения набора
- **THEN** команда завершается с ненулевым кодом и печатает значение,
ожидаемую и полученную строки
- **WHEN** проверяющий ищет в `REPORT.md` обоснование индекса истории
- **THEN** он находит запрос и `EXPLAIN (ANALYZE, BUFFERS)` на
≥10 000 сообщениях для разных позиций курсора и сравнение без
индекса, со ссылками на файлы планов метки `baseline`
### Requirement: Сравнение двух меток
Команда `make bench_compare BEFORE=<метка> AFTER=<метка>` SHALL
сравнивать результаты двух меток полной матрицы и сохранять таблицу в
`evidence/compare/<до>__<после>.md`. Для каждой ячейки матрицы таблица
SHALL содержать медиану и разброс min–max повторов RPS в обеих метках,
изменение медианы в процентах, медианы p50, p95 и p99 и CPU приложения
на один запрос. Для каждого размера истории — байты RSS на сообщение в
обеих метках.
SHALL содержать:
- медиану и разброс min–max повторов RPS в обеих метках;
- изменение медианы в процентах;
- медианы p50, p95 и p99;
- CPU приложения на один запрос.
Команда SHALL отказываться сравнивать метки, снятые разной методикой:
если различаются параметры профиля, лимиты контейнера приложения или
образ генератора, она завершается с ненулевым кодом, называет
Для каждого размера истории таблица SHALL содержать байты RSS на
сообщение и байты на сообщение в БД в обеих метках.
Команда SHALL отказываться сравнивать метки, снятые разной методикой.
Если различаются параметры профиля, лимиты любого контейнера стенда,
образы генератора, PostgreSQL или Valkey, настройки PostgreSQL, лимит
памяти и политика вытеснения Valkey или окружение приложения, она
завершается с ненулевым кодом, называет
различие и не создаёт таблицу. Параметр, записанный в паспорте только
одной из меток, SHALL перечисляться в таблице как непроверенный, без
отказа. Незавершённая метка, незакоммиченные изменения, предупреждения
о хосте и помеченные прогоны SHALL перечисляться в начале таблицы.
отказа. В начале таблицы SHALL перечисляться незавершённая метка,
незакоммиченные изменения, предупреждения о хосте и помеченные
прогоны.
С необязательным параметром `AA=<метка>` команда SHALL оценивать
уровень шума: наибольшее по ячейкам сценария изменение медианы RPS
между метками `AA` и `BEFORE`, снятыми на одном и том же коде
приложения. Изменение в ячейке SHALL называться эффектом, только если
разбросы повторов двух меток не пересекаются и изменение медианы
больше уровня шума её сценария; иначе — изменением в пределах шума.
больше уровня шума её сценария. Иначе это изменение в пределах шума.
#### Scenario: Сравнимые метки
- **WHEN** сравниваются две завершённые метки одного профиля с
одинаковыми лимитами и генератором
одинаковыми лимитами, образами и настройками
- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня
конкуренции) с медианами, разбросом и изменением в процентах, а в
начале — commit и условия хоста каждой метки
#### Scenario: Разная методика
- **WHEN** у меток различается параметр профиля, лимит контейнера или
образ генератора
- **WHEN** у меток различается параметр профиля, лимит контейнера,
образ генератора или хранилища, настройка PostgreSQL, `maxmemory`
или `maxmemory-policy` Valkey или переменная окружения приложения
- **THEN** команда завершается с ненулевым кодом, называет параметр и
оба значения, таблица не создаётся
@@ -389,21 +531,24 @@ SHALL содержать медиану и разброс min–max повтор
### Requirement: Прогоны «до» и «после» подряд
Команда `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`
SHALL снимать метки «до» и «после» одного изменения подряд, без
работы на хосте между ними. В рабочем дереве лежит код «до», а
изменение закоммичено и откачено отдельным commit; `REAPPLY` — commit
отката. Команда SHALL по порядку выполнить: полную матрицу и
разложение стоимости запроса для `BEFORE`, commit их результатов,
возврат изменения новым commit, полную матрицу и разложение для
`AFTER`. Матрица SHALL идти раньше разложения, чтобы в паспорте метки
не было признака незакоммиченных изменений.
SHALL снимать метки «до» и «после» одного изменения подряд, без работы
на хосте между ними. В рабочем дереве лежит код «до», а изменение
закоммичено и откачено отдельным commit; `REAPPLY` — commit отката.
Команда SHALL выполнить по порядку:
1. полную матрицу для `BEFORE`;
2. commit её результатов;
3. возврат изменения новым commit;
4. полную матрицу для `AFTER`.
Команда SHALL отказываться стартовать, ничего не запустив, если
рабочее дерево не чистое, файлы одной из меток уже существуют, метки
совпадают или commit `REAPPLY` не найден в текущей ветке. Если шаг
завершился с ошибкой, следующие шаги MUST NOT выполняться, а команда
SHALL назвать этот шаг. Команда создаёт commit в текущей ветке и MUST
NOT отправлять его в удалённый репозиторий.
Команда SHALL отказываться стартовать, ничего не запустив, если:
- рабочее дерево не чистое;
- каталог одной из меток уже существует;
- метки совпадают;
- commit `REAPPLY` не найден в текущей ветке.
Если шаг завершился с ошибкой, следующие шаги MUST NOT выполняться, а
команда SHALL назвать этот шаг. Команда создаёт commit в текущей ветке
и MUST NOT отправлять его в удалённый репозиторий.
#### Scenario: Оба прогона без участия человека
@@ -421,8 +566,7 @@ NOT отправлять его в удалённый репозиторий.
#### Scenario: Метка занята
- **WHEN** каталог метки стенда или файл разложения одной из меток уже
существует
- **WHEN** каталог метки стенда одной из меток уже существует
- **THEN** команда завершается с ненулевым кодом до первого шага и
называет путь