Files
mtusi2026lab2/openspec/specs/load-benchmark/spec.md
T
2026-10-02 05:05:24 +03:00

46 KiB
Raw Blame History

load-benchmark Specification

Purpose

Воспроизводимый нагрузочный эксперимент: одной командой поднимает стенд из приложения, PostgreSQL и Valkey с фиксированными лимитами, прогоняет матрицу размеров истории и уровней конкуренции для чтения и записи на чатах разного размера и сохраняет сырые данные, сводку, планы запроса истории с вариантами индекса и запроса, стоимость записи по вариантам и паспорт стенда, чтобы сравнивать версии кода и решения о схеме при одинаковых условиях. К стенду прилагаются сравнение двух меток и прогоны «до» и «после» одного изменения подряд.

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.

Последовательность случайных выборов 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 они входят в долю ошибок прогона и не входят в перцентили задержки успешных запросов

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: Сравнение двух меток

Команда 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 отчёт называет предсказание опровергнутым и приводит фактические числа