Files
mtusi2026lab3/openspec/changes/scaling-bench/tasks.md
T
ricoromaandClaude Opus 5.5 02fd3d8a36 feat: add track 1 scaling series to the bench stand
Series a/b/pool/ab/quick in bench/run.py: per-cell fresh stand with the
configuration's replicas and max_connections, open-model mixed profile
(k6/mixed.js), fixed levels and R* search by SLO, a sampler container
for cgroup, VM, HAProxy and PostgreSQL metrics, resume and a stand
lock. Pure helpers in bench/scaling.py, SVG plots in bench/plots.py,
series mode for bench_compare and bench_ab. Hypotheses H1-H3 go to
REPORT.md before the first series.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 03:28:36 +03:00

418 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Tasks
Как строить — `design.md` (дальше «решение N»). Что должно получиться —
дельта `specs/load-benchmark/spec.md`.
**Правила.**
- Перед первым файлом слоя прочитать его правило:
- `bench.md` — всё в `bench/`;
- `run-modes.md` — `Makefile`;
- `balancer.md` — для справки о слотах и runtime API.
- Перед `bench/plots.py` загрузить скилл `dataviz`.
- Файлы меняются только через Edit/Write. Приложение (`src/`),
контракт и рабочий стенд не меняются.
**Порядок:**
1. код;
2. коммит кода с гипотезами в `REPORT.md`;
3. самопроверки быстрой серией;
4. регрессия прежних профилей;
5. серии — перед каждой проверка хоста;
6. evidence;
7. `REPORT.md`;
8. `AGENTS.md`.
**Долгие команды.** Всё дольше пары минут — фоном, с журналом в
`<scratchpad>/scaling-bench/`:
```sh
nohup make <цель> > <scratchpad>/scaling-bench/<имя>.log 2>&1 &
```
Ожидание — Monitor с циклом `until ! pgrep -f "bench/run.py"
>/dev/null; do sleep 15; done; tail -30 <журнал>`, не больше 30 мин на
вызов. Затем — снова. Голый `sleep` в Bash не использовать. Ни один
вызов инструмента не должен упереться в 10 минут.
**Проверка хоста перед каждой серией** (A, B, pool, A/A; самопроверки и
регрессия — без неё), по брифу:
- `pmset -g batt` — `AC Power`;
- `memory_pressure | tail -1` — давления нет;
- `docker ps` — посторонних нет; рабочий стенд — `make stop`;
- `docker info --format '{{.NCPU}} {{.MemTotal}}'` — 12 и ~7,75 GiB;
- `vm_stat | grep Swapouts` — до и после серии.
Плохо — Telegram «хост не готов к замеру …», остановка и отчёт
основной сессии.
## 1. Код стенда
- [x] 1.1 Профили серий (решения 1, 14).
- `bench/run.py`:
- новые поля `Profile` по списку решения 14 и свойство `is_series`;
- хелпер `scaling_profile(name, series, configs, **поля)` с общими
значениями решений 1–3 и 6: лимиты PostgreSQL 2 / 1g, LB 1 /
256m, Valkey 0.5 / 128m, k6 2 / 1g (`generator_cpu_limit` 1.8),
сэмплер 0.25 / 128m; `sizes=(10_000,)`, `repeats=3`,
`members=10`, `write_chats=10`, смесь, SLO, лестница, окна;
- профили `scaling_a`, `scaling_b`, `scaling_pool`, `scaling_ab`
(1 × 1 и 6 × 1, решение 11), `scaling_quick` — с конфигурациями
решений 1 и 14;
- `compose_env` передаёт `BENCH_DB_MAX_CONNECTIONS`: значение
конфигурации ячейки, у прочих профилей — 100.
- `bench/bench.compose.yml`: в `command` сервиса `postgres` —
`-c max_connections=${BENCH_DB_MAX_CONNECTIONS:?run make bench}`.
Проверка: `uv run python -c` с импортом `run` печатает конфигурации
и лимиты пяти профилей. `docker compose -p mtusi-bench --env-file
bench/bench.env -f docker-compose.yml -f bench/bench.compose.yml
config --quiet` с переменными `BENCH_*` проходит.
- [x] 1.2 Хост, паспорт, бюджет, блокировка — для всех профилей
(решения 1, 5, 12).
- `host_state()` — поле `swapouts` (`vm_stat`).
- Удалить `SWAP_WARN_MIB` и предупреждение о занятом swap. В конце
`main()` — предупреждение о приросте `swapouts`; батарея — как
раньше.
- `static_passport()` — `performance_cores` и `efficiency_cores`
(`sysctl hw.perflevel0/1.physicalcpu`, иначе null).
- `vm_warnings()` учитывает память генератора и сэмплера.
- Для серий — `meta.budget` по конфигурациям и отказ (код 2), если
сумма CPU конфигурации больше `NCPU` ВМ.
- Блокировка: `fcntl.flock` на `bench/.bench.lock` в начале `main()`;
занята — код 2 с причиной.
- `compare.py` `passport_rows`: в строке хоста — прирост выгрузок.
Проверка: `make lint`. Вызов `host_state()` печатает `swapouts`.
Второй одновременный запуск — задача 3.3.
- [x] 1.3 Сценарии k6 (решения 2, 3, 7).
- `bench/k6/prepare.js`: `WRITE_CHATS` (по умолчанию 1) создаёт
чаты записи со всеми пользователями. В фикстуре `writeChatIds`, а
`writeChatId` = первый.
- Новый `bench/k6/mixed.js`:
- три сценария `ramping-arrival-rate` (`read`, `write`, `me`) с
`startRate` и двумя стадиями; VU по `prevus_per_rps` /
`vus_per_rps`;
- тег `window` на каждый запрос по `exec.scenario.startTime`;
- проверки ответов; счётчики `short_pages` и `instance_ok` (тег
`instance`, подметрики по `INSTANCES` и `-`);
- пороги «всегда выполнены» для подметрик окна и пороги
`abortOnFail` с `delayAbortEval` = прогрев + 5 с;
- `setup()` → `{t0}`; итог — `summaryFiles`;
- ключ записи — только `messageHeaders(token)`.
Окружение: `LEVEL`, `START`, `MIX`, `WARMUP_S`, `MEASURE_S`,
`TIMEOUT`, `PRE_VUS_PER_RPS`, `MAX_VUS_PER_RPS`, `SEED`,
`INSTANCES`, `ABORT_ERRORS`, `ABORT_P95_MS`, `STEP`, `NAME`.
Проверка: `k6 inspect` сценария в образе k6 стенда — опции
разбираются. Задача 3.1 сверяет доли и окно на живом стенде.
- [x] 1.4 Сэмплер и контейнеры стенда (решения 6, 7).
- Новый `bench/sampler.sh` (bash, только внутри контейнера): строки
`cg`, `vm`, `lb` в `/work/samples.log`; фоновый `psql … \watch 1`
с запросом решения 7 в `/work/pg-samples.log`; `PGPASSWORD` из
`POSTGRES_PASSWORD`.
- `bench/run.py`:
- `Stand.start()` запускает k6 с `--cpus/--memory/--memory-swap`,
если `generator_cpus` задан;
- `Stand.start_sampler()` и `stop_sampler()`: образ — у
`mtusi-bench-postgres`, параметры решения 7, проверка первых
строк за 5 с, иначе `BenchError`;
- `leftovers()` и `Stand.stop()` знают `mtusi-bench-sampler`;
- `Stand.limits()` добавляет лимиты k6 и `SHOW max_connections`; не
равно конфигурации — `BenchError`;
- `Watcher(..., rss=False)` — один `docker inspect` реплик,
PostgreSQL, Valkey и LB в секунду.
Проверка: `bash -n bench/sampler.sh`. Задача 3.1 видит строки всех
видов.
- [x] 1.5 Новый `bench/scaling.py` — чистые функции, только stdlib, без
docker (решения 3, 6–9):
- `SCALING_FIELDS`, `SEARCH_FIELDS`, `SAMPLE_FIELDS`, `THRESHOLDS`;
- лестница и автомат поиска: фиксированные уровни → L0 → подъём,
спуск → деление; `floor`, `search_limit`;
- разбор итога k6 ступени;
- разбор строк сэмплера и PostgreSQL;
- окна и агрегаты: CPU, троттлинг, память, ВМ, PSI, WAL, классы
ожидания, `pool_busy_share`, LB, распределение по `X-Instance-Id`;
- вердикт SLO и брака генератора, признаки `signs`;
- строки `runs.csv`, `searches.csv`, `samples.csv`;
- `render_summary()` с `host_cost` по сводке серии;
- `--selftest`: синтетические исходы ступеней (подъём, спуск от
первой нарушенной, оба фиксированных уровня провалены, брак) и
синтетические строки сэмплера.
Проверка: `uv run python bench/scaling.py --selftest`:
- R* = наибольший пройденный уровень, F / P ≤ 1,06;
- L0 из примеров решения 3: 596, 745, 1455, 1819;
- CPU и троттлинг из известных разностей;
- код 0.
- [x] 1.6 Исполнитель серий в `bench/run.py` (решения 2–5, 8).
- `Bench.run_series()`:
- план кругами с `order_seed`, в `meta.plan`;
- пропуск готовых ячеек при `--resume`.
- `run_cell()`:
- свежий стенд с конфигурацией через `dataclasses.replace`;
- `prepare_load()` с `WRITE_CHATS`, сэмплер;
- фиксированные уровни, поиск, сверка записей и читаемого чата;
- строка `searches.csv`; `stand.stop()`.
- `run_step()`:
- снимки RSS и `count(*)` до и после, k6 под облегчённым `Watcher`;
- разбор итога и окна сэмплера, «too many clients» из `docker logs
-t --since/--until`, `host_swapouts`;
- строка `runs.csv`, посекундные строки `samples.csv`;
- пауза и `wait_ready` после нарушения;
- строка вывода и `progress.json`.
- `RUN_FIELDS` += `SCALING_FIELDS`, `PREFILL_FIELDS` += `cell`,
`attempt` — в конец.
- `Results`: `add_step`, `add_search`, `add_samples`; ветка
`write_summary` для серий; `raw/` с `exist_ok`.
- `main()`:
- `--resume` с условиями решения 5 (чистота без своей метки);
- для серий — уборка устаревших остатков при взятой блокировке.
- `eta()` по ячейкам.
Проверка: `make lint`; задачи 3.1 и 3.3.
- [x] 1.7 Новый `bench/plots.py` (решение 13), после скилла `dataviz`:
- `render_series(label_dir)` — `p95-by-rate.svg`,
`cpu-by-component.svg` в каталоге метки; вызывается в конце серии;
- `render_combined(labels, out)` — `rstar-by-replicas.svg`,
`p95-by-rate-<серия>.svg`, `cpu-by-component.svg` и `summary.md`
(R*, эффективность, R*(1 × 4) / R*(1 × 1), k_sat, признаки на
k_sat ± 1) в `evidence/plots/<PLOTS>/`;
- CLI `--labels … --out …`.
Проверка: задача 3.4 — SVG открываются, PNG через `qlmanage -t -s
1000` просмотрен.
- [x] 1.8 Сравнение и «до/после» для серий (решение 11).
- `bench/compare.py`: режим серий — методика без `name` / `series` /
`configs`, лимиты по общим конфигурациям; R*, задержки на
фиксированных уровнях, CPU на запрос, CPU PostgreSQL на R*;
несравнённые конфигурации и `generator_bound` — в замечаниях; шум
`AA` по R*. Серия против матрицы — отказ. Режим матрицы не
меняется.
- `bench/ab.py`: `--series` — шаги 1 и 5 через `make bench_scaling
SERIES=… SCALING_LABEL=…`.
Проверка: задача 3.4.
- [x] 1.9 `Makefile` и `.gitignore` (решение 14, `run-modes.md`).
- Цели:
- `bench_scaling` — `SERIES` обязателен, иначе подсказка и код 2;
`SCALING_LABEL ?= scaling-$(SERIES)`; `RESUME=1` → `--resume`;
- `bench_scaling_quick`;
- `bench_plots` — `LABELS`, `PLOTS ?= scaling`;
- `SERIES` у `bench_ab`.
Все — под `$(KEEP_AWAKE)`, с комментариями в стиле файла.
- `.gitignore`: `bench/.bench.lock`, `evidence/plots/quick-*/`.
Проверка: `make -n bench_scaling SERIES=a`, `make -n
bench_scaling_quick`, `make -n bench_plots LABELS=x` печатают ожидаемые
команды; `make bench_scaling` без `SERIES` — подсказка.
## 2. Документы до замеров и коммит кода
- [x] 2.1 `.claude/rules/bench.md`:
- раздел трека 1 из «что меняется» — в «как устроено»: серии и
конфигурации, бюджет, свежий стенд в ячейке, порядок кругами,
ступени, SLO, поиск R*, генератор с лимитом и брак, сэмплер (его
соединение в границе пула), файлы метки, продолжение, блокировка и
уборка остатков сериями, `SERIES` у `bench_ab`, режим серий
`bench_compare`, графики;
- «Что не меняется между метками» — лимиты генератора и сэмплера;
- «Результаты» — правило хоста: выгрузка в swap и давление вместо
«swap занят — перезагрузить»;
- «Как писать» — `sampler.sh` работает только в контейнере.
Проверка: `grep -n "swap" .claude/rules/bench.md` — нет требования
«swap около нуля».
- [x] 2.2 Скилл `run-mtusi-messenger` (`SKILL.md`): строка `make
bench_scaling_quick` рядом с прочими быстрыми профилями. Проверка: `grep
bench_scaling .claude/skills/run-mtusi-messenger/SKILL.md`.
- [x] 2.3 Статические проверки: `make lint`, `make check`, `uv run
python -m py_compile bench/*.py`, `bash -n bench/sampler.sh`,
`openspec validate scaling-bench --strict`. Проверка: все с кодом 0.
- [x] 2.4 `REPORT.md`, «Эксперименты и отказы» — раздел «Цена
масштабирования (трек 1)» до первой серии:
- гипотезы H1, H1б, H2, H3 из решения 10 — что подтвердит и что
опровергнет;
- методика: бюджет (таблица решения 1), ядра хоста, профиль, ступени,
SLO, правило R*, повторы и порядок;
- заготовки «Результат» и «Итог по гипотезам» с пометкой «после
серий».
Проверка: раздел есть, числа гипотез совпадают с решением 10.
- [x] 2.5 Коммит кода, правил и гипотез: `feat: add track 1 scaling
series to the bench stand`, в конце — строка `Co-Authored-By` из
брифа. Проверка: `git status` — чисто; этот commit старше первой
метки серий (спек, «Гипотезы до прогонов»).
## 3. Самопроверки быстрой серией (без проверки хоста)
- [ ] 3.1 `make bench_scaling_quick` фоном. Проверка — код 0, в метке:
- `meta.plan` с двумя ячейками; `budget` и лимиты k6 /
`max_connections` по конфигурациям (50 у второй);
- `runs.csv` с новыми столбцами в конце, все заполнены;
- доли 70 : 20 : 10 в окне; `sent` = запланированным ± 3, `missing`
0 на пройденных ступенях;
- сумма `instances` = успешным окна;
- `samples.csv` со строками каждого контейнера и `vm` за каждую
секунду окна;
- `searches.csv` с R*, `resolution` ≤ 1,12 (одно деление: 1,25^½) и
сверкой записей;
- `summary.md`, `p95-by-rate.svg`, `cpu-by-component.svg`;
- секретов нет: `.work/` удалён, `grep -ril token <метка>/raw` пусто,
`grep -r "$HOME" <метка>` пусто.
- [ ] 3.2 Запас генератора и окно k6 (решение 6) по метке 3.1:
- CPU k6 на 1 000 запросов/с × ожидаемая вершина серии B (6 ×
R*(1 × 1)) ≤ 50 % лимита;
- пик памяти k6 на VU × `vus_max` вершины ≤ 70 % лимита;
- досрочный выход по порогам (код 99) встретился на нарушенной
ступени или проверен отдельным запуском `run.py --profile
scaling_quick` с завышенным уровнем.
Не так — поднять `generator_cpus` / `generator_memory` в пределах
бюджета решения 1, записать в design (раздел «Найдено в apply») и
`bench.md`, коммит кода, повторить 3.1. Запасной вариант тега окна —
Risks design. Проверка: числа записаны в
`evidence/tests/scaling-bench-checks.md`.
- [ ] 3.3 Продолжение, блокировка, уборка:
- во время `make bench_scaling_quick` — `make bench_quick` → код 2
«другой прогон»;
- `pkill -TERM -f "bench/run.py"` после первой ячейки → код 130,
метка `incomplete`, стенд удалён;
- перед продолжением — искусственный остаток: `docker run -d --name
mtusi-bench-sampler --entrypoint sleep <образ k6 стенда> 600`;
- `make bench_scaling SERIES=quick SCALING_LABEL=<та же> RESUME=1` →
остаток удалён самой командой (строка в выводе), снята только
вторая ячейка, метка `complete`;
- отказ продолжения на другом коде: копия пробной метки, в её
`meta.json` (Edit) commit подменён и статус `incomplete`, затем
`RESUME=1` на копии → код 2 с причиной. Копия — `quick-*`, в git не
идёт, после проверки удаляется.
Проверка: выводы в `evidence/tests/scaling-bench-checks.md`.
- [ ] 3.4 Сравнение, «до/после», графики:
- вторая быстрая метка; `make bench_compare BEFORE=<1> AFTER=<2>
AA=<1>` — таблица по общим конфигурациям с шумом и вердиктом;
- `BEFORE=<1> AFTER=<1>` — Δ = 0;
- `BEFORE=<быстрая серия> AFTER=<метка make bench_quick>` — отказ
«разная методика»;
- `uv run python bench/ab.py --before x --after y --reapply HEAD
--series quick --dry-run` — шаги с `make bench_scaling`;
- `make bench_plots LABELS="<1> <2>" PLOTS=quick-check` — SVG и
`summary.md`; PNG через `qlmanage -t -s 1000 -o
<scratchpad>/scaling-bench …` просмотрен (Read): оси, подписи,
легенда, SLO.
Проверка: выводы в `evidence/tests/scaling-bench-checks.md`.
## 4. Регрессия прежних профилей
- [ ] 4.1 На commit кода фоном, по очереди: `make bench_quick`, `make
bench_restore_quick`, `make bench_failover_quick`, `make
bench_rollout_quick`. Проверка:
- все с кодом 0;
- паспорт прежний: `max_connections` 100, k6 без лимита;
- предупреждения о swap только при приросте выгрузок;
- прочие профили по-прежнему отказывают при остатках стенда, а не
удаляют их.
- [ ] 4.2 `evidence/tests/scaling-bench-checks.md`:
- шапка по брифу: спеки, change, дата, commit, стенд, хост;
- выводы 2.3 и 3.1–4.1 (без секретов и путей домашнего каталога);
- коммит `docs: add scaling-bench self-checks`.
Проверка: дерево чистое.
## 5. Серии (проверка хоста перед каждой)
- [ ] 5.1 Проверка хоста. Затем `make stop`, `nohup make bench_scaling
SERIES=a` (~50 мин), ожидание циклами Monitor. После — `Swapouts`.
Проверка:
- `evidence/bench/scaling-a/` `complete`;
- 9 ячеек без `generator_bound`;
- коммит метки `docs: add scaling series A` — до следующей серии,
иначе её паспорт получит `dirty: true`.
- [ ] 5.2 Так же серия B: `SERIES=b`, ~100 мин, 18 ячеек. Прервалась —
`RESUME=1` после разбора причины. Проверка: метка `complete`, коммит
`docs: add scaling series B`.
- [ ] 5.3 Так же серия pool: `SERIES=pool`, ~35 мин, 6 ячеек. Проверка:
метка `complete`, коммит `docs: add scaling pool series`.
- [ ] 5.4 Разбор серии pool по H3:
- отказы «too many clients» и коды ответов при `max_connections`
50: `runs.csv`, журнал LB;
- отказ даёт 500, а не 503 → пункт `KNOWN_ISSUES.md`: путь
`src/infra/db/errors.py`, требование спека `data-storage`, правка
(решение 10), без исправления.
Вопрос основной сессии — в итоговый отчёт. Проверка: пункт есть или
в design записано, что 503.
- [ ] 5.5 Проверка хоста, затем `nohup make bench_scaling SERIES=ab
SCALING_LABEL=scaling-aa` (~35 мин; профиль `scaling_ab` — 1 × 1 и
6 × 1, решение 11). Проверка:
- метка `complete`, коммит `docs: add scaling A/A label`;
- рабочий стенд снова поднят (`make run_docker`, `make lb_stats` —
все `UP`).
## 6. Evidence
- [ ] 6.1 Графики и сравнения:
- `make bench_plots LABELS="scaling-a scaling-b" PLOTS=scaling`;
k_sat и признаки на k_sat ± 1 — из его `summary.md`;
- `make bench_compare BEFORE=scaling-b AFTER=scaling-aa` — шум между
сессиями;
- `make bench_compare BEFORE=scaling-b AFTER=scaling-a` — 4 × 1
против k = 4;
- PNG графиков просмотрены.
Проверка: `evidence/plots/scaling/` (3+ SVG и `summary.md`) и два
файла `evidence/compare/`.
- [ ] 6.2 В `evidence/tests/scaling-bench-checks.md` — проверки хоста
перед каждой серией и `Swapouts` до и после. Коммит evidence `docs:
add scaling-bench plots and comparisons`. Проверка: дерево чистое, в
evidence нет секретов и абсолютных путей домашнего каталога.
## 7. `REPORT.md`
- [ ] 7.1 Раздел «Цена масштабирования (трек 1)» по решению 15:
- результаты A, B, pool — таблицы из `summary.md` меток и графиков;
- графики (ссылки на SVG);
- точка насыщения и почему рост реплик перестаёт помогать — по
признакам `signs` на k_sat ± 1;
- итог H1, H1б, H2, H3 как получился;
- шум A/A и согласованность 4 × 1 / k = 4;
- фраза про `workers`;
- ограничения.
Ещё:
- строки таблицы доказательств «5» вместо TODO «Выбранный трек 5»;
- пункты в «Ограничения и следующие шаги»: серия B до 6, граница
пула на дефолтах, разнородные ядра, генератор на том же хосте,
окно 20 с;
- кандидаты `scaling-improvement` по узкому месту (решение 11).
Проверка: у каждой новой строки есть команда, наблюдение и файл;
числа — из файлов меток и таблиц команд.
## 8. `AGENTS.md` и завершение
- [ ] 8.1 `AGENTS.md`:
- команды: `bench_scaling`, `bench_scaling_quick`, `bench_plots`,
`SERIES` у `bench_ab`, режим серий `bench_compare`;
- карта кода: `bench/scaling.py`, `plots.py`, `sampler.sh`,
`k6/mixed.js`, `evidence/plots/`, метки `scaling-*`;
- «Переходное состояние» — снять пункт трека 1 `scaling-bench`,
оставить `scaling-improvement`.
Проверка: `grep -n "scaling-bench" AGENTS.md` — нет обещаний «будет».
- [ ] 8.2 Финал:
- `make lint`, `openspec validate scaling-bench --strict`;
- отметить задачи;
- коммит `docs: report track 1 scaling series`;
- `graphify update .`;
- рабочий стенд `mtusi-lab3` поднят, все реплики `UP`.
Проверка: дерево чистое.