# 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 добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса уборщика. В профилях очереди и цены телеметрии к ним SHALL добавляться S3 с его bootstrap, брокер, relay, worker и уборщик: эти профили меряют обработку. Остальные профили брокер, relay и worker не запускают: они меряют реплику, а реплика к брокеру не обращается. Число реплик SHALL задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут образ commit, заданного методикой: образ собирается тем же `Dockerfile` из файлов этого commit без изменения рабочего дерева. Профиль замены заканчивается на образе текущего checkout. LB SHALL запускаться из того же образа и с той же конфигурацией, что у рабочего стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL получает те же настройки образа плюс модуль записи планов, выключенный вне снятия плана. S3 SHALL запускаться из того же образа и с теми же аргументами сервера, что у рабочего стенда, а bucket и пользователей создаёт тот же bootstrap. В профиле сверки к аргументам S3 добавляется порт метрик шлюза: он слушает только loopback контейнера S3, и по нему оркестратор считает запросы к S3. Брокер SHALL запускаться из того же образа и с той же конфигурацией, что у рабочего стенда; в профиле очереди к ней добавляются плагин метрик и интервал статистики в секунду: порт метрик доступен только в сети стенда, на хост не публикуется. В сериях трека 1 предел соединений PostgreSQL (`max_connections`) — параметр конфигурации серии, по умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до наполнения. Телеметрию стенд SHALL запускать только в вариантах профиля цены телеметрии, где она есть, и в профилях загрузок и очереди с включённым выключателем (требование «Выключатель телеметрии стенда»). Тогда к стенду SHALL добавляться Collector, Prometheus, Loki и Tempo из тех же образов, с теми же конфигурациями и лимитами, что у рабочего стенда; вариант профиля цены телеметрии меняет только настройки SDK, слой выбора трасс Collector и набор рядов Prometheus, которые задаёт методика. Хранилища телеметрии — в отдельной сети стенда; Grafana на стенде не запускается: в пути данных её нет. Без этого сервисы телеметрии MUST NOT запускаться, а SDK реплик, worker и relay SHALL быть выключен (`observability`, «Где телеметрия включена»): методика прежних профилей не меняется. Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека 1 — во всех прогонах одной конфигурации: - у каждой реплики приложения — лимит CPU и памяти без swap, заданный методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по конфигурации); - у LB, PostgreSQL, Valkey, S3, брокера, relay, worker, уборщика, Collector и хранилищ телеметрии — свои лимиты CPU и памяти без swap, заданные методикой (у Collector и хранилищ телеметрии — рабочего стенда); в серии трека 1 они одинаковы во всех конфигурациях; у уборщика в управляемом опыте профиля сверки — другой лимит CPU, тоже заданный методикой; - у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без swap, заданный методикой; в остальных профилях генератор без лимита. Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»). Значение SHALL записываться в паспорт. Образ контейнера в паспорте SHALL называться тем значением, по которому образы контейнеров можно сравнивать: меткой манифеста compose, а у контейнера без неё — идентификатором образа. Healthcheck образа приложения SHALL быть отключён: готовность реплик проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки приложения и хранилищ SHALL браться из методики стенда, а не из `.env` и `config.toml` рабочего стенда. Пароли хранилищ, пароль брокера и секреты S3 SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же docker-сети и обращаться к приложению через LB по имени сервиса, минуя проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми все реплики, а при запущенной телеметрии — ещё и когда Collector и хранилища телеметрии отвечают готовностью. #### 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 и образы до и после записаны в паспорт #### Scenario: S3 в профиле загрузок - **WHEN** запускается профиль загрузок - **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и ограничение буфера приёма реплики записаны в паспорт #### Scenario: Брокер в профиле загрузок - **WHEN** запускается профиль загрузок - **THEN** брокер, relay и worker стенда не запущены, а загрузки отвечают 202: задания ждут в PostgreSQL #### Scenario: S3 и уборщик в профиле сверки - **WHEN** запускается профиль сверки - **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами и портом метрик только на loopback своего контейнера, bootstrap завершился успешно, а аргументы S3, образы и лимиты S3 и уборщика записаны в паспорт #### Scenario: Конвейер в профиле очереди - **WHEN** запускается профиль очереди - **THEN** S3, брокер, relay, worker и уборщик запущены из образов рабочего стенда с его лимитами без swap, у worker — политика перезапуска рабочего стенда, порт метрик брокера не опубликован на хосте, а образы, лимиты, значения конкуренции и prefetch и окружение worker и relay записаны в паспорт #### Scenario: Телеметрия выключена по умолчанию - **WHEN** запускается любой профиль, кроме профиля цены телеметрии, без выключателя телеметрии - **THEN** Collector, Prometheus, Loki, Tempo и Grafana стенда не запущены, записи о старте реплик, worker и relay говорят, что телеметрия выключена, а окружение приложения в паспорте то же, что до появления выключателя #### Scenario: Сервисы телеметрии на стенде - **WHEN** запускается вариант профиля цены телеметрии с телеметрией - **THEN** Collector, Prometheus, Loki и Tempo запущены из образов рабочего стенда с его конфигурациями, кроме слоёв варианта, и его лимитами без swap, порты на хост не опубликованы, Grafana не запущена, а образы, лимиты и контрольные суммы конфигураций записаны в паспорт ### 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=` 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 `pipeline-reliability`. Commit SHALL меняться при переходе в следующую лабу (commit прошлой лабы в её истории нет) и когда замена показывает новое изменение схемы. Правило и текущее значение SHALL быть в `.claude/rules/bench.md`, commit — в паспорте метки. Если commit методики нет в истории репозитория, команда SHALL завершаться с ненулевым кодом до запуска стенда, назвать commit и подмену `--from ` для отладки. #### Scenario: Замена на схему с вложениями - **WHEN** выполнен `make bench_rollout_quick` на коде этого изменения - **THEN** реплики стартуют на образе commit до change `pipeline-reliability`, ревизия схемы до замены — без новых колонок и таблицы, после — с ними, а команда завершается с кодом 0 #### Scenario: Commit вне истории - **WHEN** commit методики не найден в репозитории - **THEN** команда завершается с ненулевым кодом до запуска стенда, а сообщение называет commit и `--from` ### Requirement: Профиль загрузок Команда `make bench_uploads` (метка `UPLOADS_LABEL`, по умолчанию `baseline`) SHALL на свежем стенде мерить память реплики при одновременных загрузках вложений. Команда `make bench_uploads_quick` — то же короче, метка `quick-uploads-…`, в git не идёт. Результаты SHALL сохраняться в `evidence/uploads/<метка>/`. Занятая метка SHALL давать отказ до запуска стенда. Стенд — LB и одна реплика с лимитами рабочего стенда (1 CPU, 512 МБ без swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. Брокер, relay и worker не запускаются: задания ждут в PostgreSQL. Поэтому у всех вариантов предел незавершённых заданий выключен (`queue-overload`): иначе он отклонял бы загрузки, и профиль мерил бы не память приёма, а этот предел. Варианты кода: - «до» — образ commit из методики; у лабы 5 это commit переноса лабы 4, в нём места загрузки уже есть; - «без лимита» — образ текущего checkout, мест загрузки больше, чем клиентов, очереди нет; - «с лимитом» — образ текущего checkout с параметрами загрузок по умолчанию. Успешная загрузка — 202, а у варианта с образом commit до перехода на 202 — 201. Код успеха варианта SHALL быть в паспорте. Столбец успешных загрузок считает код успеха варианта. Тела — настоящие PNG около 1 MiB и около 10 MiB, не больше лимита контракта. Их строит оркестратор, детерминированно от зерна методики. Прогон — вариант × размер × число одновременных клиентов (1, 10, 20 и 40) × повтор. Повторов в полном профиле три. Каждый прогон SHALL идти на новом контейнере реплики и новом volume S3. Клиенты загружают без пауз окно, заданное методикой. На 429 клиент ждёт `Retry-After`, на прочие ошибки — секунду. Для каждого прогона SHALL сохраняться: - пик памяти реплики за окно — пик cgroup, сброшенный в начале окна, — и память перед окном; - наибольшие анонимная память и память буферов сокетов реплики; - было ли завершение реплики из-за памяти; - ответы по кодам, ошибка соединения — отдельным кодом; - успешных загрузок в секунду, p50, p95 и p99 успешных; - пик памяти S3 (в том числе анонимной) и LB. Прогон с завершением реплики из-за памяти SHALL помечаться `oom` и записываться как результат варианта, а не как сбой команды. Следующий прогон идёт на новой реплике. Граница чёрного ящика: генератор обращается к приложению только по HTTP через LB, оркестратор управляет стендом через docker CLI. Сверх этого он читает счётчики памяти cgroup контейнеров и пересоздаёт volume S3 с bootstrap между прогонами. К bucket и объектам он не обращается. В паспорте метки SHALL быть: - лимиты и образы, в том числе commit варианта «до»; - окружение приложения каждого варианта без секретов; - размеры и SHA-256 тел; - версия ядра ВМ; - ограничение буфера приёма сокетов реплики; - состояние хоста. #### Scenario: Полный профиль - **WHEN** выполнен `make bench_uploads` - **THEN** в `evidence/uploads/<метка>/` есть паспорт, таблица прогонов (три варианта × два размера × четыре уровня × три повтора), сводка по ячейкам с медианой и разбросом повторов и сырые итоги генератора, код выхода 0 #### Scenario: Быстрый профиль - **WHEN** выполнен `make bench_uploads_quick` - **THEN** за несколько минут проходят варианты «без лимита» и «с лимитом» на 10 MiB при 1, 10 и 40 клиентах, по одному повтору, код выхода 0, каталог метки в git не попадает, а успешные загрузки — 202 #### Scenario: Реплика убита из-за памяти - **WHEN** в прогоне реплику завершило ядро из-за памяти - **THEN** прогон помечен `oom`, в таблице есть ответы по кодам до и после завершения, следующий прогон идёт на новой реплике, а команда не прерывается #### Scenario: Пик окна без памяти старта - **WHEN** реплика при старте заняла больше памяти, чем в окне прогона - **THEN** пик прогона отражает только окно, а не старт процесса #### Scenario: Предел заданий не участвует - **WHEN** выполнен профиль загрузок, задания не обрабатываются, и их больше значения предела по умолчанию - **THEN** ни один ответ 429 не вызван пределом незавершённых заданий: все 429 — от мест загрузки, а в паспорте вариантов предел равен 0 ### Requirement: Загрузки в отчёте `REPORT.md` SHALL содержать по профилю загрузок: - гипотезы о пике памяти с лимитом и без него, о пропускной способности и о сроке записи в S3. Они записаны и зафиксированы commit до первого прогона метки; - методику: стенд, лимиты, варианты, тела, уровни, окно, повторы; - таблицу результатов по меткам: пик памяти, завершения из-за памяти, ответы по кодам, загрузок в секунду и p95 — по вариантам, размерам и уровням; - выводы по каждой гипотезе и ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, одна нода S3. Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться вручную. #### Scenario: Гипотезы до прогонов - **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки - **THEN** commit с гипотезами раньше commit с результатами метки #### Scenario: Выводы по метке - **WHEN** проверяющий открывает раздел загрузок в `REPORT.md` - **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки метки, а числа совпадают со сводкой ### Requirement: Профиль сверки Команда `make bench_reconcile` (метка `RECONCILE_LABEL`, по умолчанию `baseline`) SHALL на свежем стенде мерить стоимость прохода сверки bucket и БД (capability `storage-consistency`). Команда `make bench_reconcile_quick` — то же на малом наборе и одним повтором, метка `quick-reconcile-…`, в git не идёт. Результаты SHALL сохраняться в `evidence/reconcile/<метка>/`. Занятая метка SHALL давать отказ до запуска стенда. Стенд — LB, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего стенда (требование «Фиксированный стенд»). Проход сверки — разовый процесс уборщика из образа приложения с лимитами рабочего стенда (0,25 CPU, 256 МБ без swap), в управляемом опыте — с 1 CPU. Grace проходов — короткий, заданный методикой, но больше границы живой загрузки (capability `service-configuration`, «Параметры уборщика»). Данные — синтетические вложения одного чата: - 10 000, 30 000 и 100 000 объектов по 4 KiB — один набор, который растёт между этапами; - 1 000 объектов по 1 MiB — на отдельном стенде, для цены чтения байтов. Расхождения SHALL вноситься при наполнении, по 0,25 % от числа объектов каждого класса: объект без метаданных, метаданные без объекта, другой размер, зависшая загрузка. Класс объекта SHALL определяться его номером, а содержимое — номером и зерном методики. Граница чёрного ящика: - пользователи и чат создаются через API; - метаданные вложений оркестратор пишет в PostgreSQL стенда, объекты — прямой записью в S3 стенда ключами пользователя API; - проход сверки — процесс уборщика из образа приложения, его результат — журнал этого процесса; - фоновая нагрузка — генератор по HTTP через LB; - сверх этого оркестратор читает счётчики cgroup контейнеров, метрики шлюза S3 на loopback его контейнера и счётчики PostgreSQL. Приложение оркестратор не импортирует. Проходы: - без фоновой нагрузки и без предела скорости: - стратегия по умолчанию на всех размерах набора; - стратегия HEAD на 10 000 и 30 000 объектов; - глубокая сверка на 10 000 объектов по 4 KiB и на объектах по 1 MiB; - глубокая сверка с уборщиком 1 CPU на объектах по 1 MiB; - с фоновой нагрузкой, на 100 000 объектов, стратегия по умолчанию: - лимит CPU рабочего стенда с пределом скорости по умолчанию и без предела; - 1 CPU без предела и с пределом по умолчанию. Фоновая нагрузка идёт с постоянной интенсивностью, заданной методикой: скачивания вложений набора, запись сообщений и чтение истории. До и после каждого прохода — окна без прохода; - отказ по пределу: `--apply` с пределом изменений 100, когда кандидатов 1 000 и 10 000, — на образе commit из методики и на образе текущего checkout. Каждый проход повторяется три раза, повторы одной ячейки не идут подряд. Исключение — группа проходов из одной ячейки (этап 100k без нагрузки — только стратегия по умолчанию): её повторы идут подряд, потому что остальные проходы того же набора идут под фоновой нагрузкой отдельным блоком, и вставить их между повторами значило бы смешать проходы без нагрузки с проходами под ней. Варианты сравниваются внутри одной метки, на одних данных и в одной сессии хоста. Шум — разброс повторов ячейки, а у проходов с фоновой нагрузкой ещё отношение p95 окон до и после прохода (A/A). Для каждого прохода SHALL сохраняться: - итог прохода из журнала уборщика — длительность и длительность шагов, просмотренные объекты и строки, найденные расхождения по классам, затронутые объекты S3, запросы к S3 по операциям, прочитанные байты, сеансы с PostgreSQL, неперепроверенные кандидаты, код выхода; - запросы к S3 по метрикам шлюза и счётчики PostgreSQL за проход; - CPU уборщика, S3 и PostgreSQL за проход; - память уборщика в начале прохода и её пик; - у проходов с фоновой нагрузкой — по каждому сценарию в окне прохода и в окнах до и после: число ответов, ошибки, p50, p95 и p99. Достоверность: - найденные расхождения SHALL по каждому классу совпадать с внесёнными. Иначе команда завершается ненулевым кодом: замер на неверных данных — не результат; - в проходах без фоновой нагрузки запросы к S3 по счётчикам сверки SHALL совпадать с метриками шлюза, иначе проход помечается; - ответ 5xx фоновой нагрузки в окнах прохода — пометка прохода; любой неуспешный запрос фона или недосланная итерация по всему итогу генератора — пометка всех проходов блока. В паспорте метки SHALL быть: - лимиты и образы, в том числе commit варианта «до»; - аргументы S3; - размеры набора, размеры объектов, доли расхождений и зерно; - grace проходов и предел скорости по умолчанию; - фоновая нагрузка; - версия ядра ВМ; - состояние хоста и посторонние контейнеры. Сводка SHALL давать по каждой ячейке медиану и разброс повторов, вывод по каждой гипотезе (требование «Стоимость сверки в отчёте») и графики: длительность и запросы прохода от размера набора по стратегиям, p95 фоновой нагрузки по вариантам. #### Scenario: Полный профиль сверки - **WHEN** выполнен `make bench_reconcile` - **THEN** в `evidence/reconcile/<метка>/` есть паспорт, таблица проходов со всеми ячейками по три повтора, таблица окон фоновой нагрузки, сводка с выводами по гипотезам и графики, код выхода 0 #### Scenario: Быстрый профиль сверки - **WHEN** выполнен `make bench_reconcile_quick` - **THEN** за несколько минут проходят все виды проходов на малом наборе по одному повтору, код выхода 0, каталог метки в git не попадает #### Scenario: Найдено не то, что внесено - **WHEN** проход нашёл в каком-то классе не столько расхождений, сколько внесено - **THEN** команда завершается ненулевым кодом, называет класс, ячейку и оба числа и удаляет стенд #### Scenario: Счётчики сверки и метрики S3 - **WHEN** завершён проход без фоновой нагрузки - **THEN** в строке прохода запросы к S3 по счётчикам сверки равны запросам по метрикам шлюза, а при различии строка помечена ### Requirement: Стоимость сверки в отчёте `REPORT.md` SHALL содержать по профилю сверки: - гипотезы и ожидание, записанные и зафиксированные commit до первого прохода метки: - о линейности прохода; - о цене стратегии HEAD; - о цене глубокой сверки; - о влиянии на фоновую нагрузку с порогом p95; - ожидаемую цену отказа по пределу; - методику: стенд, лимиты, данные и граница наполнения, ячейки, фоновую нагрузку, повторы и A/A; - таблицы результатов метки по ячейкам: - длительность и цена на объект; - запросы к S3 и PostgreSQL, байты, CPU и память; - p95 фоновой нагрузки по вариантам; - цена отказа по пределу до и после change; - выводы по каждой гипотезе, обоснование предела скорости по умолчанию и рекомендации для стратегии HEAD и глубокой сверки; - ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, одна нода S3, синтетические объекты двух размеров. Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться вручную. #### Scenario: Гипотезы сверки до прогонов - **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки - **THEN** commit с гипотезами раньше commit с результатами метки #### Scenario: Выводы по метке сверки - **WHEN** проверяющий открывает раздел стоимости сверки в `REPORT.md` - **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки метки, а числа совпадают со сводкой ### Requirement: Профиль очереди Команда `make bench_queue` (метка `QUEUE_LABEL`, по умолчанию `baseline`) SHALL мерить конвейер обработки вложений под перегрузкой. Команда `make bench_queue_quick` — то же на части ячеек и с короткими окнами, метка `quick-queue-…`, в git не идёт. Результаты SHALL сохраняться в `evidence/queue/<метка>/`. Занятая метка SHALL давать отказ до запуска стенда, кроме продолжения прерванной метки на том же commit (`RESUME=1`), как у серий трека 1. Стенд — требование «Фиксированный стенд»: LB, две реплики, PostgreSQL, Valkey, S3, брокер, relay, worker и уборщик с лимитами рабочего стенда (worker — 1 CPU и 1 ГБ без swap). Worker перезапускается по той же политике, что на рабочем стенде: настройка, которая не помещается в лимит памяти, может стоить завершения его процесса 1 ядром, и ячейка показывает это, а не простаивает. Каждая ячейка — свежий стенд на новых volume. **Настройки** (конкуренция, prefetch): 1 и 1; 2 и 2 — значения по умолчанию; 4 и 4; 2 и 256 — большой prefetch. **Классы изображений** — настоящие файлы, детерминированно от зерна методики, ни один не тривиален для декодера, размер и SHA-256 — в паспорте: - `s` — JPEG около 1,9 млн пикселей и 0,5 MiB; - `m` — PNG из шума около 3,5 млн пикселей на границе байтов контракта; - `lj` — JPEG на границе пикселей контракта, около 9 MiB; - `lp` — PNG с альфа-каналом на границе пикселей и байтов контракта. **Ячейки матрицы** — настройка × класс × повтор, повторов три, круги с перестановкой от зерна, повтор одной ячейки не идёт подряд. План — в паспорте до первой ячейки. Большой prefetch — на `s` и `lp`, конкуренция 1 — на `m` и `lp`, остальные — на всех классах. **Нагрузка ячейки** — открытая модель загрузок через LB, интенсивность задана методикой на класс и одинакова для всех настроек: окно ниже потолка worker; окно перегрузки выше потолка; спад до нуля, пока незавершённых заданий нет; снова окно ниже потолка. Ответ не повторяется: 429 считается отказом. Рядом всё время идёт контрольный поток: отправка текста, чтение истории и скачивание готовых вложений с постоянной интенсивностью. **Блоки сверх матрицы**, по три повтора, класс `s`, настройка по умолчанию, если не сказано иное: - предел: предел незавершённых заданий по умолчанию и выключенный, перегрузка, которая его превышает; - приём: класс `m`, интенсивность выше того, что принимают реплики и S3, окно перегрузки такой длины, что после мест загрузки срабатывает и предел незавершённых заданий; - второй worker: в конце окна перегрузки запускается ещё один worker с теми же настройками, настройки 2 и 2 и 2 и 256; - рестарты: посреди перегрузки worker завершён сигналом KILL и снова запущен; брокер перезапущен с сохранённым volume. Для каждой ячейки SHALL сохраняться: - throughput — готовых вложений в секунду в окне перегрузки и в окне восстановления; - очередь посекундно и её пики, в трёх местах: неопубликованные задания (outbox) и ждущие срока; очередь брокера — готовые и неподтверждённые сообщения, опубликованные и не взятые задания; взятые worker — `processing` и выданные, но не взятые; - возраст старейшего незавершённого задания, пик по окнам и посекундно; время задания в очереди по журналу worker: p50 и p95 по окнам прихода; - время от ответа 202 до `ready` по метаданным: p50, p95 и p99 по окнам прихода; - время восстановления: от ответа на последнюю загрузку окна перегрузки до нуля незавершённых заданий; - RSS: пик процесса worker, пик процесса обработки по его отчёту (p50 и наибольший), `memory.peak` и наибольшая анонимная память контейнера, завершения ядром из-за памяти, перезапуски контейнера worker; причина каждого завершения по событиям Docker — ядро, команда или прочее с кодом выхода; перезапуски и завершения relay; у перезапущенного контейнера — наибольшее и сумма по его жизням; - CPU и троттлинг worker, S3, PostgreSQL, реплик, relay, брокера, уборщика и LB по каждому окну; - память брокера и наличие сработавшего предела памяти; - ответы на загрузку по кодам, недосланные итерации, `failed` по кодам и причинам, попытки сверх одной, пропущенные сообщения по причинам; - контрольный поток: число ответов, ошибки, p50, p95 и p99 по окнам. Граница чёрного ящика: генератор обращается к приложению только по HTTP через LB, истина о готовности — метаданные `GET /attachments/{id}`, запрошенные у каждого принятого вложения после разбора очереди. Сверх этого оркестратор читает: счётчики cgroup; журналы worker, relay, реплик и уборщика; состояние заданий в PostgreSQL стенда — только для измерения; метрики очереди брокера. Приложение он не импортирует. Достоверность: - принятые вложения SHALL совпасть с вложениями стенда в обе стороны: потерянное, зависшее или вложение стенда, на которое никто не получил 202 и которое не объясняется ответом 5xx или обрывом, — пометка ячейки, у ячейки блока рестартов и матрицы — и ненулевой код команды в конце метки; - второго набора вариантов и второго задания у вложения SHALL не быть, иначе так же; - выборка оригиналов и вариантов SHALL скачиваться с SHA-256 из метаданных; - k6 с недосланными итерациями, выгрузка хоста в swap и упавшее хранилище — пометки ячейки; - конкуренция и prefetch в записи о старте worker SHALL совпасть с ячейкой, иначе отказ. В паспорте метки SHALL быть: лимиты и образы; значения конкуренции, prefetch и окружение worker и relay по ячейкам без секретов; классы и их параметры; интенсивности и окна; контрольный поток; план; версия ядра ВМ; состояние хоста; посторонние контейнеры. Сводка SHALL давать по каждой ячейке медиану и разброс повторов, таблицы блоков, вывод по каждой гипотезе (требование «Очередь под перегрузкой в отчёте»), рекомендуемую настройку по её правилу и графики. Настройку, снятую не на всех классах, сводка SHALL называть такой, и кандидатом в рекомендацию она MUST NOT быть. #### Scenario: Полный профиль очереди - **WHEN** выполнен `make bench_queue` - **THEN** в `evidence/queue/<метка>/` есть паспорт, таблица ячеек, посекундная шкала, сводка с выводами по гипотезам и графики, код выхода 0 #### Scenario: Быстрый профиль очереди - **WHEN** выполнен `make bench_queue_quick` - **THEN** за несколько минут проходят ячейки перегрузки на двух классах, большой конкуренции на классе с наибольшей памятью, предела, второго worker и рестарта worker, код выхода 0, каталог метки в git не попадает #### Scenario: Вложение потеряно - **WHEN** на вложение ответили 202, а после разбора очереди метаданных нет или они не `ready` и не `failed` - **THEN** ячейка помечена, число потерянных и зависших названо в сводке, а код команды в конце метки ненулевой #### Scenario: Завершение ядром из-за памяти - **WHEN** ядро завершает процесс обработки или процесс 1 worker по памяти контейнера - **THEN** ячейка помечена `oom`, контейнер worker перезапускается сам, если завершён его процесс 1, число завершений, перезапусков и повторов записано как результат настройки, а не как сбой команды, а принятые вложения дошли до `ready` или названного `failed` #### Scenario: Прерванная метка - **WHEN** длинный прогон прерван, и он запущен снова с `RESUME=1` на том же commit - **THEN** готовые ячейки не снимаются заново, а незавершённая снимается с новой попыткой ### Requirement: Очередь под перегрузкой в отчёте `REPORT.md` SHALL содержать по профилю очереди: - гипотезы с числовыми порогами «подтверждено / нет», записанные и зафиксированные commit раньше меток замера; - методику: стенд, лимиты, настройки, классы, интенсивности и окна, контрольный поток, повторы и как читается шум; - определения: что считается очередью в трёх местах, throughput, время до `ready`, восстановление; - таблицы результатов метки: throughput, очередь, p50, p95 и p99 времени до `ready`, RSS, `memory.peak`, CPU и троттлинг — по настройкам и классам; блоки предела, второго worker и рестартов; - backpressure и ограничение принятой работы: где работа перестаёт приниматься и ускоряться и что видит клиент; - восстановление: время, отсутствие потерянных, зависших и дублей эффекта, контрольный поток; - вывод по каждой гипотезе, компромисс latency и ресурсов как вывод из данных, рекомендуемую настройку с условиями и решение о значениях по умолчанию с обоснованием; - обоснование предела незавершённых заданий по измеренному потолку; - ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, одна нода S3 на свежем volume, число worker, лимиты контейнеров, синтетические изображения. Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться вручную. Метка SHALL быть снята с закоммиченного кода, commit — в шапке. #### Scenario: Гипотезы очереди до прогонов - **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки - **THEN** commit с гипотезами раньше commit с результатами метки #### Scenario: Выводы по метке очереди - **WHEN** проверяющий открывает раздел очереди в `REPORT.md` - **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки, числа совпадают со сводкой, а рекомендуемая настройка следует из правила и таблиц ### Requirement: Выключатель телеметрии стенда Команды `make bench_uploads`, `make bench_queue` и их быстрые варианты SHALL принимать выключатель телеметрии `TELEMETRY` со значениями `on` и `off`, по умолчанию `off`. С `on` стенд SHALL запускать сервисы телеметрии (требование «Фиксированный стенд») и включать SDK в репликах, worker и relay с настройками рабочего стенда: все трассы, прежние границы histogram и интервал отправки метрик. Режим SHALL записываться в паспорт метки вместе с образами и лимитами сервисов телеметрии и называться в сводке; это не отладочное переопределение: продолжение прерванной метки (`RESUME=1`) SHALL требовать тот же режим. Другие профили выключатель MUST NOT принимать: с `on` — ненулевой код до запуска стенда и сообщение с именами профилей, которые его принимают. С включённой телеметрией сумма лимитов CPU стенда может превысить число CPU ВМ: тогда это SHALL быть предупреждением в паспорте и сводке с обеими суммами, а не отказом — лимиты CPU делят время, а ВМ уже отдаёт все ядра хоста. Сумма лимитов памяти проверяется прежним правилом. У профиля загрузок вариант «до» — образ кода без SDK: при `on` его сравнение с остальными вариантами — смешанное, и сводка SHALL это называть. У профиля очереди CPU, троттлинг и пик памяти Collector и хранилищ телеметрии SHALL сохраняться новыми столбцами в конце таблицы ячеек; без телеметрии они пусты. #### Scenario: Очередь с телеметрией - **WHEN** выполнен `make bench_queue_quick TELEMETRY=on` - **THEN** записи о старте реплик, worker и relay называют телеметрию включённой и адрес Collector стенда, Collector, Prometheus, Loki и Tempo работают, Grafana нет, в паспорте режим `on`, у ячеек заполнены столбцы сервисов телеметрии, код выхода 0 #### Scenario: Выключатель у другого профиля - **WHEN** профиль, кроме профилей загрузок и очереди, запущен с включённым выключателем телеметрии - **THEN** команда завершается ненулевым кодом до запуска стенда и называет профили, которые принимают выключатель #### Scenario: Лимиты CPU больше ВМ - **WHEN** сумма лимитов CPU профиля очереди с телеметрией больше числа CPU ВМ - **THEN** прогон идёт, а паспорт и сводка содержат предупреждение с суммой лимитов и числом CPU ВМ #### Scenario: Продолжение в другом режиме - **WHEN** прерванная метка профиля очереди, снятая с `TELEMETRY=on`, продолжается с `RESUME=1` без выключателя - **THEN** команда завершается ненулевым кодом до запуска стенда и называет режим метки ### Requirement: Профиль цены телеметрии Команда `make bench_telemetry` (метка `TELEMETRY_LABEL`, по умолчанию `baseline`) SHALL мерить цену телеметрии и то, что теряет каждый вариант её настройки, при одинаковой нагрузке. Команда `make bench_telemetry_quick` — все варианты, кроме копии A/A, по одному разу и с короткими окнами, метка `quick-telemetry-…`, в git не идёт. Результаты SHALL сохраняться в `evidence/telemetry-cost/<метка>/`. Занятая метка SHALL давать отказ до запуска стенда, кроме продолжения прерванной метки на том же commit (`RESUME=1`). Стенд — требование «Фиксированный стенд»: LB, две реплики, PostgreSQL, Valkey, S3, брокер, relay, worker и уборщик с лимитами рабочего стенда без swap, а в вариантах с телеметрией — Collector, Prometheus, Loki и Tempo. Каждый прогон — свежий стенд на новых volume. **Варианты** различаются только телеметрией, остальное одинаково: - `off` — телеметрия выключена, сервисов телеметрии нет; - `full` — как на рабочем стенде: все трассы, прежние границы, интервал отправки метрик 15 с, конфигурации Collector и Prometheus рабочего стенда; `full-aa` — тот же вариант под другим именем: разница с `full` — шум метода (A/A); - `head` — доля выбора трасс в голове 0,1 (`observability`, «Выбор трасс в голове»); - `tail` — типовой выбор трасс в Collector после завершения трассы: трассы со span в статусе ошибки, трассы не короче 0,25 с и 10 % остальных, срок ожидания решения по умолчанию; - `metrics` — агрегация метрик: интервал отправки 30 с, набор границ `coarse` (`observability`, «Наборы границ histogram») и отбор лишних рядов Prometheus — собственных метрик хранилищ; - `balanced` — сбалансированная конфигурация (`observability`, «Сбалансированная конфигурация телеметрии»). Каждый вариант SHALL проверяться применённым: записи о старте всех реплик, worker и relay называют настройки телеметрии варианта, Collector и Prometheus работают с его конфигурациями; иначе — отказ команды с названием прогона. До первого прогона SHALL проверяться конфигурации вариантов: слой Collector — инструментом Collector и сравнением с рабочей конфигурацией, конфигурация Prometheus — инструментом Prometheus и совпадением с рабочей вне блоков отбора рядов; расхождение — отказ до стенда. **План** — вариант × повтор, повторов три, круги с перестановкой от зерна, повтор одного варианта не идёт подряд; план — в паспорте до первого прогона. **Нагрузка прогона** — открытая модель через LB, интенсивности заданы методикой и одинаковы во всех вариантах, ниже насыщения: чтение страницы истории, отправка сообщения с новым ключом, `GET /users/me`, карточка чата, скачивание готовых вложений и загрузка настоящего изображения. Рядом идут **редкие события с известным счётом**: - скачивание вложения, у которого нет объекта в S3, — 500 API со статусом ошибки span; - загрузка изображения, которое проходит проверку структуры и не декодируется, — 202, затем `failed` worker; - регистрация пользователя с Argon2id — редкий маршрут (сохраняется ли он, если он не медленный); - в окне отказов — запись в чат под короткой блокировкой таблицы сообщений: медленные запросы быстрого маршрута. Окна прогона: разогрев, чистое окно — по нему считается цена, — окно отказов. Ответ не повторяется. Каждый запрос — строка с временем отправки, длительностью, статусом и `X-Request-Id`. После нагрузки стенд ждёт, пока незавершённых заданий нет, затем отправки последних метрик и решений выбора трасс и только потом читает хранилища. Для каждого прогона SHALL сохраняться: - по классам запросов чистого окна — число ответов, ошибки, p50, p95 и p99; время до `ready` по метаданным вложений; - CPU, троттлинг и память (наибольшая, пик контейнера, анонимная) каждого контейнера стенда в чистом окне; CPU реплик на запрос; - объём приёма по сигналам: span, записи журнала и точки метрик, принятые и отправленные Collector; байты и единицы, принятые Tempo и Loki; ряды и отсчёты Prometheus; рост каждого хранилища на диске за прогон; - потери по звеньям SDK → Collector → хранилище для span и записей журнала — отдельно от отброшенного выборкой в голове (счёт начатых span SDK) и в Collector (его решения); - по каждому классу редких событий — счёт по клиенту и найденное в хранилищах: трасса по `X-Request-Id` (у неудачной загрузки — вся цепочка до consumer span исхода `failed`), запись журнала, счёт в метрике и переход от записи журнала к трассе; - точность квантилей: p95 и p99 двух лёгких маршрутов из buckets против точной длительности тех же запросов из журнала. Граница чёрного ящика: генератор обращается к приложению только по HTTP через LB, истина о готовности — метаданные `GET /attachments/{id}`. Сверх этого оркестратор: читает счётчики cgroup и записи о старте процессов в журналах контейнеров; вставляет до нагрузки одну строку вложения без объекта в базу свежего стенда (схему не трогает); держит в окне отказов блокировку таблицы сообщений в своей сессии PostgreSQL; считает незавершённые задания в PostgreSQL; читает Prometheus, Loki, Tempo и метрики Collector по HTTP из вспомогательного контейнера в сети хранилищ; меряет размер volume хранилищ только на чтение. Приложение он не импортирует. Достоверность: - строк о запросах SHALL быть столько, сколько итераций у генератора; недосланные итерации, выгрузка хоста в swap, гибель хранилища или сервиса телеметрии и завершение ядром из-за памяти — пометки прогона; - каждая принятая загрузка SHALL стать `ready`, а каждая загрузка недекодируемого изображения — `failed`; иначе прогон помечен, а код команды в конце метки ненулевой; - выборка из хранилищ, упёршаяся в предел числа результатов, SHALL быть отказом, а не неполным счётом; - потери телеметрии в варианте — результат с числами по звеньям, а не отказ команды. В паспорте метки SHALL быть: лимиты и образы всех контейнеров; таблица вариантов с настройками SDK и контрольными суммами конфигураций Collector и Prometheus; интенсивности, окна и расписание блокировок; план; версия ядра ВМ; состояние хоста; посторонние контейнеры; сумма лимитов против ресурсов ВМ. Сводка SHALL давать по каждому варианту медиану и разброс повторов, шум A/A, таблицы требования «Цена телеметрии в отчёте», вывод по каждой гипотезе и по критериям сбалансированной конфигурации и графики. #### Scenario: Полный профиль цены телеметрии - **WHEN** выполнен `make bench_telemetry` - **THEN** в `evidence/telemetry-cost/<метка>/` есть паспорт, таблицы прогонов, компонентов и классов редких событий, сводка с выводами по гипотезам и критериям и графики, код выхода 0 #### Scenario: Быстрый профиль цены телеметрии - **WHEN** выполнен `make bench_telemetry_quick` - **THEN** каждый вариант, кроме копии A/A, проходит по одному разу на свежем стенде, код выхода 0, каталог метки в git не попадает #### Scenario: Вариант не применён - **WHEN** запись о старте реплики, worker или relay называет настройки телеметрии, отличные от варианта прогона - **THEN** команда завершается ненулевым кодом и называет прогон и процесс #### Scenario: Конфигурация варианта не прошла проверку - **WHEN** слой Collector меняет что-то, кроме выбора трасс, или конфигурация Prometheus варианта расходится с рабочей вне блоков отбора рядов - **THEN** команда завершается ненулевым кодом до запуска стенда и называет файл #### Scenario: Принятая загрузка не дошла до итога - **WHEN** после ожидания у принятой загрузки нет статуса `ready`, а у загрузки недекодируемого изображения — `failed` - **THEN** прогон помечен, число таких загрузок названо в сводке, а код команды в конце метки ненулевой #### Scenario: Прерванная метка цены телеметрии - **WHEN** прогон метки прерван, и он запущен снова с `RESUME=1` на том же commit - **THEN** готовые прогоны не снимаются заново, а незавершённый снимается с новой попыткой ### Requirement: Цена телеметрии в отчёте `REPORT.md` SHALL содержать по профилю цены телеметрии: - гипотезы с числовыми порогами «подтверждено / нет», записанные и зафиксированные commit раньше метки; - методику: стенд, лимиты, варианты и их параметры, нагрузку и окна, редкие события и как они вносятся и считаются, источник каждого измерения, повторы и правило шума: изменение — эффект, только если разбросы повторов не пересекаются и изменение медианы больше разницы `full` и `full-aa`; - таблицы метки по вариантам: p50, p95 и p99 лёгких запросов и остальных классов, CPU реплик на запрос, CPU и память по компонентам, приём по сигналам, рост хранилищ с пересчётом на сутки и на срок хранения, потери по звеньям отдельно от отброшенного выборкой, время до `ready`; - что теряет каждый вариант: по классам редких событий — трассу, цельную цепочку загрузки, запись журнала, счёт в метрике и переход от журнала к трассе; точность квантилей из buckets; свежесть метрик при редкой отправке; объяснение причин потерь; - сбалансированную конфигурацию: состав, почему каждое правило, критерии и вывод по каждому из них: - B1 — сохранены трассы всех внесённых 500 API и всех медленных по серверу записей (длительность записи доступа — та же величина, что server span, — не меньше 0,25 с) и цепочки всех неудачных загрузок; регистрация — редкий, но быстрый маршрут, у неё называется доля сохранённых трасс; - B2 — приём Tempo не больше 25 % варианта `full` и меньше, чем у `tail`; рядов Prometheus не больше 40 % `full`; - B3 — непреднамеренных потерь нет, трассы не отброшены до решения, пик памяти Collector не больше двух третей его лимита; - B4 — надбавка против `off`: CPU реплик на запрос не больше 25 %, p95 лёгких запросов — не больше 3 мс, p99 — не больше 10 мс; - B5 — у сохранённых классов каждая запись журнала с идентификатором трассы ведёт на трассу в Tempo; - рекомендацию с условиями: что оставить на рабочем стенде, что брать при большей нагрузке и когда нужна выборка в голове; - режим телеметрии меток профилей загрузок и очереди последнего шага; - ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте, короткие окна на свежих хранилищах (рост на диске — журнал предзаписи, без сжатых блоков), синтетические данные, один Collector, лимиты — доли CPU, Grafana не мерилась. Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться вручную. Метка SHALL быть снята с закоммиченного кода, commit — в шапке. #### Scenario: Гипотезы цены телеметрии до метки - **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки - **THEN** commit с гипотезами раньше commit с результатами метки #### Scenario: Выводы по метке цены телеметрии - **WHEN** проверяющий открывает раздел цены наблюдаемости в `REPORT.md` - **THEN** у каждой гипотезы и у каждого критерия B1–B5 есть вывод со ссылкой на таблицы сводки, числа совпадают со сводкой, а для каждого варианта названо, какие внесённые ошибки и медленные запросы он потерял и почему