Files
mtusi2026lab2/openspec/specs/load-benchmark/spec.md
T
ricoromaandClaude Opus 5.5 7b775a29a9 chore: carry over lab 1 solution into lab 2 skeleton
Copy the committed lab 1 sources as-is: src/, student-tests/, bench/,
Dockerfile, docker-compose.yml, pyproject.toml, uv.lock,
.python-version, config_example.toml, AGENTS.md, CLAUDE.md, .claude/,
openspec/, .graphifyignore and KNOWN_ISSUES.md. Lab 1 evidence stays
in the lab 1 repository.

Merge the new skeleton files with own sections: Makefile (lab 2
targets plus own run, docker, bench and common targets), .gitignore,
.dockerignore and .env.example. Rename the image to
mtusi-messenger:lab2 and point AGENTS.md at lab 2.

The application is still the in-memory lab 1 implementation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 22:11:46 +03:00

483 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# load-benchmark Specification
## Purpose
Воспроизводимый нагрузочный эксперимент трека 1: одной командой
поднимает стенд с фиксированными лимитами, прогоняет матрицу размеров
истории и уровней конкуренции для чтения и записи и сохраняет сырые
данные, сводку и паспорт стенда, чтобы сравнивать версии кода при
одинаковых условиях. К стенду прилагаются диагностика стоимости
запроса, сравнение двух меток и прогоны «до» и «после» одного
изменения подряд.
## Requirements
### Requirement: Запуск одной командой
Полная матрица SHALL запускаться командой `make bench` с меткой
результата `BENCH_LABEL` (по умолчанию `baseline`), короткий прогон —
командой `make bench_quick`. Результаты SHALL сохраняться в
`evidence/bench/<метка>/`. Команда MUST NOT перезаписывать результаты
существующей метки и MUST NOT использовать порт 8080 хоста и
контейнеры `make run_dev` / `make run_docker`. После завершения, в том
числе с ошибкой или по Ctrl+C, контейнеры и сеть стенда 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** контейнеры и сеть стенда удалены, частичные результаты
помечены как незавершённые
### Requirement: Фиксированный стенд
Приложение SHALL запускаться в контейнере из образа, собранного из
текущего checkout тем же `Dockerfile`, с одинаковыми во всех прогонах
лимитами: 1 CPU, 2 ГБ памяти без swap. Healthcheck образа SHALL быть
отключён, порты на хост MUST NOT публиковаться. Генератор нагрузки
SHALL работать в той же docker-сети и обращаться к приложению по имени
контейнера, минуя проброс портов хоста.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит лимиты CPU и памяти контейнера
приложения, прочитанные у запущенного контейнера, и они одинаковы для
всех прогонов
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
### 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 включать размеры истории 10 000, 100 000 и
1 000 000 сообщений, уровни конкуренции 1, 10 и 50 одновременных
клиентов и оба сценария, по 3 измеряемых прогона на ячейку. Перед
каждым измеряемым прогоном SHALL идти прогрев с той же нагрузкой, не
входящий в результат. Каждый размер SHALL начинаться с нового процесса
приложения, наполненного через HTTP API до ровно N сообщений в читаемом
чате. Рост хранилища за прогоны `write` SHALL фиксироваться в
результатах.
#### Scenario: Состав матрицы
- **WHEN** полная матрица завершена
- **THEN** в результатах 54 измеряемых прогона: 3 размера × 3 уровня
конкуренции × 2 сценария × 3 повтора
#### Scenario: Свежий процесс на каждый размер
- **WHEN** начинается размер N
- **THEN** контейнер приложения запущен заново и перед первым прогоном
содержит ровно N сообщений в читаемом чате
### Requirement: Метрики прогона
Для каждого измеряемого прогона SHALL сохраняться: сценарий, размер
истории, конкуренция, номер повтора, длительность, число успешных и
неуспешных запросов, успешные RPS, доля ошибок, задержки p50, p95, p99
и max успешных запросов, потреблённое приложением CPU, RSS процесса
приложения в начале, в конце и максимальный за прогон, число сообщений
в хранилище в начале и в конце, загрузка CPU генератора. Для каждого
размера SHALL сохраняться RSS до и после наполнения и оценка байт RSS
на сообщение.
Наполнение SHALL идти порциями, и для каждой порции SHALL сохраняться:
размер, число сообщений в хранилище до и после, успешные RPS, доля
ошибок, задержки p50, p95, p99 и max, CPU приложения и RSS в конце
порции. Так наполнение до 1 000 000 даёт кривую «запись при росте
хранилища» без дополнительного времени прогона.
#### Scenario: Строка прогона
- **WHEN** проверяющий открывает таблицу прогонов
- **THEN** у каждой строки заполнены все перечисленные поля
#### Scenario: Память на сообщение
- **WHEN** наполнение размера N завершено
- **THEN** в результатах есть прирост RSS за наполнение и байты на
сообщение
#### Scenario: Кривая наполнения
- **WHEN** наполнение размера 1 000 000 завершено
- **THEN** в таблице наполнения есть строка на каждую порцию, от
пустого хранилища до 1 000 000 сообщений, с RPS, p95, p99, max и
RSS
### Requirement: Достоверность прогона
Прогон SHALL помечаться в результатах, если его данные нельзя считать
замером сервера: процесс приложения перезапускался или был убит,
генератор нагрузки был загружен настолько, что мог сам ограничивать
throughput, или доля ошибок больше нуля. Сводка SHALL показывать эти
пометки рядом со значениями.
#### Scenario: Генератор упёрся в CPU
- **WHEN** загрузка CPU генератора за прогон выше порога, заданного в
методике
- **THEN** прогон помечен, и в сводке рядом с его ячейкой видна пометка
### Requirement: Ход прогона виден
Во время прогона команда SHALL печатать строку на каждый этап (сборка
образа, запуск стенда, наполнение, сбор курсоров, каждый измеряемый
прогон) с временем от начала. Наполнение SHALL показывать прогресс не
реже раза в минуту: сколько сообщений из N, скорость, оценку
оставшегося времени. После каждого измеряемого прогона SHALL
печататься его номер из общего числа, ячейка матрицы, основные
результаты (RPS, p50, p95, p99, CPU приложения, RSS, доля ошибок),
пометки и оценка времени до конца матрицы. В каталоге метки SHALL
поддерживаться файл текущего состояния, а строка прогона SHALL
дописываться в таблицу прогонов сразу после прогона.
#### Scenario: Где мы сейчас
- **WHEN** идёт наполнение размера 1M
- **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;
- паспорт стенда: дата, commit и признак незакоммиченных изменений,
digest образа приложения, версии генератора и Python, лимиты, железо
хоста и VM, параметры профиля и команда запуска;
- состояние хоста в начале и в конце прогона: занятый swap, доля
свободной памяти, питание от сети или от батареи.
Если в начале прогона хост работает от батареи или swap занят сверх
порога методики, команда SHALL предупреждать об этом в выводе и в
паспорте, но не прерываться. Данные MUST быть синтетическими;
результаты MUST NOT содержать секретов, `.env` и абсолютных путей
домашнего каталога.
#### Scenario: Повтор на другой машине
- **WHEN** другой человек берёт паспорт и команду из каталога метки
- **THEN** он может запустить тот же профиль на своём checkout и
сравнить таблицы по тем же столбцам
#### Scenario: Условия хоста для сравнения меток
- **WHEN** проверяющий сравнивает две метки
- **THEN** по паспортам видно, одинаковы ли были swap, свободная
память и питание хоста в начале и в конце каждого прогона
#### Scenario: Неподходящий хост
- **WHEN** прогон запускается от батареи или с занятым swap выше порога
- **THEN** вывод команды и паспорт содержат предупреждение, а прогон
продолжается
### Requirement: Базовый замер в отчёте
Результат полной матрицы текущего кода SHALL быть сохранён под меткой
`baseline`. `REPORT.md` SHALL описывать в разделе экспериментов
гипотезы, стенд и лимиты, профиль нагрузки, результаты по ячейкам со
ссылкой на каталог `evidence/bench/baseline/` и ограничения замера.
#### Scenario: Проверяющий читает отчёт
- **WHEN** проверяющий открывает раздел экспериментов `REPORT.md`
- **THEN** в нём есть гипотезы, условия стенда, таблица результатов и
путь к сырым данным
### Requirement: Разложение стоимости запроса
Команда `make bench_inproc` SHALL раскладывать время обработки одного
запроса внутри приложения на части, чтобы узкое место находилось
измерением, а не догадкой. Приложение SHALL вызываться в том же
процессе, без сервера и сети, на синтетических данных с фиксированным
зерном. Вывод SHALL содержать:
- время на запрос сценариев `read` и `write` при обычном уровне логов
и при выключенных записях уровня INFO; разница — цена логов, отдельно
сборка записи и запись в stdout контейнера;
- время частей построения ответа страницы истории, в том числе вариант
без форматирования времени в Python; разница — цена форматирования;
- функции с наибольшим собственным временем и числом вызовов на запрос;
- медиану и разброс min–max каждого измерения: по запускам процесса
для времени на запрос, по повторам для частей ответа;
- дату, commit, признак незакоммиченных изменений, версии Python и
библиотек, машину хоста.
Результат SHALL сохраняться в `evidence/profile/<метка>.txt`. Команда
MUST NOT перезаписывать файл существующей метки. Числа этой команды
MUST NOT выдаваться за результат стенда: она объясняет, куда уходит
время, а пропускную способность и задержки меряет только `make bench`.
Команда SHALL также сверять текущее форматирование времени с эталонной
записью формата `ГГГГ-ММ-ДДTЧЧ:ММ:СС.ffffffZ` на наборе значений,
включающем нулевые микросекунды и время в другом часовом поясе, и
проверять, что строка разбирается обратно в то же значение. При
расхождении команда SHALL завершаться с ненулевым кодом и называть
значение.
#### Scenario: Разложение чтения
- **WHEN** выполняется `make bench_inproc BENCH_LABEL=<метка>`
- **THEN** в `evidence/profile/<метка>.txt` есть время на запрос `read`
и `write`, цена логов, цена построения ответа и цена форматирования
времени, у каждого числа — медиана и разброс
#### Scenario: До и после изменения
- **WHEN** команда выполнена на коде до изменения и на коде после него
под разными метками
- **THEN** по двум файлам видно, какая часть запроса подешевела и на
сколько, а какие части не изменились
#### Scenario: Метка уже занята
- **WHEN** файл `evidence/profile/<метка>.txt` уже существует
- **THEN** команда завершается с ненулевым кодом и называет файл
#### Scenario: Формат времени изменился
- **WHEN** форматирование времени даёт строку, отличную от эталонной,
хотя бы для одного значения набора
- **THEN** команда завершается с ненулевым кодом и печатает значение,
ожидаемую и полученную строки
### Requirement: Сравнение двух меток
Команда `make bench_compare BEFORE=<метка> AFTER=<метка>` SHALL
сравнивать результаты двух меток полной матрицы и сохранять таблицу в
`evidence/compare/<до>__<после>.md`. Для каждой ячейки матрицы таблица
SHALL содержать медиану и разброс min–max повторов RPS в обеих метках,
изменение медианы в процентах, медианы p50, p95 и p99 и CPU приложения
на один запрос. Для каждого размера истории — байты RSS на сообщение в
обеих метках.
Команда SHALL отказываться сравнивать метки, снятые разной методикой:
если различаются параметры профиля, лимиты контейнера приложения или
образ генератора, она завершается с ненулевым кодом, называет
различие и не создаёт таблицу. Параметр, записанный в паспорте только
одной из меток, SHALL перечисляться в таблице как непроверенный, без
отказа. Незавершённая метка, незакоммиченные изменения, предупреждения
о хосте и помеченные прогоны SHALL перечисляться в начале таблицы.
С необязательным параметром `AA=<метка>` команда SHALL оценивать
уровень шума: наибольшее по ячейкам сценария изменение медианы RPS
между метками `AA` и `BEFORE`, снятыми на одном и том же коде
приложения. Изменение в ячейке SHALL называться эффектом, только если
разбросы повторов двух меток не пересекаются и изменение медианы
больше уровня шума её сценария; иначе — изменением в пределах шума.
#### Scenario: Сравнимые метки
- **WHEN** сравниваются две завершённые метки одного профиля с
одинаковыми лимитами и генератором
- **THEN** в таблице 18 ячеек (2 сценария × 3 размера × 3 уровня
конкуренции) с медианами, разбросом и изменением в процентах, а в
начале — commit и условия хоста каждой метки
#### Scenario: Разная методика
- **WHEN** у меток различается параметр профиля, лимит контейнера или
образ генератора
- **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 по порядку выполнить: полную матрицу и
разложение стоимости запроса для `BEFORE`, commit их результатов,
возврат изменения новым commit, полную матрицу и разложение для
`AFTER`. Матрица SHALL идти раньше разложения, чтобы в паспорте метки
не было признака незакоммиченных изменений.
Команда 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** отчёт называет предсказание опровергнутым и приводит
фактические числа