- upload, metadata and download endpoints for PNG/JPEG attachments:
limits before reading and decompression, type by content,
structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1827 lines
120 KiB
Markdown
1827 lines
120 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 перезаписывать результаты
|
||
существующей метки. Единственное исключение — продолжение прерванной
|
||
серии трека 1 (требование «Серии трека 1»): оно дописывает в метку
|
||
только недостающие ячейки. Команда MUST NOT использовать порт 8080
|
||
хоста и MUST NOT трогать контейнеры, базу и кэш рабочего стенда (`make
|
||
run_dev` / `make run_docker`). После завершения, в том числе с ошибкой
|
||
или по Ctrl+C, контейнеры, сеть и volume стенда SHALL удаляться.
|
||
|
||
Одновременно SHALL идти не больше одного прогона стенда любого профиля.
|
||
Второй прогон завершается с ненулевым кодом до запуска стенда и
|
||
называет причину.
|
||
|
||
#### Scenario: Полная матрица
|
||
|
||
- **WHEN** выполняется `make bench BENCH_LABEL=baseline`
|
||
- **THEN** прогоняется вся матрица, результаты лежат в
|
||
`evidence/bench/baseline/`, код выхода 0
|
||
|
||
#### Scenario: Метка уже занята
|
||
|
||
- **WHEN** каталог `evidence/bench/<метка>/` уже существует, и это не
|
||
продолжение прерванной серии трека 1
|
||
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
|
||
называет каталог
|
||
|
||
#### Scenario: Рабочий стенд не затронут
|
||
|
||
- **WHEN** во время прогона запущен `make run_docker` на 8080
|
||
- **THEN** он продолжает отвечать, а его контейнеры, база и кэш не
|
||
меняются
|
||
|
||
#### Scenario: Прерывание
|
||
|
||
- **WHEN** прогон прерван Ctrl+C
|
||
- **THEN** контейнеры, сеть и volume стенда удалены, частичные
|
||
результаты помечены как незавершённые
|
||
|
||
#### Scenario: Второй прогон одновременно
|
||
|
||
- **WHEN** идёт прогон стенда, и запускается ещё один прогон любого
|
||
профиля
|
||
- **THEN** второй завершается с ненулевым кодом до запуска стенда, а
|
||
первый продолжается
|
||
|
||
### Requirement: Фиксированный стенд
|
||
|
||
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
|
||
PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по
|
||
умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
|
||
собранного из текущего checkout тем же `Dockerfile`. Исключение —
|
||
профиль поочерёдной замены. Он стартует на образе commit, заданного
|
||
методикой: образ собирается тем же `Dockerfile` из файлов этого commit
|
||
без изменения рабочего дерева. Заканчивается профиль на образе текущего
|
||
checkout. LB SHALL
|
||
запускаться из того же образа и с той же конфигурацией, что у рабочего
|
||
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
|
||
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
|
||
получает те же настройки образа плюс модуль записи планов, выключенный
|
||
вне снятия плана. В сериях трека 1 предел соединений PostgreSQL
|
||
(`max_connections`) — параметр конфигурации серии, по умолчанию 100, как
|
||
у образа. Схема БД SHALL применяться миграциями до наполнения.
|
||
|
||
Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека
|
||
1 — во всех прогонах одной конфигурации:
|
||
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
|
||
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по
|
||
конфигурации);
|
||
- у LB, PostgreSQL и Valkey — свои лимиты CPU и памяти без swap,
|
||
заданные методикой; в серии трека 1 они одинаковы во всех
|
||
конфигурациях;
|
||
- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без
|
||
swap, заданный методикой; в остальных профилях генератор без лимита.
|
||
|
||
Healthcheck образа приложения SHALL быть отключён: готовность реплик
|
||
проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки
|
||
приложения и хранилищ SHALL браться из методики стенда, а не из `.env`
|
||
и `config.toml` рабочего стенда. Пароли хранилищ SHALL генерироваться
|
||
на прогон. Генератор нагрузки SHALL работать в той же docker-сети и
|
||
обращаться к приложению через LB по имени сервиса, минуя проброс
|
||
портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми
|
||
все реплики.
|
||
|
||
#### Scenario: Лимиты в паспорте
|
||
|
||
- **WHEN** прогон завершён
|
||
- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти
|
||
реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных
|
||
контейнеров, и они одинаковы для всех размеров
|
||
|
||
#### Scenario: Лимиты конфигурации серии
|
||
|
||
- **WHEN** серия трека 1 завершена
|
||
- **THEN** паспорт по каждой конфигурации содержит число реплик, лимиты
|
||
CPU и памяти каждого контейнера стенда и генератора и предел
|
||
соединений PostgreSQL, прочитанные у запущенных контейнеров, и они
|
||
одинаковы во всех повторах конфигурации
|
||
|
||
#### Scenario: Нехватка памяти
|
||
|
||
- **WHEN** процесс приложения превысил лимит памяти и был убит
|
||
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
|
||
обычный результат
|
||
|
||
#### Scenario: Настройки рабочего стенда не влияют
|
||
|
||
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
|
||
отсутствуют
|
||
- **THEN** стенд запускается с теми же настройками приложения и
|
||
хранилищ, а окружение приложения в паспорте то же
|
||
|
||
#### Scenario: Схема до наполнения
|
||
|
||
- **WHEN** начинается наполнение размера
|
||
- **THEN** миграции применены до последней ревизии, и приложение
|
||
отвечает готовностью
|
||
|
||
#### Scenario: Одна реплика за балансировщиком
|
||
|
||
- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`,
|
||
`restore_quick`) запущен с одной репликой
|
||
- **THEN** все запросы генератора проходят через LB, прогон завершается
|
||
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
|
||
разделы, что раньше
|
||
|
||
#### Scenario: Образ прежнего commit
|
||
|
||
- **WHEN** запускается профиль поочерёдной замены
|
||
- **THEN** реплики стартуют на образе commit из методики, схема — на
|
||
его последней ревизии, рабочее дерево не меняется, а commit и образы
|
||
до и после записаны в паспорт
|
||
|
||
### 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.
|
||
|
||
При нескольких репликах CPU, RSS и память приложения SHALL быть суммой
|
||
по всем репликам. При одной реплике они совпадают со значениями её
|
||
процесса.
|
||
|
||
Для каждого размера 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
|
||
|
||
#### Scenario: Сумма по репликам
|
||
|
||
- **WHEN** прогон идёт с двумя репликами
|
||
- **THEN** CPU и 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; у серий трека 1 — свои
|
||
таблицы и сводка (требование «Метрики ступени серии»);
|
||
- паспорт стенда;
|
||
- состояние хоста в начале и в конце прогона: занятый swap, счётчик
|
||
выгрузок страниц в swap, доля свободной памяти, питание от сети или
|
||
от батареи, а также прирост выгрузок за прогон.
|
||
|
||
Паспорт стенда SHALL содержать:
|
||
- дату, commit и признак незакоммиченных изменений;
|
||
- digest образа приложения и версии его библиотек;
|
||
- образы и версии PostgreSQL и Valkey;
|
||
- настройки PostgreSQL, от которых зависят план запроса и стоимость
|
||
записи;
|
||
- окружение приложения без паролей;
|
||
- версии генератора и Python;
|
||
- лимиты всех контейнеров стенда;
|
||
- железо хоста и VM, в том числе число производительных и
|
||
энергоэффективных ядер, если процессор их различает;
|
||
- параметры профиля, включая уровни фоновых чатов и варианты индекса,
|
||
и команду запуска.
|
||
|
||
Если хост в начале или в конце прогона работает от батареи или за
|
||
прогон шла выгрузка страниц в swap (счётчик выгрузок вырос), команда
|
||
SHALL предупреждать об этом в выводе и в паспорте, но не прерываться.
|
||
Занятый swap без выгрузки во время прогона предупреждения не даёт.
|
||
Данные MUST быть синтетическими. Результаты MUST NOT содержать секретов
|
||
(паролей и токенов стенда), `.env` и абсолютных путей домашнего
|
||
каталога.
|
||
|
||
#### Scenario: Повтор на другой машине
|
||
|
||
- **WHEN** другой человек берёт паспорт и команду из каталога метки
|
||
- **THEN** он может запустить тот же профиль на своём checkout и
|
||
сравнить таблицы по тем же столбцам
|
||
|
||
#### Scenario: Условия хоста для сравнения меток
|
||
|
||
- **WHEN** проверяющий сравнивает две метки
|
||
- **THEN** по паспортам видно, одинаковы ли были питание и свободная
|
||
память хоста в начале и в конце каждого прогона и шла ли во время
|
||
прогона выгрузка в swap
|
||
|
||
#### Scenario: Неподходящий хост
|
||
|
||
- **WHEN** прогон идёт от батареи или во время прогона шла выгрузка
|
||
страниц в swap
|
||
- **THEN** вывод команды и паспорт содержат предупреждение, а прогон
|
||
продолжается
|
||
|
||
#### Scenario: Занятый swap без выгрузки
|
||
|
||
- **WHEN** swap занят с начала прогона, но за прогон счётчик выгрузок
|
||
не вырос
|
||
- **THEN** предупреждения о swap нет, а занятый объём записан в
|
||
паспорт
|
||
|
||
#### 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 на
|
||
сообщение и байты на сообщение в БД в обеих метках.
|
||
|
||
Метки серий трека 1 команда SHALL сравнивать по общим конфигурациям.
|
||
Для каждой общей конфигурации таблица SHALL содержать:
|
||
- медиану и разброс min–max повторов максимальной устойчивой
|
||
интенсивности (R*) в обеих метках и изменение медианы в процентах;
|
||
- медианы p95 и p99 на фиксированных уровнях интенсивности;
|
||
- CPU приложения на один успешный запрос на фиксированном уровне;
|
||
- CPU PostgreSQL на уровне R*.
|
||
|
||
Вторая таблица меток серий SHALL показывать по каждой общей
|
||
конфигурации две ступени: R* и первую ступень выше неё, нарушившую SLO.
|
||
На каждой — медианы по повторам в обеих метках:
|
||
- уровень интенсивности;
|
||
- CPU PostgreSQL на один успешный запрос;
|
||
- число новых сессий PostgreSQL за окно замера;
|
||
- наибольшее число соединений с PostgreSQL.
|
||
|
||
Конфигурации, которые есть только в одной метке, SHALL перечисляться
|
||
как несравнённые. В шапке таблицы SHALL быть команда и спек. Ещё в ней
|
||
SHALL быть change, к которому относится сравнение: параметр `CHANGE`,
|
||
без него — change, который ввёл сравнение серий.
|
||
|
||
Команда SHALL отказываться сравнивать метки, снятые разной методикой.
|
||
Если различаются параметры профиля, лимиты любого контейнера стенда,
|
||
образы генератора, PostgreSQL или Valkey, настройки PostgreSQL, лимит
|
||
памяти и политика вытеснения Valkey или окружение приложения, она
|
||
завершается с ненулевым кодом, называет различие и не создаёт таблицу.
|
||
У меток серий трека 1 состав конфигураций и имя серии к методике не
|
||
относятся, а лимиты контейнеров и предел соединений PostgreSQL
|
||
сравниваются по каждой общей конфигурации. Метку серии трека 1 и метку
|
||
матрицы команда SHALL отказываться сравнивать. Метка, снятая без
|
||
балансировщика (в её паспорте нет числа реплик), и метка стенда с
|
||
балансировщиком тоже сняты разной методикой: команда SHALL отказываться
|
||
их сравнивать. Остальной параметр, записанный в паспорте только одной
|
||
из меток, SHALL перечисляться в таблице как непроверенный, без отказа.
|
||
В начале таблицы SHALL перечисляться незавершённая метка,
|
||
незакоммиченные изменения, предупреждения о хосте и помеченные прогоны.
|
||
|
||
С необязательным параметром `AA=<метка>` команда SHALL оценивать
|
||
уровень шума между метками `AA` и `BEFORE`, снятыми на одном и том же
|
||
коде приложения:
|
||
- для матрицы — наибольшее по ячейкам сценария изменение медианы RPS;
|
||
- для серий трека 1 — наибольшее по общим конфигурациям изменение
|
||
медианы R*.
|
||
|
||
Изменение в ячейке или конфигурации SHALL называться эффектом, только
|
||
если разбросы повторов двух меток не пересекаются и изменение медианы
|
||
больше уровня шума её сценария или серии. Иначе это изменение в
|
||
пределах шума.
|
||
|
||
#### Scenario: Сравнимые метки
|
||
|
||
- **WHEN** сравниваются две завершённые метки одного профиля с
|
||
одинаковыми лимитами, образами и настройками
|
||
- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня
|
||
конкуренции) с медианами, разбросом и изменением в процентах, а в
|
||
начале — commit и условия хоста каждой метки
|
||
|
||
#### Scenario: Разная методика
|
||
|
||
- **WHEN** у меток различается параметр профиля, лимит контейнера,
|
||
образ генератора или хранилища, настройка PostgreSQL, `maxmemory`
|
||
или `maxmemory-policy` Valkey или переменная окружения приложения
|
||
- **THEN** команда завершается с ненулевым кодом, называет параметр и
|
||
оба значения, таблица не создаётся
|
||
|
||
#### Scenario: Метка без балансировщика
|
||
|
||
- **WHEN** одна метка снята до перехода стенда на балансировщик (в
|
||
паспорте нет числа реплик), а другая — на стенде с балансировщиком
|
||
- **THEN** команда завершается с ненулевым кодом, называет метку без
|
||
балансировщика, таблица не создаётся
|
||
|
||
#### Scenario: Параметр только в одной метке
|
||
|
||
- **WHEN** параметр профиля записан в паспорте одной метки и отсутствует
|
||
в паспорте другой, и обе метки сняты на стенде с балансировщиком или
|
||
обе без него
|
||
- **THEN** сравнение выполняется, а параметр назван в таблице как
|
||
непроверенный
|
||
|
||
#### Scenario: Уровень шума
|
||
|
||
- **WHEN** задан `AA` — метка того же кода приложения, что и `BEFORE`
|
||
- **THEN** таблица содержит уровень шума по каждому сценарию и для
|
||
каждой ячейки вывод: эффект или изменение в пределах шума
|
||
|
||
#### Scenario: Метка сама с собой
|
||
|
||
- **WHEN** `BEFORE` и `AFTER` — одна и та же метка
|
||
- **THEN** изменение во всех ячейках равно нулю
|
||
|
||
#### Scenario: Серии трека 1
|
||
|
||
- **WHEN** сравниваются метка серии `b` и метка серии `ab`, снятые на
|
||
том же коде
|
||
- **THEN** таблица содержит только общие конфигурации с медианой и
|
||
разбросом R*, изменением в процентах, задержками на фиксированных
|
||
уровнях и CPU на запрос, а остальные конфигурации серии `b`
|
||
перечислены как несравнённые
|
||
|
||
#### Scenario: Серия и матрица
|
||
|
||
- **WHEN** одна метка — серия трека 1, а другая — полная матрица
|
||
- **THEN** команда завершается с ненулевым кодом и называет различие
|
||
методики, таблица не создаётся
|
||
|
||
#### Scenario: PostgreSQL в сравнении серий
|
||
|
||
- **WHEN** сравниваются две метки серии трека 1 с параметром `CHANGE`
|
||
- **THEN** вторая таблица по каждой общей конфигурации показывает на
|
||
ступени R* и на первой нарушившей ступени уровень, CPU PostgreSQL на
|
||
запрос, новые сессии PostgreSQL за окно и соединения в обеих метках
|
||
- **AND** шапка называет change из `CHANGE`
|
||
|
||
### Requirement: Прогоны «до» и «после» подряд
|
||
|
||
Команда `make bench_ab BEFORE=<метка> AFTER=<метка> REAPPLY=<commit>`
|
||
SHALL снимать метки «до» и «после» одного изменения подряд, без работы
|
||
на хосте между ними. В рабочем дереве лежит код «до», а изменение
|
||
закоммичено и откачено отдельным commit; `REAPPLY` — commit отката.
|
||
Команда SHALL выполнить по порядку:
|
||
1. полную матрицу для `BEFORE`;
|
||
2. commit её результатов;
|
||
3. возврат изменения новым commit;
|
||
4. полную матрицу для `AFTER`.
|
||
|
||
С параметром `SERIES=<серия>` команда SHALL снимать в шагах 1 и 4
|
||
вместо полной матрицы серию трека 1 под метками `BEFORE` и `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** следующие шаги не выполняются, команда называет номер шага
|
||
и завершается с ненулевым кодом
|
||
|
||
#### Scenario: «До» и «после» на серии
|
||
|
||
- **WHEN** выполняется `make bench_ab` с `SERIES=ab`
|
||
- **THEN** обе метки — полные серии `ab` без признака незакоммиченных
|
||
изменений, и `make bench_compare` сравнивает их по общим
|
||
конфигурациям
|
||
|
||
### Requirement: Сравнение «до/после» в отчёте
|
||
|
||
Результаты полной матрицы или серии трека 1 на коде до изменения и
|
||
после него SHALL быть сохранены под разными метками, снятыми в одной
|
||
сессии хоста при одинаковых лимитах и одном профиле. Между этими
|
||
метками код приложения SHALL отличаться одним изменением.
|
||
|
||
Для серии трека 1 действуют ещё три правила:
|
||
- метка уровня шума (A/A) SHALL сниматься на том же коде «до» и в той
|
||
же сессии хоста, перед метками «до» и «после»;
|
||
- сдвиг R* SHALL засчитываться эффектом, только если сравнение
|
||
называет его эффектом и медиана сдвинулась не меньше чем на две
|
||
ступени сетки поиска, то есть в √1,25 ≈ 1,118 раза;
|
||
- в той же серии SHALL быть контрольная конфигурация, где изменение
|
||
эффекта давать не должно.
|
||
|
||
`REPORT.md` SHALL описывать в разделе экспериментов:
|
||
- как искали узкое место: метод, числа и путь к сохранённому выводу;
|
||
- почему прежнее решение было выбрано и что при этом не измерялось;
|
||
- что именно изменено, какие части сервиса это затрагивает и какие
|
||
свойства ответа сохраняются;
|
||
- предсказание результата, записанное до замера «после», и условие,
|
||
при котором оно считается опровергнутым;
|
||
- методику измерения дельты: какие метки сравниваются, как оценён
|
||
уровень шума и по какому правилу изменение считается эффектом;
|
||
- результаты по ячейкам или конфигурациям со ссылкой на таблицу
|
||
сравнения и каталоги меток, включая те, где эффекта нет;
|
||
- почему изменение дало такой результат и что осталось узким местом;
|
||
- ограничения сравнения.
|
||
|
||
Результат SHALL записываться таким, каким получился: если предсказание
|
||
не подтвердилось, отчёт SHALL это говорить.
|
||
|
||
#### Scenario: Проверяющий читает сравнение
|
||
|
||
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
|
||
- **THEN** он находит метод поиска узкого места, причину прежнего
|
||
решения, описание изменения и его влияния, предсказание, методику
|
||
измерения дельты, таблицу «до/после» и пути к сырым данным
|
||
|
||
#### Scenario: Одно изменение
|
||
|
||
- **WHEN** проверяющий сравнивает commit меток «до» и «после»
|
||
- **THEN** код приложения между ними отличается только описанным в
|
||
отчёте изменением
|
||
|
||
#### Scenario: Контрольные ячейки
|
||
|
||
- **WHEN** изменение затрагивает только один сценарий нагрузки
|
||
- **THEN** отчёт показывает и ячейки другого сценария, чтобы было
|
||
видно, что разница не вызвана условиями прогона
|
||
|
||
#### Scenario: Предсказание не подтвердилось
|
||
|
||
- **WHEN** изменение в ячейках оказалось в пределах шума или
|
||
противоположного знака
|
||
- **THEN** отчёт называет предсказание опровергнутым и приводит
|
||
фактические числа
|
||
|
||
#### Scenario: Улучшение на серии трека 1
|
||
|
||
- **WHEN** изменение измерено на серии трека 1
|
||
- **THEN** отчёт называет метку A/A того же кода и той же сессии,
|
||
основную и контрольную конфигурации, R* «до» и «после» с разбросом и
|
||
выводом сравнения и сдвиг основной конфигурации в ступенях сетки
|
||
- **AND** механизм изменения показан числами из таблиц команд, а не
|
||
пересчётом вручную
|
||
|
||
### Requirement: Профиль отказа реплик
|
||
|
||
Команда `make bench_failover` (метка `FAILOVER_LABEL`) SHALL на свежем
|
||
стенде с двумя репликами и лимитами рабочего стенда по очереди
|
||
останавливать каждую реплику под нагрузкой и восстанавливать её. Команда
|
||
`make bench_failover_quick` — то же короче, метка `quick-failover-…`, в
|
||
git не идёт. Результаты SHALL сохраняться в `evidence/failover/<метка>/`.
|
||
Занятая метка SHALL давать отказ до запуска стенда.
|
||
|
||
Нагрузка — постоянная интенсивность, заданная методикой: запись
|
||
сообщения с `Idempotency-Key` и чтение страницы истории. Фаза — одна
|
||
реплика в одном режиме:
|
||
1. установившаяся нагрузка;
|
||
2. действие над репликой: `stop`, `kill` или `pause`;
|
||
3. окно отказа;
|
||
4. восстановление: запуск того же контейнера или разморозка;
|
||
5. нагрузка после возврата.
|
||
|
||
Режимы полного профиля — `stop`, `kill` и `pause`, быстрого — `stop` и
|
||
`kill`. Перед каждой фазой LB SHALL видеть готовыми обе реплики.
|
||
|
||
Для каждой фазы SHALL сохраняться посекундная шкала от момента
|
||
действия:
|
||
- успешные записи и чтения;
|
||
- ошибки по кодам, ошибка соединения — отдельным кодом;
|
||
- доля успешных;
|
||
- p50 и p95 задержки успешных;
|
||
- распределение ответов по `X-Instance-Id`.
|
||
|
||
Секунда запроса определяется по моменту его отправки.
|
||
|
||
Для каждой фазы SHALL сохраняться:
|
||
- момент действия по событию Docker;
|
||
- время до исключения реплики LB по его журналу;
|
||
- время до первой успешной записи и первого успешного чтения после
|
||
действия;
|
||
- число ошибок по кодам в окне отказа и после возврата;
|
||
- время восстановления до доли успешных ≥ 99 % (`load-balancing`);
|
||
- время до возврата реплики в LB.
|
||
|
||
Для каждой фазы SHALL сохраняться ресурсы стенда по требованию «Ресурсы
|
||
профилей отказа и замены». Окна:
|
||
- до действия — от конца разгона генератора;
|
||
- окно отказа — от действия до возврата;
|
||
- после возврата — до последнего запроса фазы.
|
||
|
||
Компоненты — каждая реплика отдельно, с её `X-Instance-Id` и пометкой,
|
||
над какой выполнено действие, сумма по репликам, PostgreSQL, LB, Valkey,
|
||
генератор и ВМ.
|
||
|
||
После каждой фазы каждая неподтверждённая запись SHALL повторяться с
|
||
тем же ключом и тем же телом до ответа 201. Число сообщений чата записи
|
||
SHALL совпадать с числом разных ключей, отправленных за прогон, а
|
||
одинаковых текстов в нём MUST NOT быть. Иначе команда завершается с
|
||
ненулевым кодом и называет фазу.
|
||
|
||
#### Scenario: Полный профиль
|
||
|
||
- **WHEN** выполнен `make bench_failover`
|
||
- **THEN** в `evidence/failover/<метка>/` есть шесть фаз (две реплики ×
|
||
три режима) с посекундными шкалами, таблица фаз, ресурсы по окнам
|
||
фаз и сводка, код выхода 0
|
||
|
||
#### Scenario: Быстрый профиль
|
||
|
||
- **WHEN** выполнен `make bench_failover_quick`
|
||
- **THEN** за несколько минут проходят четыре фазы (две реплики ×
|
||
`stop` и `kill`) с ресурсами по окнам, код выхода 0, каталог метки в
|
||
git не попадает
|
||
|
||
#### Scenario: Время обнаружения в результатах
|
||
|
||
- **WHEN** фаза завершена
|
||
- **THEN** в таблице фаз есть момент действия, время до исключения
|
||
реплики, время до первых успешных ответов, время восстановления и
|
||
время до возврата реплики, все на часах ВМ Docker
|
||
|
||
#### Scenario: Без потерь и дублей
|
||
|
||
- **WHEN** в окне отказа часть записей получила ошибку
|
||
- **THEN** их повтор с тем же ключом получает 201, а в чате записи
|
||
столько сообщений, сколько разных ключей отправлено, без одинаковых
|
||
текстов
|
||
|
||
#### Scenario: Хранилище упало во время фазы
|
||
|
||
- **WHEN** контейнер PostgreSQL или Valkey был убит или перезапущен во
|
||
время фазы
|
||
- **THEN** команда завершается с ненулевым кодом, называет контейнер, а
|
||
стенд удаляется
|
||
|
||
#### Scenario: Ресурсы фазы
|
||
|
||
- **WHEN** фаза завершена
|
||
- **THEN** в таблице ресурсов для каждого из трёх окон есть CPU (среднее
|
||
и посекундный максимум) и пик памяти реплики, над которой выполнено
|
||
действие, и второй реплики с их `X-Instance-Id`, а также суммы по
|
||
репликам, PostgreSQL, LB, Valkey, генератора и занятые ядра ВМ
|
||
- **AND** посекундная таблица содержит те же компоненты в секундах от
|
||
момента действия, на тех же часах, что шкала фазы
|
||
|
||
#### Scenario: Реплика остановлена или заморожена
|
||
|
||
- **WHEN** реплика остановлена `stop`, убита `kill` или заморожена
|
||
`pause`, а затем возвращена
|
||
- **THEN** её CPU в окне отказа учтён только до остановки, у
|
||
замороженной — без прироста, после возврата счёт продолжается от
|
||
запуска или разморозки, а значения второй реплики и остальных
|
||
компонентов есть во всех окнах
|
||
|
||
### Requirement: Профиль поочерёдной замены
|
||
|
||
Команда `make bench_rollout` (метка `ROLLOUT_LABEL`) SHALL на свежем
|
||
стенде с лимитами рабочего стенда и `API_REPLICAS` по методике
|
||
выполнять поочерёдную замену реплик (`scripts/rolling-update.sh`,
|
||
`load-balancing`) под нагрузкой. Реплики стартуют на образе прежнего
|
||
commit и заменяются на образ текущего checkout. Команда `make
|
||
bench_rollout_quick` делает то же с короткими окнами, метка
|
||
`quick-rollout-…`, в git она не идёт. Результаты SHALL сохраняться в
|
||
`evidence/rollout/<метка>/`. Занятая метка SHALL давать отказ до
|
||
запуска стенда.
|
||
|
||
Нагрузка — постоянная интенсивность, заданная методикой: запись
|
||
сообщения с `Idempotency-Key` и чтение страницы истории. Скрипт
|
||
замены SHALL запускаться через заданное методикой время после начала
|
||
нагрузки. Нагрузка SHALL продолжаться после его завершения. Скрипт
|
||
SHALL быть тем же, что у рабочего стенда, и выполняться против проекта
|
||
compose стенда.
|
||
|
||
SHALL сохраняться посекундная шкала от начала замены (создание
|
||
контейнера миграции):
|
||
- успешные записи и чтения;
|
||
- ошибки по кодам;
|
||
- доля успешных;
|
||
- p50 и p95 задержки успешных;
|
||
- число успешных ответов старых и новых реплик;
|
||
- распределение ответов по `X-Instance-Id`.
|
||
|
||
По каждой заменённой реплике SHALL сохраняться:
|
||
- время от запуска новой реплики до её `UP` в LB;
|
||
- время дренажа старой реплики;
|
||
- время её остановки;
|
||
- время замены целиком.
|
||
|
||
Для прогона целиком SHALL сохраняться:
|
||
- длительность замены;
|
||
- ошибки по кодам до, во время и после замены;
|
||
- минимальная доля успешных в секунде;
|
||
- контейнеры, их образы и ревизия схемы до и после.
|
||
|
||
Ресурсы стенда SHALL сохраняться по требованию «Ресурсы профилей отказа
|
||
и замены». Окна:
|
||
- до запуска скрипта — от конца разгона генератора;
|
||
- подготовка — от первого обращения скрипта к стенду до начала замены:
|
||
проверки и сборка образа;
|
||
- замена — от начала замены до удаления последней старой реплики;
|
||
- после замены — до последнего запроса.
|
||
|
||
Компоненты — каждая старая и каждая новая реплика отдельно, с её
|
||
`X-Instance-Id`, сумма по репликам с пиком их общей памяти, контейнер
|
||
миграции, PostgreSQL, LB, Valkey, генератор и ВМ.
|
||
|
||
После прогона каждая неподтверждённая запись SHALL повторяться с тем
|
||
же ключом и телом до 201. Число сообщений чата записи SHALL совпадать
|
||
с числом отправленных ключей, одинаковых текстов MUST NOT быть.
|
||
|
||
Команда SHALL завершаться с ненулевым кодом в случаях:
|
||
- скрипт замены вернул ненулевой код;
|
||
- генератор упал;
|
||
- PostgreSQL или Valkey падал;
|
||
- сверка не сошлась;
|
||
- в конце работает не `API_REPLICAS` реплик;
|
||
- среди работающих реплик есть реплика прежнего образа;
|
||
- не все реплики `UP` в LB.
|
||
|
||
Ошибки клиента при замене — результат, а не отказ команды: они
|
||
считаются и показываются.
|
||
|
||
#### Scenario: Полный профиль
|
||
|
||
- **WHEN** выполнен `make bench_rollout`
|
||
- **THEN** в `evidence/rollout/<метка>/` есть посекундная шкала, таблица
|
||
шагов по каждой заменённой реплике, ресурсы по окнам, сводка,
|
||
контейнеры и образы до и после, код выхода 0
|
||
|
||
#### Scenario: Быстрый профиль
|
||
|
||
- **WHEN** выполнен `make bench_rollout_quick`
|
||
- **THEN** за несколько минут проходит замена всех реплик с ресурсами
|
||
по окнам, код выхода 0, каталог метки в git не попадает
|
||
|
||
#### Scenario: Версии в ответах
|
||
|
||
- **WHEN** замена завершена
|
||
- **THEN** шкала показывает, как доля ответов старых реплик падает до
|
||
нуля, а новых растёт до всех, а ответов прежних `X-Instance-Id` после
|
||
удаления их контейнеров нет
|
||
|
||
#### Scenario: Без потерь и дублей при замене
|
||
|
||
- **WHEN** нагрузка с записью шла всё время замены
|
||
- **THEN** после повтора неподтверждённых записей с тем же ключом в чате
|
||
записи столько сообщений, сколько отправлено ключей, без одинаковых
|
||
текстов
|
||
|
||
#### Scenario: Замена не удалась
|
||
|
||
- **WHEN** скрипт замены завершился с ненулевым кодом
|
||
- **THEN** команда завершается с ненулевым кодом, называет шаг из
|
||
журнала скрипта, сохраняет частичные результаты и удаляет стенд
|
||
|
||
#### Scenario: Ресурсы замены
|
||
|
||
- **WHEN** замена завершена
|
||
- **THEN** в таблице ресурсов для окон до, подготовки, замены и после
|
||
есть CPU и пик памяти каждой старой и каждой новой реплики с их
|
||
`X-Instance-Id`, контейнера миграции, суммы по репликам с пиком их
|
||
общей памяти, PostgreSQL, LB, Valkey, генератора и занятые ядра ВМ
|
||
- **AND** CPU на успешный запрос указан для окон до и после замены
|
||
|
||
#### Scenario: Новая реплика с первых секунд
|
||
|
||
- **WHEN** скрипт запускает новую реплику посреди нагрузки
|
||
- **THEN** её CPU и память есть в посекундной таблице с первого отсчёта
|
||
после её запуска, а CPU от запуска до этого отсчёта входит в окно, где
|
||
она запущена
|
||
|
||
### Requirement: Ресурсы профилей отказа и замены
|
||
|
||
Профили отказа реплик и поочерёдной замены, полные и быстрые, SHALL всё
|
||
время нагрузки снимать не реже раза в секунду, на часах ВМ Docker:
|
||
- CPU, троттлинг CFS и память каждого контейнера стенда — каждой
|
||
реплики приложения, PostgreSQL, LB, Valkey и контейнера миграции;
|
||
- те же величины генератора нагрузки и самого наблюдателя;
|
||
- загрузку CPU ВМ.
|
||
|
||
Контейнер, созданный во время прогона, SHALL учитываться с первого
|
||
отсчёта после его запуска, без перезапуска наблюдения. CPU от запуска
|
||
контейнера до первого отсчёта MUST NOT теряться. Остановленный,
|
||
убитый, замороженный, пересозданный или удалённый контейнер MUST NOT
|
||
ломать расчёт:
|
||
- пока контейнера нет, он не потребляет CPU и не даёт отсчётов памяти;
|
||
- у замороженного CPU не прирастает, память остаётся;
|
||
- у запущенного снова счёт идёт с нуля от момента запуска.
|
||
|
||
Отсчёты контейнеров вне стенда MUST NOT попадать в результаты.
|
||
|
||
Для каждого окна прогона (требования профилей) и каждого компонента
|
||
SHALL сохраняться:
|
||
- среднее CPU за окно — CPU-секунды, делённые на длину окна;
|
||
- наибольшее посекундное CPU;
|
||
- пик памяти;
|
||
- доля периодов CFS с троттлингом;
|
||
- сколько секунд окна контейнер работал;
|
||
- у реплик ещё сумма по всем репликам с пиком их общей памяти;
|
||
- у ВМ — среднее и наибольшее посекундное число занятых ядер.
|
||
|
||
CPU на один успешный запрос SHALL указываться только в установившихся
|
||
окнах: до действия у профиля отказа, до и после замены у профиля
|
||
замены. В остальных окнах его MUST NOT указывать: там CPU уходит на
|
||
ошибки и ожидание, на остановку и запуск процессов, на миграцию и
|
||
сборку, а не пропорционально успешным ответам. Сводка SHALL называть эту
|
||
причину.
|
||
|
||
Посекундные значения SHALL сохраняться таблицей: фаза, окно, секунды от
|
||
опорного момента (действие над репликой или начало замены), компонент,
|
||
CPU, троттлинг, ожидание CPU и память. Значения по окнам SHALL
|
||
сохраняться второй таблицей. Сводка метки SHALL показывать их по
|
||
компонентам и окнам.
|
||
|
||
Наблюдение MUST NOT менять методику профиля: нагрузку, фазы, окна,
|
||
лимиты стенда и пороги. Генератор остаётся без лимита. Наблюдатель:
|
||
- SHALL работать в своём контейнере со своим лимитом CPU и памяти без
|
||
swap; лимит читается у запущенного контейнера и пишется в паспорт;
|
||
- SHALL брать отсчёты только из счётчиков cgroup контейнеров и ВМ;
|
||
- MUST NOT запускать процессы в контейнерах стенда и MUST NOT
|
||
обращаться к приложению, хранилищам и LB.
|
||
|
||
Сумма лимитов CPU стенда на пике прогона и наблюдателя MUST NOT
|
||
превышать число CPU ВМ. На пике профиля замены работает `API_REPLICAS`
|
||
+ 1 реплик. Иначе команда завершается с ненулевым кодом до запуска
|
||
стенда. Паспорт SHALL содержать сумму лимитов CPU и памяти, а также CPU
|
||
и память ВМ.
|
||
|
||
Если в окне нагрузки отсчётов нет дольше трёх секунд или наблюдатель
|
||
остановился, команда SHALL завершаться с ненулевым кодом и называть
|
||
фазу.
|
||
|
||
#### Scenario: Ресурсы в результатах
|
||
|
||
- **WHEN** выполнен `make bench_failover` или `make bench_rollout`
|
||
- **THEN** в каталоге метки есть посекундная таблица и таблица по
|
||
окнам, сводка показывает CPU и память каждого компонента по окнам, а
|
||
паспорт — лимит наблюдателя и бюджет ВМ
|
||
|
||
#### Scenario: Контейнер вне стенда
|
||
|
||
- **WHEN** во время прогона в ВМ работает контейнер другого проекта
|
||
- **THEN** его отсчётов нет ни в посекундной таблице, ни в таблице по
|
||
окнам
|
||
|
||
#### Scenario: Бюджет ВМ
|
||
|
||
- **WHEN** сумма лимитов CPU стенда на пике и наблюдателя больше числа
|
||
CPU ВМ
|
||
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
|
||
называет сумму и число CPU ВМ
|
||
|
||
#### Scenario: Наблюдение не меняет методику
|
||
|
||
- **WHEN** проверяющий сравнивает паспорт новой метки профиля с
|
||
паспортом прежней метки того же профиля
|
||
- **THEN** нагрузка, окна, лимиты стенда и пороги совпадают, генератор
|
||
без лимита в обеих, а новые поля относятся только к наблюдению
|
||
|
||
#### Scenario: CPU на запрос только в установившихся окнах
|
||
|
||
- **WHEN** окно содержит действие над репликой, её возврат, миграцию
|
||
или замену реплик
|
||
- **THEN** CPU на успешный запрос для этого окна не указан, а сводка
|
||
называет причину
|
||
|
||
#### Scenario: Наблюдатель остановился
|
||
|
||
- **WHEN** во время нагрузки отсчётов нет дольше трёх секунд
|
||
- **THEN** команда завершается с ненулевым кодом и называет фазу, а
|
||
стенд удаляется
|
||
|
||
#### Scenario: Наблюдатель не нагружает стенд
|
||
|
||
- **WHEN** идёт нагрузка профиля отказа или замены
|
||
- **THEN** у PostgreSQL нет соединений наблюдателя, в контейнерах стенда
|
||
нет его процессов, а его собственные CPU и память видны в таблицах
|
||
отдельным компонентом
|
||
|
||
### Requirement: Ресурсы профилей отказа и замены в отчёте
|
||
|
||
Метки профилей отказа и замены с ресурсами SHALL сохраняться в
|
||
`evidence/failover/` и `evidence/rollout/`. Их снимают с закоммиченного
|
||
кода на хосте, состояние которого записано в паспорт. `REPORT.md` SHALL
|
||
показывать для обоих профилей:
|
||
- CPU и память по компонентам и окнам;
|
||
- CPU на запрос в установившихся окнах;
|
||
- занятые ядра ВМ;
|
||
- лимиты и бюджет ВМ;
|
||
- накладные расходы наблюдения: его собственные CPU и память;
|
||
- ограничения замера.
|
||
|
||
Числа SHALL переноситься из файлов меток, со ссылками на них.
|
||
|
||
Результаты новых меток по доступности SHALL стоять рядом с прежними
|
||
метками тех же профилей, с названными различиями условий: commit и
|
||
хост. Для профиля отказа это исключение из LB, ошибки, восстановление,
|
||
возврат в LB и сверка записей. Для профиля замены — ошибки,
|
||
длительность и шаги замены, ответы старых реплик после дренажа и
|
||
сверка записей. Если результаты расходятся, отчёт SHALL это говорить и
|
||
называть причину, а если она не установлена — говорить и это.
|
||
|
||
#### Scenario: Проверяющий ищет CPU и память при отказе
|
||
|
||
- **WHEN** проверяющий открывает в `REPORT.md` раздел отказа реплик или
|
||
поочерёдной замены
|
||
- **THEN** он находит CPU и память каждой реплики, PostgreSQL, LB,
|
||
Valkey, генератора и ВМ по окнам, CPU на запрос в установившихся
|
||
окнах, накладные расходы наблюдения и пути к файлам меток
|
||
|
||
#### Scenario: Новая метка расходится с прежней
|
||
|
||
- **WHEN** в новой метке число ошибок, время исключения, восстановления
|
||
или шаги замены отличаются от прежней метки сверх её разброса
|
||
- **THEN** отчёт приводит оба значения, называет различия условий и
|
||
причину расхождения или пишет, что она не установлена
|
||
|
||
### Requirement: Серии трека 1
|
||
|
||
Команда `make bench_scaling SERIES=<серия>` SHALL снимать серию трека 1
|
||
«Цена масштабирования» под меткой `SCALING_LABEL` (по умолчанию
|
||
`scaling-<серия>`) в `evidence/bench/<метка>/`. Серия — набор
|
||
конфигураций стенда. Конфигурация задаёт число реплик приложения, лимит
|
||
CPU и памяти реплики и предел соединений PostgreSQL. Серии:
|
||
- `a` — фиксированный суммарный бюджет приложения 4 CPU / 2 ГиБ:
|
||
1 реплика × 4 CPU / 2 ГиБ, 2 × 2 CPU / 1 ГиБ, 4 × 1 CPU / 512 МиБ;
|
||
- `b` — рост ресурсов: 1, 2, 3, 4, 5 и 6 реплик по 1 CPU / 512 МиБ;
|
||
- `pool` — граница пула: 4 реплики по 1 CPU / 512 МиБ при пределе
|
||
соединений PostgreSQL 100 и 50;
|
||
- `ab` — 1 и 6 реплик по 1 CPU / 512 МиБ, как в серии `b`: одна
|
||
реплика и наибольшая конфигурация в бюджете ВМ, для замера
|
||
«до/после» и уровня шума A/A;
|
||
- `db` — насыщение PostgreSQL управляемым опытом: 1, 2 и 4 реплики по
|
||
1 CPU / 512 МиБ при узком лимите CPU PostgreSQL (выбран калибровкой,
|
||
записан в паспорт и имя конфигурации) и контроль — 4 реплики при
|
||
прежних 2 CPU PostgreSQL. Лимит CPU PostgreSQL у этой серии — часть
|
||
конфигурации;
|
||
- `db4` — две конфигурации серии `db` для замера «до/после»: 4 реплики
|
||
по 1 CPU / 512 МиБ при узком лимите CPU PostgreSQL и при 2 CPU, с теми
|
||
же полями и лимитами, что у `db`. Имя серии и состав конфигураций к
|
||
методике сравнения не относятся: метки `db4` сравнимы с метками `db`
|
||
по общим конфигурациям;
|
||
- короткие серии самопроверки — `make bench_scaling_quick` и `make
|
||
bench_scaling SERIES=db_quick` с меткой `quick-…`, в git не идут.
|
||
|
||
Лимиты LB, Valkey и генератора, профиль нагрузки, ступени и SLO SHALL
|
||
быть одинаковыми во всех сериях; лимит PostgreSQL — тоже, кроме
|
||
конфигураций серий `db` и `db4`. В каждой конфигурации серий
|
||
`a`, `b`, `pool`, `ab`, `db` и `db4` сумма лимитов CPU стенда и
|
||
генератора MUST NOT превышать число CPU ВМ Docker: иначе команда
|
||
завершается с ненулевым кодом до запуска стенда. Паспорт SHALL
|
||
содержать по каждой конфигурации сумму лимитов CPU и памяти, а также CPU
|
||
и память ВМ.
|
||
|
||
Ячейка серии — конфигурация в одном повторе. Каждая конфигурация SHALL
|
||
сниматься 3 раза. Каждая ячейка SHALL начинаться со свежего стенда:
|
||
новый volume, миграции, данные профиля. Порядок ячеек SHALL
|
||
перемешиваться кругами: в каждом круге каждая конфигурация встречается
|
||
один раз, порядок задан зерном методики и записан в метку до первой
|
||
ячейки.
|
||
|
||
Результат ячейки SHALL сохраняться сразу после неё. Прерванную серию
|
||
SHALL можно продолжить той же командой с `RESUME=1`. Продолжение
|
||
работает только на том же commit без незакоммиченных изменений:
|
||
- снимаются ячейки, которых в метке нет;
|
||
- прерванная ячейка снимается заново с новым номером попытки; строки
|
||
прежней попытки остаются в таблице, но в сводку не входят.
|
||
|
||
Стенд, оставшийся от прерванного прогона, серия SHALL удалять сама, без
|
||
ручной уборки, если другой прогон стенда не идёт.
|
||
|
||
Во время серии команда SHALL печатать строку на каждую ступень: ячейку
|
||
и её номер из общего числа, ступень, уровень, итог и оценку времени до
|
||
конца серии. Файл состояния в каталоге метки SHALL показывать текущие
|
||
ячейку и ступень.
|
||
|
||
#### Scenario: Серия с фиксированным бюджетом
|
||
|
||
- **WHEN** выполняется `make bench_scaling SERIES=a`
|
||
- **THEN** в метке 9 ячеек (3 конфигурации × 3 повтора), каждая на
|
||
свежем стенде, суммарный лимит реплик в каждой конфигурации — 4 CPU и
|
||
2 ГиБ, код выхода 0
|
||
|
||
#### Scenario: Бюджет помещается в ВМ
|
||
|
||
- **WHEN** проверяющий открывает паспорт серии `a`, `b`, `pool`, `ab`,
|
||
`db` или `db4`
|
||
- **THEN** у каждой конфигурации сумма лимитов CPU стенда и генератора
|
||
не больше числа CPU ВМ, а сумма лимитов памяти записана рядом с
|
||
памятью ВМ
|
||
|
||
#### Scenario: Насыщение PostgreSQL
|
||
|
||
- **WHEN** выполняется `make bench_scaling SERIES=db`
|
||
- **THEN** в метке все конфигурации серии × 3 повтора в перемешанном
|
||
порядке на одном коде; у каждой конфигурации в паспорте — лимит CPU
|
||
PostgreSQL, прочитанный у контейнера, а сводка показывает R*, CPU
|
||
PostgreSQL на R* относительно лимита и его троттлинг
|
||
|
||
#### Scenario: Подмножество серии для «до/после»
|
||
|
||
- **WHEN** выполняется `make bench_scaling SERIES=db4`
|
||
- **THEN** в метке 6 ячеек (2 конфигурации серии `db` × 3 повтора) в
|
||
перемешанном порядке на одном коде, с теми же полями паспорта и
|
||
сводки, что у серии `db`
|
||
- **AND** `make bench_compare` сравнивает её с меткой серии `db` или
|
||
`db4` по общим конфигурациям без отказа «разная методика»
|
||
|
||
#### Scenario: Перемешанный порядок
|
||
|
||
- **WHEN** серия запущена дважды с тем же профилем
|
||
- **THEN** порядок ячеек одинаков, в каждом круге каждая конфигурация
|
||
встречается ровно один раз, а порядок записан в метке
|
||
|
||
#### Scenario: Продолжение прерванной серии
|
||
|
||
- **WHEN** серия прервана на ячейке k, а затем запущена с `RESUME=1` на
|
||
том же commit
|
||
- **THEN** снимаются только ячейки, которых в метке нет, начиная с
|
||
прерванной, остатки стенда удалены без ручных команд, в конце метка
|
||
завершена
|
||
|
||
#### Scenario: Продолжение на другом коде
|
||
|
||
- **WHEN** `RESUME=1` запускается на другом commit или с
|
||
незакоммиченными изменениями
|
||
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
|
||
называет причину
|
||
|
||
### Requirement: Смешанный профиль открытой модели
|
||
|
||
Нагрузка серий трека 1 SHALL быть открытой моделью: генератор
|
||
отправляет запросы с заданной интенсивностью, не дожидаясь ответов на
|
||
прежние. Профиль один для всех конфигураций:
|
||
- 70 % — страница истории (`limit=50`) читаемого чата из 10 000
|
||
сообщений с курсором из пула, равномерно покрывающего историю;
|
||
- 20 % — отправка сообщения в один из 10 чатов записи с новым
|
||
`Idempotency-Key`, отправитель — участник чата;
|
||
- 10 % — `GET /users/me`.
|
||
|
||
Доли SHALL выдерживаться в каждой ступени с точностью до округления.
|
||
Пользователи стенда (читатель и 10 участников) SHALL регистрироваться и
|
||
входить по Basic до первой ступени; вход MUST NOT входить в замер.
|
||
Каждый ответ SHALL проверяться: у чтения — 200 и полная страница, у
|
||
отправки — 201, у `GET /users/me` — 200. Иначе это ошибка ступени. После
|
||
ячейки в читаемом чате SHALL быть ровно 10 000 сообщений, а число
|
||
сообщений в чатах записи — не меньше подтверждённых и не больше
|
||
отправленных отправок ячейки. Иначе команда завершается с ненулевым
|
||
кодом и называет ячейку.
|
||
|
||
#### Scenario: Доли запросов
|
||
|
||
- **WHEN** завершилась любая ступень
|
||
- **THEN** число отправленных чтений, записей и `GET /users/me` в окне
|
||
замера относится как 70 : 20 : 10 с точностью до округления
|
||
|
||
#### Scenario: Вход до замера
|
||
|
||
- **WHEN** идут ступени ячейки
|
||
- **THEN** генератор не отправляет `POST /auth/sessions` и не
|
||
регистрирует пользователей
|
||
|
||
#### Scenario: Записи без потерь и дублей
|
||
|
||
- **WHEN** ячейка завершена
|
||
- **THEN** каждая отправка шла с новым ключом, а число сообщений в
|
||
чатах записи лежит между числом ответов 201 и числом отправок
|
||
|
||
### Requirement: Максимальная устойчивая интенсивность
|
||
|
||
Ячейка SHALL состоять из ступеней. Ступень — подъём интенсивности от
|
||
прежнего уровня до нового (прогрев, в замер не входит) и окно замера с
|
||
постоянной интенсивностью. Прогрев — 5 с; у первой ступени ячейки и у
|
||
ступени после паузы за нарушенной — подъём с нуля за 15 с. Окно замера —
|
||
20 с. Сначала SHALL идти фиксированные уровни 250 и 500 запросов в
|
||
секунду, одинаковые во всех сериях, затем поиск.
|
||
|
||
Ступень проходит SLO, если в окне замера одновременно:
|
||
- p95 успешных запросов не больше 200 мс;
|
||
- доля ошибок не больше 1 %. В ошибки входят неожиданный статус,
|
||
ошибка соединения, таймаут, неполная страница чтения, а также
|
||
запросы, которые генератор должен был отправить в окне, но не
|
||
отправил.
|
||
|
||
Поиск начинается с начального уровня методики:
|
||
1. подъём в 1,25 раза до первой ступени, нарушившей SLO, а если
|
||
нарушена первая — спуск в 1,25 раза до первой прошедшей;
|
||
2. два деления промежутка между последней прошедшей и первой
|
||
нарушившей ступенью по среднему геометрическому.
|
||
|
||
Максимальная устойчивая интенсивность ячейки (R*) — наибольший уровень
|
||
поиска, прошедший SLO. Разрешение поиска — не грубее 6 %.
|
||
|
||
После ступени, нарушившей SLO, SHALL идти пауза без нагрузки, а
|
||
следующая ступень SHALL начинаться, только когда LB видит готовыми все
|
||
реплики. Ступень с долей ошибок больше 50 % или p95 больше 2 с SHALL
|
||
прерываться досрочно и считаться нарушившей SLO.
|
||
|
||
#### Scenario: Поиск сошёлся
|
||
|
||
- **WHEN** ячейка завершена без брака генератора
|
||
- **THEN** R* прошёл SLO, ближайший измеренный уровень выше него SLO
|
||
нарушил, и их отношение не больше 1,06
|
||
|
||
#### Scenario: Фиксированные уровни
|
||
|
||
- **WHEN** проверяющий сравнивает конфигурации серий
|
||
- **THEN** у каждой ячейки есть ступени 250 и 500 запросов в секунду с
|
||
p50, p95 и p99, даже если конфигурация их не выдержала
|
||
|
||
#### Scenario: Нарушение SLO
|
||
|
||
- **WHEN** в окне замера p95 больше 200 мс или ошибок больше 1 %
|
||
- **THEN** ступень помечена нарушившей, причина записана, а следующая
|
||
ступень идёт после паузы и проверки готовности реплик
|
||
|
||
#### Scenario: Пропуски генератора — ошибки
|
||
|
||
- **WHEN** генератор не отправил часть запланированных запросов окна,
|
||
потому что все его VU ждали ответов
|
||
- **THEN** эти запросы входят в долю ошибок ступени
|
||
|
||
### Requirement: Метрики ступени серии
|
||
|
||
Для каждой ступени SHALL сохраняться строка таблицы прогонов. Новые
|
||
столбцы SHALL добавляться в конец, прежние MUST NOT меняться. Столбец
|
||
конкуренции у ступени — наибольшее из посекундных значений числа
|
||
занятых VU генератора. Строка содержит:
|
||
- серию, ячейку, попытку, конфигурацию, номер и вид ступени
|
||
(фиксированная, подъём, спуск, деление), целевую интенсивность;
|
||
- отправленные, успешные и неуспешные запросы окна, неотправленные
|
||
генератором, долю ошибок SLO, итог SLO и причину нарушения;
|
||
- p50, p95, p99 и max успешных запросов и p95 по видам запросов;
|
||
- для реплик приложения, PostgreSQL, LB, Valkey и генератора — среднее
|
||
CPU за окно и долю периодов с троттлингом CFS; у реплик — ещё пик
|
||
памяти, время троттлинга, сумма CPU, наибольшее среднее по реплике и
|
||
наибольшее посекундное значение; у PostgreSQL и генератора — пик
|
||
памяти. Полный набор по каждому контейнеру (CPU, время троттлинга,
|
||
память) — в посекундной таблице;
|
||
- CPU приложения и PostgreSQL на один успешный запрос;
|
||
- загрузку CPU ВМ и долю времени, когда задачи ВМ ждали CPU;
|
||
- PostgreSQL: commit и rollback в секунду, объём и fsync WAL в секунду,
|
||
новые соединения, число соединений всего и наибольшее на реплику,
|
||
среднее число активных соединений по классам ожидания (CPU, WAL,
|
||
блокировки, прочие легковесные блокировки, ввод-вывод, прочее), долю
|
||
отсчётов, когда все соединения пула какой-либо реплики заняты, и
|
||
число отказов «слишком много клиентов» из журнала;
|
||
- LB: время ответа реплики, ожидания в очереди и полного запроса —
|
||
скользящее среднее HAProxy по последним 1 024 запросам на конце окна
|
||
(около 0,5 с при 2 000 запросов/с, а не среднее окна; для разбора
|
||
задержек не используется), наибольшее число сессий и запросов в
|
||
очереди, повторы,
|
||
перенаправления, ошибки соединения и ответа, исключения реплик
|
||
проверками, ответы 5xx;
|
||
- распределение успешных ответов по `X-Instance-Id`;
|
||
- прирост выгрузок в swap на хосте.
|
||
|
||
Значения SHALL браться из отсчётов не реже раза в секунду в окне
|
||
замера. Все отсчёты времени — часы ВМ Docker. Посекундные CPU и
|
||
троттлинг каждого контейнера и загрузка ВМ в окнах замера SHALL
|
||
сохраняться отдельной таблицей. Для каждой ячейки SHALL сохраняться
|
||
строка таблицы ячеек:
|
||
- конфигурация, повтор, попытка, место в порядке;
|
||
- R*, уровень и причина первого нарушения, число ступеней;
|
||
- p95 и p99 на фиксированных уровнях;
|
||
- сверка записей и читаемого чата;
|
||
- состояние хоста за ячейку;
|
||
- пометки.
|
||
|
||
#### Scenario: Строка ступени
|
||
|
||
- **WHEN** проверяющий открывает таблицу прогонов серии
|
||
- **THEN** у каждой строки ступени заполнены поля из списка, а прежние
|
||
столбцы таблицы на месте
|
||
|
||
#### Scenario: Посекундный CPU реплики
|
||
|
||
- **WHEN** проверяющий ищет, сколько ядер занимает одна реплика с
|
||
лимитом 4 CPU под перегрузкой
|
||
- **THEN** в посекундной таблице есть CPU этой реплики за каждую
|
||
секунду окон замера, а в строке ступени — её наибольшее посекундное
|
||
значение и троттлинг
|
||
|
||
#### Scenario: Распределение по репликам
|
||
|
||
- **WHEN** ступень шла на нескольких репликах
|
||
- **THEN** строка содержит число успешных ответов каждой реплики по
|
||
`X-Instance-Id`, и их сумма равна числу успешных ответов окна
|
||
|
||
#### Scenario: Отказ в соединении виден
|
||
|
||
- **WHEN** PostgreSQL отказывал в новых соединениях из-за предела
|
||
`max_connections`
|
||
- **THEN** строка ступени содержит число таких отказов из журнала и
|
||
ответы 5xx по данным LB
|
||
|
||
### Requirement: Генератор не ограничивает серию
|
||
|
||
Для каждой ступени серии SHALL сохраняться:
|
||
- CPU генератора, доля периодов его троттлинга и пик памяти;
|
||
- число выделенных VU и наибольшее число занятых;
|
||
- число пропущенных итераций.
|
||
|
||
Ступень SHALL считаться браком генератора, если выполнено одно из
|
||
условий:
|
||
- CPU генератора не меньше 90 % его лимита;
|
||
- троттлинг генератора — не меньше 10 % периодов;
|
||
- итерации не отправлены при CPU генератора не меньше 70 % его лимита
|
||
(свободные VU по выборке k6 раз в секунду не видны).
|
||
|
||
Брак не засчитывается ни как прошедшая, ни как нарушившая SLO ступень.
|
||
Поиск ячейки останавливается, а её R* записывается нижней границей с
|
||
пометкой. Сводка серии SHALL называть такие ячейки.
|
||
|
||
#### Scenario: Генератор упёрся в CPU
|
||
|
||
- **WHEN** CPU генератора в окне замера не меньше 90 % его лимита
|
||
- **THEN** ступень помечена браком генератора, поиск ячейки
|
||
остановлен, R* ячейки — нижняя граница, и сводка это называет
|
||
|
||
#### Scenario: Генератор в каждой строке
|
||
|
||
- **WHEN** проверяющий открывает таблицу прогонов серии
|
||
- **THEN** у каждой ступени есть CPU, троттлинг и память генератора,
|
||
число VU и пропущенные итерации
|
||
|
||
### Requirement: Графики серий
|
||
|
||
Команда `make bench_plots LABELS="<метки>"` SHALL строить по таблицам
|
||
меток графики SVG без новых зависимостей:
|
||
- R* от числа реплик: медиана и разброс повторов серий `a` и `b` и
|
||
линия линейного роста от одной реплики с 1 CPU;
|
||
- p95 от интенсивности по конфигурациям, с линией SLO;
|
||
- CPU по компонентам на уровне R* по конфигурациям: реплики,
|
||
PostgreSQL, LB, Valkey, генератор и остальная загрузка ВМ.
|
||
|
||
Вместе с графиками SHALL сохраняться сводная таблица:
|
||
- R* серий;
|
||
- эффективность роста по числу реплик;
|
||
- точка насыщения по правилу методики.
|
||
|
||
Графики и таблица выводятся из неизменяемых меток и пересоздаются той
|
||
же командой. Серия при завершении SHALL строить свои графики p95 и CPU
|
||
в каталоге метки.
|
||
|
||
#### Scenario: Графики из меток
|
||
|
||
- **WHEN** графики удалены, и команда запускается снова на тех же
|
||
метках
|
||
- **THEN** графики и сводная таблица созданы заново с теми же
|
||
значениями
|
||
|
||
#### Scenario: Точка насыщения названа
|
||
|
||
- **WHEN** проверяющий открывает сводную таблицу серий
|
||
- **THEN** в ней R* по числу реплик, отношение к линейному росту и
|
||
число реплик, после которого прирост меньше порога методики
|
||
|
||
### Requirement: Цена масштабирования в отчёте
|
||
|
||
Гипотезы о фиксированном бюджете, росте ресурсов и границе пула вместе
|
||
с тем, что их подтвердит и что опровергнет, SHALL быть закоммичены до
|
||
первого прогона серий. Метки серий `a`, `b`, `pool` и метка A/A серии
|
||
`ab` на том же коде SHALL сохраняться в `evidence/bench/`. `REPORT.md`
|
||
SHALL описывать трек 1:
|
||
- гипотезы;
|
||
- стенд, бюджет конфигураций, ядра хоста и ВМ;
|
||
- профиль нагрузки, ступени, SLO и правило поиска R*;
|
||
- результаты серий по конфигурациям (медиана и разброс) и графики;
|
||
- точку насыщения и её причину по метрикам ступеней: почему рост
|
||
реплик перестаёт помогать;
|
||
- итог каждой гипотезы, как получился;
|
||
- уровень шума A/A;
|
||
- ограничения: один хост, ВМ, разнородные ядра, серия `b` до 6 реплик,
|
||
генератор на том же хосте.
|
||
|
||
Числа SHALL переноситься из файлов меток и таблиц команд, со ссылками на
|
||
них.
|
||
|
||
#### Scenario: Проверяющий ищет точку насыщения
|
||
|
||
- **WHEN** проверяющий открывает трек 1 в `REPORT.md`
|
||
- **THEN** он находит R* по числу реплик, точку, после которой рост
|
||
останавливается, метрику, которая называет узкое место, и ссылки на
|
||
метки и графики
|
||
|
||
#### Scenario: Гипотезы до прогонов
|
||
|
||
- **WHEN** проверяющий смотрит историю git
|
||
- **THEN** commit с гипотезами старше commit первой метки серий
|
||
|
||
#### Scenario: Гипотеза не подтвердилась
|
||
|
||
- **WHEN** результат расходится с гипотезой
|
||
- **THEN** отчёт называет гипотезу опровергнутой и приводит числа
|
||
|
||
### Requirement: События Docker профилей отказа и замены
|
||
|
||
Профили отказа реплик и поочерёдной замены SHALL получать события Docker
|
||
своих контейнеров потоком, который запущен до нагрузки фазы или замены и
|
||
работает до её конца. Это действия над репликой и её возврат, а также
|
||
создание, остановка и удаление реплик и контейнера миграции.
|
||
|
||
Профили MUST NOT зависеть от истории событий, которую демон Docker
|
||
хранит ограниченно. Обращения к Docker во время прогона — `docker exec`
|
||
скрипта замены, оркестратора и проверок здоровья — MUST NOT приводить к
|
||
потере этих событий. Если событие действия или возврата не получено,
|
||
команда SHALL завершаться с ненулевым кодом и называть фазу и реплику.
|
||
|
||
#### Scenario: Много событий Docker за фазу
|
||
|
||
- **WHEN** во время фазы профиля отказа Docker порождает больше событий,
|
||
чем хранит демон, например сотни `docker exec` в контейнер стенда
|
||
- **THEN** фаза находит моменты действия и возврата и завершается, а
|
||
величины фазы считаются от этих моментов
|
||
|
||
#### Scenario: Событие не получено
|
||
|
||
- **WHEN** поток не получил события действия или возврата фазы
|
||
- **THEN** команда завершается с ненулевым кодом, называет фазу и
|
||
реплику и удаляет стенд
|
||
|
||
### Requirement: Прежний commit профиля замены
|
||
|
||
Commit, с образа которого стартуют реплики профилей `rollout` и
|
||
`rollout_quick`, SHALL задаваться методикой профиля. Это commit
|
||
текущей лабы до изменения, которое показывает замена. Сейчас таким
|
||
изменением SHALL быть миграция вложений: commit — последний перед
|
||
change `attachments`. Commit SHALL меняться при переходе в следующую
|
||
лабу (commit прошлой лабы в её истории нет) и когда замена показывает
|
||
новое изменение схемы. Правило и текущее значение SHALL быть в
|
||
`.claude/rules/bench.md`, commit — в паспорте метки.
|
||
|
||
Если commit методики нет в истории репозитория, команда SHALL
|
||
завершаться с ненулевым кодом до запуска стенда, назвать commit и
|
||
подмену `--from <commit>` для отладки.
|
||
|
||
#### Scenario: Замена на схему с вложениями
|
||
|
||
- **WHEN** выполнен `make bench_rollout_quick` на коде с вложениями
|
||
- **THEN** реплики стартуют на образе commit до change `attachments`,
|
||
ревизия схемы до замены — без таблиц вложений, после — с ними, а
|
||
команда завершается с кодом 0
|
||
|
||
#### Scenario: Commit вне истории
|
||
|
||
- **WHEN** commit методики не найден в репозитории
|
||
- **THEN** команда завершается с ненулевым кодом до запуска стенда, а
|
||
сообщение называет commit и `--from`
|