Files
mtusi2026lab5/openspec/changes/pipeline-reliability/specs/load-benchmark/spec.md
T
2026-10-31 10:08:03 +03:00

26 KiB
Raw Blame History

Spec Delta

MODIFIED Requirements

Requirement: Фиксированный стенд

Стенд SHALL состоять из балансировщика (LB), реплик приложения, PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса уборщика. Брокер, 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. В сериях трека 1 предел соединений PostgreSQL (max_connections) — параметр конфигурации серии, по умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до наполнения.

Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека 1 — во всех прогонах одной конфигурации:

  • у каждой реплики приложения — лимит CPU и памяти без swap, заданный методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по конфигурации);
  • у LB, PostgreSQL, Valkey, S3 и уборщика — свои лимиты CPU и памяти без swap, заданные методикой; в серии трека 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 видит готовыми все реплики.

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 и уборщика записаны в паспорт

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 <commit> для отладки.

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.

Варианты кода:

  • «до» — образ 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 пик прогона отражает только окно, а не старт процесса

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 по счётчикам сверки равны запросам по метрикам шлюза, а при различии строка помечена