- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
852 lines
53 KiB
Markdown
852 lines
53 KiB
Markdown
# load-benchmark Specification
|
||
|
||
## Purpose
|
||
|
||
Воспроизводимый нагрузочный эксперимент: одной командой поднимает
|
||
стенд из приложения, PostgreSQL и Valkey с фиксированными лимитами,
|
||
прогоняет матрицу размеров истории и уровней конкуренции для чтения и
|
||
записи на чатах разного размера и сохраняет сырые данные, сводку,
|
||
планы запроса истории с вариантами индекса и запроса, стоимость записи
|
||
по вариантам и паспорт стенда, чтобы сравнивать версии кода и решения
|
||
о схеме при одинаковых условиях. На тех же данных стенд проверяет
|
||
backup и восстановление в новое хранилище со сверкой, временем
|
||
восстановления и границей потери данных.
|
||
К стенду прилагаются сравнение двух меток и прогоны «до» и «после»
|
||
одного изменения подряд.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Запуск одной командой
|
||
|
||
Полная матрица SHALL запускаться командой `make bench` с меткой
|
||
результата `BENCH_LABEL` (по умолчанию `baseline`), короткий прогон —
|
||
командой `make bench_quick`. Результаты SHALL сохраняться в
|
||
`evidence/bench/<метка>/`. Команда MUST NOT перезаписывать результаты
|
||
существующей метки. Она MUST NOT использовать порт 8080 хоста и MUST
|
||
NOT трогать контейнеры, базу и кэш рабочего стенда (`make run_dev` /
|
||
`make run_docker`). После завершения, в том числе с ошибкой или по
|
||
Ctrl+C, контейнеры, сеть и volume стенда SHALL удаляться.
|
||
|
||
#### Scenario: Полная матрица
|
||
|
||
- **WHEN** выполняется `make bench BENCH_LABEL=baseline`
|
||
- **THEN** прогоняется вся матрица, результаты лежат в
|
||
`evidence/bench/baseline/`, код выхода 0
|
||
|
||
#### Scenario: Метка уже занята
|
||
|
||
- **WHEN** каталог `evidence/bench/<метка>/` уже существует
|
||
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
|
||
называет каталог
|
||
|
||
#### Scenario: Рабочий стенд не затронут
|
||
|
||
- **WHEN** во время прогона запущен `make run_docker` на 8080
|
||
- **THEN** он продолжает отвечать, а его контейнеры, база и кэш не
|
||
меняются
|
||
|
||
#### Scenario: Прерывание
|
||
|
||
- **WHEN** прогон прерван Ctrl+C
|
||
- **THEN** контейнеры, сеть и volume стенда удалены, частичные
|
||
результаты помечены как незавершённые
|
||
|
||
### Requirement: Фиксированный стенд
|
||
|
||
Стенд 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 и памяти контейнеров
|
||
приложения, PostgreSQL и Valkey, прочитанные у запущенных
|
||
контейнеров, и они одинаковы для всех размеров
|
||
|
||
#### Scenario: Нехватка памяти
|
||
|
||
- **WHEN** процесс приложения превысил лимит памяти и был убит
|
||
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
|
||
обычный результат
|
||
|
||
#### Scenario: Настройки рабочего стенда не влияют
|
||
|
||
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
|
||
отсутствуют
|
||
- **THEN** стенд запускается с теми же настройками приложения и
|
||
хранилищ, а окружение приложения в паспорте то же
|
||
|
||
#### Scenario: Схема до наполнения
|
||
|
||
- **WHEN** начинается наполнение размера
|
||
- **THEN** миграции применены до последней ревизии, и приложение
|
||
отвечает готовностью
|
||
|
||
### Requirement: Сценарии нагрузки
|
||
|
||
Стенд SHALL поддерживать два сценария с синтетическими данными
|
||
фиксированной длины:
|
||
- `read` — запрос страницы истории (`limit=50`) чата из N сообщений.
|
||
Каждый запрос берёт курсор случайно из пула, равномерно покрывающего
|
||
всю историю. В пул входят только позиции, после которых есть не
|
||
меньше 50 сообщений, поэтому каждый ответ содержит ровно 50
|
||
элементов. Данные при этом не меняются;
|
||
- `write` — отправка сообщения в отдельный чат, чтобы история чата
|
||
сценария `read` оставалась ровно N.
|
||
|
||
Каждая отправка сообщения стенда — при наполнении, в сценарии `write`
|
||
и на этапах восстановления — SHALL идти с новым `Idempotency-Key`,
|
||
который не совпадает с ключами других запросов прогона. Стенд MUST NOT
|
||
повторять отправку.
|
||
|
||
Последовательность случайных выборов SHALL задаваться фиксированным
|
||
зерном из профиля, у каждого клиента — своя последовательность: при
|
||
том же профиле и том же N прогоны разных меток отправляют одинаковые
|
||
запросы, а одновременные клиенты не повторяют друг друга. Каждый ответ
|
||
SHALL проверяться на
|
||
ожидаемый статус; неожиданные статусы и ошибки соединения SHALL
|
||
считаться ошибками прогона.
|
||
|
||
#### Scenario: Полная страница
|
||
|
||
- **WHEN** выполняется любой запрос сценария `read`
|
||
- **THEN** ответ содержит ровно 50 сообщений
|
||
|
||
#### Scenario: Одинаковые запросы в разных метках
|
||
|
||
- **WHEN** один профиль запускается под двумя метками на одинаковом N
|
||
- **THEN** каждый клиент выбирает курсоры в той же последовательности,
|
||
что и в другой метке, а последовательности разных клиентов различны
|
||
|
||
#### Scenario: Чтение не меняет данные
|
||
|
||
- **WHEN** выполнены все прогоны `read` для размера N
|
||
- **THEN** в читаемом чате по-прежнему ровно N сообщений
|
||
|
||
#### Scenario: Ошибки учитываются
|
||
|
||
- **WHEN** часть ответов не 200 (`read`) или не 201 (`write`)
|
||
- **THEN** они входят в долю ошибок прогона и не входят в перцентили
|
||
задержки успешных запросов
|
||
|
||
#### Scenario: Запись с ключом
|
||
|
||
- **WHEN** стенд отправляет сообщение при наполнении, в `write` или на
|
||
этапе восстановления
|
||
- **THEN** запрос несёт новый `Idempotency-Key`, ответ 201, а число
|
||
сообщений в чате совпадает с числом подтверждённых отправок
|
||
|
||
### 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 и
|
||
500 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных
|
||
клиентов и оба сценария, по 3 измеряемых прогона на ячейку. Перед
|
||
каждым измеряемым прогоном SHALL идти прогрев с той же нагрузкой, не
|
||
входящий в результат.
|
||
|
||
Каждый размер SHALL начинаться со свежего стенда:
|
||
- новый процесс приложения;
|
||
- пустая база на новом volume с применёнными миграциями;
|
||
- пустой кэш.
|
||
|
||
Кроме читаемого чата из N сообщений и чата записи, в стенде SHALL быть
|
||
фоновые чаты неравномерных размеров. Число чатов и сообщений в каждом
|
||
уровне задаёт методика, одинаково для всех размеров. В полной матрице
|
||
фоновых сообщений не меньше 100 000. Стенд наполняется через HTTP API.
|
||
Сообщения всех чатов SHALL отправляться вперемешку: сообщения каждого
|
||
чата распределены по всему наполнению равномерно, порядок
|
||
воспроизводим. После наполнения в читаемом чате ровно N сообщений, а
|
||
число сообщений каждого фонового чата SHALL совпадать с методикой;
|
||
иначе команда завершается с ненулевым кодом.
|
||
|
||
После наполнения, до сбора курсоров и первого прогона, SHALL
|
||
выполняться обслуживание БД: очистка и сбор статистики планировщика по
|
||
таблицам, затем контрольная точка. Так состояние таблиц и статистика
|
||
не зависят от того, когда сработали фоновые процессы БД. Рост
|
||
хранилища за прогоны `write` SHALL фиксироваться в результатах.
|
||
|
||
#### Scenario: Состав матрицы
|
||
|
||
- **WHEN** полная матрица завершена
|
||
- **THEN** в результатах 54 измеряемых прогона: 3 размера × 3 уровня
|
||
конкуренции × 2 сценария × 3 повтора
|
||
|
||
#### Scenario: Свежий процесс на каждый размер
|
||
|
||
- **WHEN** начинается размер N
|
||
- **THEN** контейнеры приложения, PostgreSQL и Valkey запущены заново,
|
||
volume базы новый, и перед первым прогоном в читаемом чате ровно N
|
||
сообщений
|
||
|
||
#### Scenario: Обслуживание после наполнения
|
||
|
||
- **WHEN** наполнение размера N завершено
|
||
- **THEN** до сбора курсоров выполнены очистка и сбор статистики
|
||
таблиц, затем контрольная точка, и это видно в выводе команды
|
||
|
||
#### Scenario: Неравномерные чаты
|
||
|
||
- **WHEN** наполнение размера N полной матрицы завершено
|
||
- **THEN** в таблице сообщений не меньше 100 000 строк, размеры чатов
|
||
различаются больше чем в 100 раз, и распределение по чатам совпадает
|
||
с методикой
|
||
|
||
#### Scenario: Распределение не совпало
|
||
|
||
- **WHEN** после наполнения у фонового чата число сообщений отличается
|
||
от методики
|
||
- **THEN** команда завершается с ненулевым кодом, называет размер, а
|
||
стенд удаляется
|
||
|
||
### Requirement: Метрики прогона
|
||
|
||
Для каждого измеряемого прогона SHALL сохраняться:
|
||
- сценарий, размер истории, конкуренция, номер повтора, длительность;
|
||
- число успешных и неуспешных запросов, успешные RPS, доля ошибок;
|
||
- задержки p50, p95, p99 и max успешных запросов;
|
||
- потреблённое приложением CPU;
|
||
- RSS процесса приложения в начале, в конце и максимальный за прогон;
|
||
- число сообщений в хранилище в начале и в конце;
|
||
- загрузка CPU генератора и CPU контейнера PostgreSQL.
|
||
|
||
Для каждого размера SHALL сохраняться:
|
||
- RSS приложения до и после наполнения;
|
||
- объём таблицы сообщений и её индексов после обслуживания БД;
|
||
- байты на сообщение в БД.
|
||
|
||
Наполнение SHALL идти порциями. Для каждой порции SHALL сохраняться:
|
||
- размер и число сообщений в хранилище до и после;
|
||
- успешные RPS и доля ошибок;
|
||
- задержки p50, p95, p99 и max;
|
||
- CPU приложения и CPU PostgreSQL;
|
||
- RSS в конце порции.
|
||
|
||
Так наполнение до 500 000 даёт кривую «запись при росте хранилища»
|
||
без дополнительного времени прогона. Новые метрики SHALL добавляться
|
||
новыми столбцами в конце таблиц. Прежние столбцы MUST NOT
|
||
переименовываться и удаляться.
|
||
|
||
#### Scenario: Строка прогона
|
||
|
||
- **WHEN** проверяющий открывает таблицу прогонов
|
||
- **THEN** у каждой строки заполнены все перечисленные поля
|
||
|
||
#### Scenario: Память на сообщение
|
||
|
||
- **WHEN** наполнение размера N завершено
|
||
- **THEN** в результатах есть прирост RSS приложения за наполнение,
|
||
объём таблицы и индексов сообщений и байты на сообщение в БД
|
||
|
||
#### Scenario: Кривая наполнения
|
||
|
||
- **WHEN** наполнение размера 500 000 завершено
|
||
- **THEN** в таблице наполнения есть строка на каждую порцию, от
|
||
пустого хранилища до 500 000 сообщений, с RPS, p95, p99, max, CPU
|
||
приложения и PostgreSQL и RSS
|
||
|
||
### Requirement: План запроса истории
|
||
|
||
Для каждого размера, после обслуживания БД и до измеряемых прогонов,
|
||
стенд SHALL сохранять в каталоге метки вывод `EXPLAIN (ANALYZE,
|
||
BUFFERS)` запроса страницы истории с `limit` профиля. Это SHALL быть тот
|
||
запрос и те параметры, которые выполнило само приложение при обработке
|
||
HTTP-запроса. Планы снимаются:
|
||
- для читаемого чата и одного чата каждого фонового уровня;
|
||
- для первой страницы, страницы из середины истории и последней полной
|
||
страницы чата. Середина и конец выбираются из позиций обхода истории
|
||
страницами по размеру обхода из методики, после которых есть полная
|
||
страница. У чата без таких позиций (не длиннее одной страницы обхода)
|
||
— только для первой.
|
||
|
||
Для страницы из середины каждого чата, а у чата без неё — для первой,
|
||
SHALL сохраняться планы того же запроса с теми же параметрами в
|
||
вариантах:
|
||
- с индексом, который использовал план приложения;
|
||
- то же с generic plan;
|
||
- с условием курсора, записанным через `OR` вместо сравнения кортежей,
|
||
если у страницы есть курсор;
|
||
- с каждым вариантом индекса из методики вместо индекса приложения;
|
||
- без индекса, который использовал план приложения.
|
||
|
||
Варианты MUST NOT менять индексы и данные для приложения и следующих
|
||
прогонов.
|
||
|
||
Сводка метки SHALL показывать по каждому плану:
|
||
- чат и его размер;
|
||
- вариант;
|
||
- узел доступа к таблице сообщений;
|
||
- число прочитанных страниц: из кэша и с диска;
|
||
- время выполнения.
|
||
|
||
Если план запроса приложения не найден, команда SHALL завершаться с
|
||
ненулевым кодом и называть размер.
|
||
|
||
#### Scenario: Планы на каждом размере
|
||
|
||
- **WHEN** размер N наполнен и обслужен
|
||
- **THEN** в каталоге метки есть файл планов размера N: для читаемого и
|
||
каждого фонового уровня — страницы приложения и варианты страницы
|
||
сравнения
|
||
|
||
#### Scenario: Запрос самого приложения
|
||
|
||
- **WHEN** проверяющий открывает файл планов
|
||
- **THEN** в нём текст запроса и параметры, с которыми его выполнило
|
||
приложение, план с фактическим временем, числом строк и буферами
|
||
каждого узла
|
||
|
||
#### Scenario: Индекс остаётся
|
||
|
||
- **WHEN** сняты планы вариантов
|
||
- **THEN** индексы в базе стенда те же, что до этапа, и следующие
|
||
прогоны идут при той же схеме
|
||
|
||
#### Scenario: План не найден
|
||
|
||
- **WHEN** в окне снятия плана приложение не выполнило запрос истории
|
||
или его план не попал в журнал PostgreSQL
|
||
- **THEN** команда завершается с ненулевым кодом, называет размер, а
|
||
стенд удаляется
|
||
|
||
### Requirement: Стоимость записи по вариантам индекса
|
||
|
||
Для каждого размера, после измеряемых прогонов, стенд SHALL измерять
|
||
стоимость записи в таблицу сообщений для каждого варианта индекса
|
||
истории:
|
||
- текущего индекса приложения;
|
||
- каждого варианта из методики;
|
||
- без индекса истории.
|
||
|
||
Остальные индексы и ограничения таблицы во всех вариантах одинаковы.
|
||
Для каждого варианта SHALL сохраняться:
|
||
- размер индекса и байты индекса на сообщение;
|
||
- время вставки порции сообщений на сообщение: медиана и разброс
|
||
min–max повторов;
|
||
- объём WAL и число полных образов страниц на сообщение;
|
||
- вставляется ли сообщение максимальной по контракту длины из
|
||
несжимаемого текста, а если нет — текст ошибки PostgreSQL.
|
||
|
||
Порция сообщений SHALL распределяться по всем чатам стенда, как
|
||
наполнение. Вставки и смена индекса SHALL выполняться в транзакции,
|
||
которая откатывается: после замера в базе тот же индекс приложения, а
|
||
число сообщений не изменилось. Размер порции и число повторов SHALL
|
||
задаваться методикой.
|
||
|
||
#### Scenario: Таблица стоимости записи
|
||
|
||
- **WHEN** размер N завершён
|
||
- **THEN** в сводке метки для каждого варианта есть размер индекса,
|
||
время вставки на сообщение с разбросом, WAL на сообщение и результат
|
||
вставки сообщения максимальной длины
|
||
|
||
#### Scenario: База после замера
|
||
|
||
- **WHEN** замер стоимости записи завершён
|
||
- **THEN** в базе стенда индексы и число сообщений те же, что до него
|
||
|
||
#### Scenario: Вариант не принимает длинное сообщение
|
||
|
||
- **WHEN** вставка сообщения максимальной длины при варианте
|
||
индекса завершилась ошибкой PostgreSQL
|
||
- **THEN** замер не прерывается, а в сводке у варианта записано, что
|
||
сообщение не вставляется, и текст ошибки
|
||
|
||
### Requirement: Достоверность прогона
|
||
|
||
Прогон SHALL помечаться в результатах, если его данные нельзя считать
|
||
замером сервера:
|
||
- процесс приложения перезапускался или был убит;
|
||
- контейнер PostgreSQL или Valkey перезапускался, был убит или
|
||
остановлен;
|
||
- генератор нагрузки был загружен настолько, что мог сам ограничивать
|
||
throughput;
|
||
- доля ошибок больше нуля.
|
||
|
||
Сводка SHALL показывать эти пометки рядом со значениями.
|
||
|
||
#### Scenario: Генератор упёрся в CPU
|
||
|
||
- **WHEN** загрузка CPU генератора за прогон выше порога, заданного в
|
||
методике
|
||
- **THEN** прогон помечен, и в сводке рядом с его ячейкой видна пометка
|
||
|
||
#### Scenario: Хранилище упало
|
||
|
||
- **WHEN** во время прогона контейнер PostgreSQL или Valkey был убит
|
||
или перезапущен
|
||
- **THEN** прогон помечен, матрица останавливается, и команда называет
|
||
контейнер
|
||
|
||
### Requirement: Ход прогона виден
|
||
|
||
Во время прогона команда SHALL печатать строку на каждый этап с
|
||
временем от начала. Этапы:
|
||
- сборка образа и запуск стенда;
|
||
- миграции;
|
||
- наполнение;
|
||
- обслуживание БД;
|
||
- снятие плана;
|
||
- сбор курсоров;
|
||
- каждый измеряемый прогон.
|
||
|
||
Наполнение SHALL показывать прогресс не реже раза в минуту: сколько
|
||
сообщений из N, скорость, оценку оставшегося времени. После каждого
|
||
измеряемого прогона SHALL печататься:
|
||
- его номер из общего числа и ячейка матрицы;
|
||
- основные результаты: RPS, p50, p95, p99, CPU приложения, RSS, доля
|
||
ошибок;
|
||
- пометки и оценка времени до конца матрицы.
|
||
|
||
В каталоге метки SHALL поддерживаться файл текущего состояния, а строка
|
||
прогона SHALL дописываться в таблицу прогонов сразу после прогона.
|
||
|
||
#### Scenario: Где мы сейчас
|
||
|
||
- **WHEN** идёт наполнение размера 500k
|
||
- **THEN** в выводе не реже раза в минуту появляется строка с числом
|
||
отправленных сообщений, скоростью и оценкой оставшегося времени
|
||
|
||
#### Scenario: Результат сразу после прогона
|
||
|
||
- **WHEN** завершился измеряемый прогон
|
||
- **THEN** в выводе появляется строка вида «прогон k из 54, сценарий,
|
||
размер, конкуренция, повтор: RPS, p50/p95/p99, CPU, RSS, ошибки,
|
||
пометки, осталось ~T», а в таблице прогонов — его строка
|
||
|
||
#### Scenario: Наблюдение из другого терминала
|
||
|
||
- **WHEN** прогон запущен, и пользователь открывает файл состояния в
|
||
каталоге метки
|
||
- **THEN** там текущий этап, число завершённых прогонов из общего,
|
||
оценка оставшегося времени и результат последнего прогона
|
||
|
||
#### Scenario: Частичные результаты
|
||
|
||
- **WHEN** прогон прерван на середине матрицы
|
||
- **THEN** строки уже завершённых прогонов есть в таблице прогонов
|
||
|
||
### Requirement: Сохранение результатов
|
||
|
||
В каталоге метки SHALL лежать:
|
||
- сырой результат генератора для каждого прогона и каждой порции
|
||
наполнения;
|
||
- таблица всех прогонов в CSV;
|
||
- таблица порций наполнения в CSV;
|
||
- планы запроса истории по размерам;
|
||
- сводка по ячейкам матрицы (медиана и разброс min–max по повторам),
|
||
по планам и вариантам и по стоимости записи в Markdown;
|
||
- паспорт стенда;
|
||
- состояние хоста в начале и в конце прогона: занятый swap, доля
|
||
свободной памяти, питание от сети или от батареи.
|
||
|
||
Паспорт стенда SHALL содержать:
|
||
- дату, commit и признак незакоммиченных изменений;
|
||
- digest образа приложения и версии его библиотек;
|
||
- образы и версии PostgreSQL и Valkey;
|
||
- настройки PostgreSQL, от которых зависят план запроса и стоимость
|
||
записи;
|
||
- окружение приложения без паролей;
|
||
- версии генератора и Python;
|
||
- лимиты всех контейнеров стенда;
|
||
- железо хоста и VM;
|
||
- параметры профиля, включая уровни фоновых чатов и варианты индекса,
|
||
и команду запуска.
|
||
|
||
Если в начале прогона хост работает от батареи или swap занят сверх
|
||
порога методики, команда SHALL предупреждать об этом в выводе и в
|
||
паспорте, но не прерываться. Данные MUST быть синтетическими.
|
||
Результаты MUST NOT содержать секретов (паролей и токенов стенда),
|
||
`.env` и абсолютных путей домашнего каталога.
|
||
|
||
#### Scenario: Повтор на другой машине
|
||
|
||
- **WHEN** другой человек берёт паспорт и команду из каталога метки
|
||
- **THEN** он может запустить тот же профиль на своём checkout и
|
||
сравнить таблицы по тем же столбцам
|
||
|
||
#### Scenario: Условия хоста для сравнения меток
|
||
|
||
- **WHEN** проверяющий сравнивает две метки
|
||
- **THEN** по паспортам видно, одинаковы ли были swap, свободная
|
||
память и питание хоста в начале и в конце каждого прогона
|
||
|
||
#### Scenario: Неподходящий хост
|
||
|
||
- **WHEN** прогон запускается от батареи или с занятым swap выше порога
|
||
- **THEN** вывод команды и паспорт содержат предупреждение, а прогон
|
||
продолжается
|
||
|
||
#### Scenario: Хранилища в паспорте
|
||
|
||
- **WHEN** проверяющий открывает паспорт метки
|
||
- **THEN** в нём образы и версии PostgreSQL и Valkey, их лимиты,
|
||
настройки PostgreSQL и окружение приложения, а паролей нет
|
||
|
||
### Requirement: Базовый замер в отчёте
|
||
|
||
Результат полной матрицы текущего кода на PostgreSQL SHALL быть
|
||
сохранён под меткой `baseline`. `REPORT.md` SHALL описывать в разделе
|
||
экспериментов:
|
||
- гипотезы;
|
||
- стенд и лимиты всех контейнеров;
|
||
- профиль нагрузки;
|
||
- результаты по ячейкам со ссылкой на каталог
|
||
`evidence/bench/baseline/`;
|
||
- ограничения замера.
|
||
|
||
Индекс истории SHALL обосновываться в `REPORT.md` планами из этой
|
||
метки на размерах от 10 000 сообщений. Для этого приводятся:
|
||
- запрос;
|
||
- узел доступа, буферы и время для первой, средней и последней
|
||
страницы;
|
||
- тот же запрос без индекса.
|
||
|
||
#### Scenario: Проверяющий читает отчёт
|
||
|
||
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
|
||
- **THEN** в нём есть гипотезы, условия стенда, таблица результатов и
|
||
путь к сырым данным
|
||
|
||
#### Scenario: Обоснование индекса истории
|
||
|
||
- **WHEN** проверяющий ищет в `REPORT.md` обоснование индекса истории
|
||
- **THEN** он находит запрос и `EXPLAIN (ANALYZE, BUFFERS)` на
|
||
≥10 000 сообщениях для разных позиций курсора и сравнение без
|
||
индекса, со ссылками на файлы планов метки `baseline`
|
||
|
||
### Requirement: Исследование индексов в отчёте
|
||
|
||
Сравнение индексов и запросов на неравномерных чатах SHALL быть
|
||
сохранено под меткой `track2` полной матрицы. Гипотезы и правило
|
||
выбора индекса SHALL быть записаны в `REPORT.md` до её запуска.
|
||
`REPORT.md` SHALL описывать в треке 2:
|
||
- набор данных: число сообщений и размеры чатов;
|
||
- сравниваемые индексы и формы запроса;
|
||
- планы по уровням чатов: узел доступа, буферы и время;
|
||
- стоимость записи по вариантам;
|
||
- итог по каждой гипотезе, как получился;
|
||
- решение по индексу приложения с обоснованием;
|
||
- ограничения.
|
||
|
||
Числа SHALL переноситься из файлов метки, со ссылкой на них.
|
||
|
||
#### Scenario: Проверяющий ищет сравнение индексов
|
||
|
||
- **WHEN** проверяющий открывает трек 2 в `REPORT.md`
|
||
- **THEN** он находит ≥2 индекса и ≥2 формы запроса, сравнённые на
|
||
≥100 000 сообщениях в чатах разного размера, стоимость записи по
|
||
вариантам и ссылки на файлы метки `track2`
|
||
|
||
#### Scenario: Гипотеза не подтвердилась
|
||
|
||
- **WHEN** результат расходится с гипотезой
|
||
- **THEN** отчёт называет гипотезу опровергнутой и приводит числа
|
||
|
||
### Requirement: Backup и восстановление в новое хранилище
|
||
|
||
Профиль методики SHALL включать этап backup и восстановления. Команда
|
||
`make bench_restore` (метка `RESTORE_LABEL`, по умолчанию `restore`)
|
||
SHALL запускать его на размерах 10 000, 100 000 и 500 000 с фоновыми
|
||
чатами полной матрицы, без измеряемых прогонов. Команда `make
|
||
bench_restore_quick` — то же на малых размерах, метка `quick-…`.
|
||
|
||
На каждом размере, после наполнения и планов, стенд SHALL по порядку:
|
||
1. снять логический backup базы стенда, пока через HTTP API идёт запись
|
||
сообщений;
|
||
2. после backup через HTTP создать пользователя с сессией, чат с
|
||
ним и сообщение в этом чате;
|
||
3. восстановить backup в новое хранилище: новый контейнер PostgreSQL
|
||
того же образа и с теми же лимитами, на новом volume;
|
||
4. сверить базы:
|
||
- число строк каждой таблицы, кроме сообщений, совпадает с
|
||
исходной базой до активности шага 2;
|
||
- каждое сообщение восстановленной базы есть в исходной с теми же
|
||
полями;
|
||
- сообщений восстановлено не меньше, чем было до начала backup;
|
||
- каждое потерянное сообщение записано после начала backup;
|
||
- индексы и ревизия схемы совпадают;
|
||
5. переключить API на восстановленную базу и через HTTP проверить:
|
||
- выбранные страницы истории совпадают с исходными;
|
||
- прежняя сессия действует;
|
||
- сессия, созданная после backup, — 401;
|
||
- запрос чата, созданного после backup, до очистки кэша — записать
|
||
ответ;
|
||
6. очистить кэш и убедиться, что чат, созданный после backup, — 404.
|
||
|
||
Любое расхождение в шагах 4–6 SHALL завершать команду с ненулевым
|
||
кодом, называя размер и расхождение. Второе хранилище и его volume
|
||
SHALL удаляться вместе со стендом, в том числе при ошибке и по Ctrl+C.
|
||
Файл backup MUST NOT попадать в каталог метки.
|
||
|
||
Для каждого размера SHALL сохраняться:
|
||
- время и размер backup, байты backup на сообщение;
|
||
- время восстановления, сбора статистики и готовности API на
|
||
восстановленной базе;
|
||
- время от начала восстановления до готовности API;
|
||
- число сообщений до backup, в исходной базе в конце и в
|
||
восстановленной, число потерянных;
|
||
- результаты проверок шагов 4–6, включая ответ на чат из кэша до
|
||
очистки.
|
||
|
||
#### Scenario: Восстановление сходится
|
||
|
||
- **WHEN** выполняется `make bench_restore`
|
||
- **THEN** на каждом размере сверка шагов 4–6 проходит, код выхода 0, в
|
||
сводке — таблица восстановления
|
||
|
||
#### Scenario: Потеря ограничена началом backup
|
||
|
||
- **WHEN** во время backup и после него через API записаны сообщения
|
||
- **THEN** в восстановленной базе нет только части этих сообщений и
|
||
сущностей шага 2, а всё, что было до начала backup, восстановлено без
|
||
изменений
|
||
|
||
#### Scenario: Кэш после восстановления
|
||
|
||
- **WHEN** API переключён на восстановленную базу
|
||
- **THEN** до очистки кэша записан ответ на чат, созданный после
|
||
backup, а после очистки — 404
|
||
|
||
#### Scenario: Расхождение
|
||
|
||
- **WHEN** у восстановленной базы отличается число строк таблицы или
|
||
поля сообщения
|
||
- **THEN** команда завершается с ненулевым кодом, называет размер и
|
||
расхождение, оба хранилища удалены
|
||
|
||
#### Scenario: Backup не в результатах
|
||
|
||
- **WHEN** прогон завершён, в том числе с ошибкой
|
||
- **THEN** в каталоге метки нет файла backup, а в `.work/` его тоже нет
|
||
|
||
### Requirement: Восстановление в отчёте
|
||
|
||
Результат `make bench_restore` SHALL быть сохранён под меткой
|
||
`restore`. Гипотезы SHALL быть записаны в `REPORT.md` до её запуска.
|
||
`REPORT.md` SHALL описывать в треке 2:
|
||
- процедуру backup и восстановления по шагам, включая очистку кэша;
|
||
- сверку: что сравнивается и с каким результатом;
|
||
- время backup и восстановления по размерам, RTO;
|
||
- границу потери данных (RPO): что теряется при логическом backup и
|
||
чем её можно сузить;
|
||
- итог по гипотезам, как получился;
|
||
- ограничения.
|
||
|
||
Числа SHALL переноситься из файлов метки, со ссылкой на них.
|
||
|
||
#### Scenario: Проверяющий ищет восстановление
|
||
|
||
- **WHEN** проверяющий открывает трек 2 в `REPORT.md`
|
||
- **THEN** он находит backup, восстановление в новое хранилище, сверку
|
||
количества и выбранных сообщений на ≥100 000 сообщениях, время
|
||
восстановления и границы потери данных со ссылками на метку
|
||
`restore`
|
||
|
||
### Requirement: Сравнение двух меток
|
||
|
||
Команда `make bench_compare BEFORE=<метка> AFTER=<метка>` SHALL
|
||
сравнивать результаты двух меток полной матрицы и сохранять таблицу в
|
||
`evidence/compare/<до>__<после>.md`. Для каждой ячейки матрицы таблица
|
||
SHALL содержать:
|
||
- медиану и разброс min–max повторов RPS в обеих метках;
|
||
- изменение медианы в процентах;
|
||
- медианы p50, p95 и p99;
|
||
- CPU приложения на один запрос.
|
||
|
||
Для каждого размера истории таблица SHALL содержать байты RSS на
|
||
сообщение и байты на сообщение в БД в обеих метках.
|
||
|
||
Команда SHALL отказываться сравнивать метки, снятые разной методикой.
|
||
Если различаются параметры профиля, лимиты любого контейнера стенда,
|
||
образы генератора, PostgreSQL или Valkey, настройки PostgreSQL, лимит
|
||
памяти и политика вытеснения Valkey или окружение приложения, она
|
||
завершается с ненулевым кодом, называет
|
||
различие и не создаёт таблицу. Параметр, записанный в паспорте только
|
||
одной из меток, SHALL перечисляться в таблице как непроверенный, без
|
||
отказа. В начале таблицы SHALL перечисляться незавершённая метка,
|
||
незакоммиченные изменения, предупреждения о хосте и помеченные
|
||
прогоны.
|
||
|
||
С необязательным параметром `AA=<метка>` команда SHALL оценивать
|
||
уровень шума: наибольшее по ячейкам сценария изменение медианы RPS
|
||
между метками `AA` и `BEFORE`, снятыми на одном и том же коде
|
||
приложения. Изменение в ячейке SHALL называться эффектом, только если
|
||
разбросы повторов двух меток не пересекаются и изменение медианы
|
||
больше уровня шума её сценария. Иначе это изменение в пределах шума.
|
||
|
||
#### Scenario: Сравнимые метки
|
||
|
||
- **WHEN** сравниваются две завершённые метки одного профиля с
|
||
одинаковыми лимитами, образами и настройками
|
||
- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня
|
||
конкуренции) с медианами, разбросом и изменением в процентах, а в
|
||
начале — commit и условия хоста каждой метки
|
||
|
||
#### Scenario: Разная методика
|
||
|
||
- **WHEN** у меток различается параметр профиля, лимит контейнера,
|
||
образ генератора или хранилища, настройка PostgreSQL, `maxmemory`
|
||
или `maxmemory-policy` Valkey или переменная окружения приложения
|
||
- **THEN** команда завершается с ненулевым кодом, называет параметр и
|
||
оба значения, таблица не создаётся
|
||
|
||
#### Scenario: Параметр только в одной метке
|
||
|
||
- **WHEN** параметр профиля записан в паспорте одной метки и отсутствует
|
||
в паспорте другой
|
||
- **THEN** сравнение выполняется, а параметр назван в таблице как
|
||
непроверенный
|
||
|
||
#### Scenario: Уровень шума
|
||
|
||
- **WHEN** задан `AA` — метка того же кода приложения, что и `BEFORE`
|
||
- **THEN** таблица содержит уровень шума по каждому сценарию и для
|
||
каждой ячейки вывод: эффект или изменение в пределах шума
|
||
|
||
#### Scenario: Метка сама с собой
|
||
|
||
- **WHEN** `BEFORE` и `AFTER` — одна и та же метка
|
||
- **THEN** изменение во всех ячейках равно нулю
|
||
|
||
### Requirement: Прогоны «до» и «после» подряд
|
||
|
||
Команда `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`
|
||
SHALL снимать метки «до» и «после» одного изменения подряд, без работы
|
||
на хосте между ними. В рабочем дереве лежит код «до», а изменение
|
||
закоммичено и откачено отдельным commit; `REAPPLY` — commit отката.
|
||
Команда SHALL выполнить по порядку:
|
||
1. полную матрицу для `BEFORE`;
|
||
2. commit её результатов;
|
||
3. возврат изменения новым commit;
|
||
4. полную матрицу для `AFTER`.
|
||
|
||
Команда SHALL отказываться стартовать, ничего не запустив, если:
|
||
- рабочее дерево не чистое;
|
||
- каталог одной из меток уже существует;
|
||
- метки совпадают;
|
||
- commit `REAPPLY` не найден в текущей ветке.
|
||
|
||
Если шаг завершился с ошибкой, следующие шаги MUST NOT выполняться, а
|
||
команда SHALL назвать этот шаг. Команда создаёт commit в текущей ветке
|
||
и MUST NOT отправлять его в удалённый репозиторий.
|
||
|
||
#### Scenario: Оба прогона без участия человека
|
||
|
||
- **WHEN** на чистом рабочем дереве выполняется `make bench_ab` со
|
||
свободными метками и commit отката
|
||
- **THEN** обе метки сняты полностью, у обеих в паспорте нет признака
|
||
незакоммиченных изменений, а код приложения между их commit
|
||
отличается возвращённым изменением
|
||
|
||
#### Scenario: Нечистое рабочее дерево
|
||
|
||
- **WHEN** в рабочем дереве есть незакоммиченные изменения
|
||
- **THEN** команда завершается с ненулевым кодом до первого шага и
|
||
называет причину
|
||
|
||
#### Scenario: Метка занята
|
||
|
||
- **WHEN** каталог метки стенда одной из меток уже существует
|
||
- **THEN** команда завершается с ненулевым кодом до первого шага и
|
||
называет путь
|
||
|
||
#### Scenario: Шаг завершился с ошибкой
|
||
|
||
- **WHEN** один из шагов вернул ненулевой код
|
||
- **THEN** следующие шаги не выполняются, команда называет номер шага
|
||
и завершается с ненулевым кодом
|
||
|
||
### Requirement: Сравнение «до/после» в отчёте
|
||
|
||
Результаты полной матрицы на коде до изменения и после него SHALL
|
||
быть сохранены под разными метками, снятыми в одной сессии хоста при
|
||
одинаковых лимитах и одном профиле. Между этими метками код приложения
|
||
SHALL отличаться одним изменением. `REPORT.md` SHALL описывать в
|
||
разделе экспериментов:
|
||
- как искали узкое место: метод, числа и путь к сохранённому выводу;
|
||
- почему прежнее решение было выбрано и что при этом не измерялось;
|
||
- что именно изменено, какие части сервиса это затрагивает и какие
|
||
свойства ответа сохраняются;
|
||
- предсказание результата, записанное до замера «после», и условие,
|
||
при котором оно считается опровергнутым;
|
||
- методику измерения дельты: какие метки сравниваются, как оценён
|
||
уровень шума и по какому правилу изменение считается эффектом;
|
||
- результаты по ячейкам со ссылкой на таблицу сравнения и каталоги
|
||
меток, включая ячейки, где эффекта нет;
|
||
- почему изменение дало такой результат и что осталось узким местом;
|
||
- ограничения сравнения.
|
||
|
||
Результат SHALL записываться таким, каким получился: если предсказание
|
||
не подтвердилось, отчёт SHALL это говорить.
|
||
|
||
#### Scenario: Проверяющий читает сравнение
|
||
|
||
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
|
||
- **THEN** он находит метод поиска узкого места, причину прежнего
|
||
решения, описание изменения и его влияния, предсказание, методику
|
||
измерения дельты, таблицу «до/после» и пути к сырым данным
|
||
|
||
#### Scenario: Одно изменение
|
||
|
||
- **WHEN** проверяющий сравнивает commit меток «до» и «после»
|
||
- **THEN** код приложения между ними отличается только описанным в
|
||
отчёте изменением
|
||
|
||
#### Scenario: Контрольные ячейки
|
||
|
||
- **WHEN** изменение затрагивает только один сценарий нагрузки
|
||
- **THEN** отчёт показывает и ячейки другого сценария, чтобы было
|
||
видно, что разница не вызвана условиями прогона
|
||
|
||
#### Scenario: Предсказание не подтвердилось
|
||
|
||
- **WHEN** изменение в ячейках оказалось в пределах шума или
|
||
противоположного знака
|
||
- **THEN** отчёт называет предсказание опровергнутым и приводит
|
||
фактические числа
|