28 KiB
Tasks
Как строить — design.md (дальше «решение N»). Что должно получиться —
дельты specs/data-storage, specs/service-configuration,
specs/load-benchmark.
Правила.
- Правила слоёв. Перед первым файлом слоя прочитать его правило
через Read:
bench.md— всё вbench/;run-modes.md—Makefile;settings.mdиinfra.md—src/config/settings.py,config_example.toml;docker.mdиbalancer.md—docker-compose.yml;student-tests.md—student-tests/.
- Только Edit и Write. Файлы меняются только ими. Рабочий
config.toml(не в git) — тоже через Edit, его значения в ответ и журнал не печатать. - Коммиты — со строкой
Co-Authored-Byбрифа, кроме двух, которые делает самmake bench_ab. Push, checkout, reset, stash, rebase нельзя. - Упавший тест — сначала разбор и названная причина, потом правка (AGENTS.md).
- Уведомления в Telegram — по брифу, номер этапа даёт основная сессия.
Порядок (решение 4):
- инструменты сравнения;
- H4;
- изменение X, тест и регрессия;
- откат R;
- A/A;
make bench_ab;- сравнения и критерий;
- регрессия на итоговом коде и цена соединения;
- evidence;
- отчёт и документы.
Между A/A (5) и make bench_ab (6) — только коммит метки и проверка
хоста.
Долгие команды. Всё дольше пары минут — фоном, журнал в
<scratchpad>/scaling-improvement/ (scratchpad сессии из брифа):
nohup make <цель> > <scratchpad>/scaling-improvement/<имя>.log 2>&1 &
Ожидание — until ! pgrep -f "[b]ench/run.py" >/dev/null; do sleep 15; done; tail -30 <журнал>. Запуск — Bash с run_in_background или
Monitor, не дольше 30 мин на вызов, по истечении — снова. Голый sleep
в Bash не использовать. Ни один вызов инструмента не должен упереться в
10 минут.
Проверка хоста перед A/A (5) и перед make bench_ab (6), по брифу:
pmset -g batt—AC Power;memory_pressure | tail -1— давления нет, свободной памяти хватает на ВМ до 7,7 GiB;make stop, затемdocker ps— посторонних контейнеров нет;docker info --format '{{.NCPU}} {{.MemTotal}}'— 12 и ~7,7 GiB;vm_stat | grep Swapouts— до и после каждого прогона.
Плохо — Telegram «хост не готов к замеру scaling-improvement <что>: <проблема> — перезагрузи/подключи питание», остановка и отчёт основной сессии.
1. Инструменты сравнения серий (до замеров)
-
1.1
bench/scaling.py,config_stats(решение 7).- Новые поля по каждой конфигурации — медианы по завершённым ячейкам
на ступени R* (
step_at) и на ближайшей нарушившей выше неё (fail_step), тем же отбором, что уdb_cpu_r:- уровень первой нарушившей;
db_us_per_request,db_sessions_new,db_conn_maxна обеих ступенях.
- Имена — в стиле
db_cpu_r, напримерdb_us_r/db_us_f,sessions_r/sessions_f,conn_r/conn_f,level_f. - Если self-test проверяет поля
config_stats, дополнить его.
Проверка:
uv run python bench/scaling.py --selftestпечатаетselftest ok. - Новые поля по каждой конфигурации — медианы по завершённым ячейкам
на ступени R* (
-
1.2
bench/compare.py,render_series(решение 7).- После таблицы «R* по общим конфигурациям» и строки «Δ R*…» —
раздел
## PostgreSQL на R* и первой нарушившей ступени. - Строка — конфигурация × ступень (
R*,первая нарушившая). - Столбцы «до → после»: уровень, CPU PostgreSQL на запрос (мкс), новых
сессий за окно, соединений PostgreSQL. Нет значения —
—. - Аргумент
--change, по умолчаниюscaling-bench, заменяет зашитоеscaling-benchв строке шапки серии. - Сравнение матрицы не меняется.
Проверка — задача 1.5.
- После таблицы «R* по общим конфигурациям» и строки «Δ R*…» —
раздел
-
1.3
Makefile, цельbench_compare: добавить$(if $(CHANGE),--change "$(CHANGE)")и строку оCHANGEв комментарий цели. Цели skeleton не трогать (run-modes.md). Проверка:make -n bench_compare BEFORE=a AFTER=b CHANGE=xпечатает--change "x";- без
CHANGEаргумента нет.
-
1.4
.claude/rules/bench.md, раздел «Сравнение меток»:- вторая таблица серий (PostgreSQL на R* и первой нарушившей) и
параметр
CHANGE; - порог эффекта R* — «не меньше двух ступеней сетки: R* после / R* до ≥ √1,25 ≈ 1,118 (+11,8 %)» вместо «≥ 12 %» (решение 5);
- пул приложения в метке — дефолт
settings.py, а не окружение стенда. Пул из окружения попадает вstand.app_env, и сравнение откажет (решение 2).
Проверка: правило не противоречит коду 1.1–1.3.
- вторая таблица серий (PostgreSQL на R* и первой нарушившей) и
параметр
-
1.5 Самопроверки, вывод — в
<scratchpad>/scaling-improvement/compare-checks.logдля 9.1.-
make lint. -
make bench_compare BEFORE=scaling-db AFTER=scaling-db CHANGE=scaling-improvement:- код 0, шапка называет
scaling-improvement; - Δ R* 0 у всех четырёх конфигураций;
- во втором разделе у
4x1-pg0.5: R* 931, первая нарушившая 984, значения «до» и «после» совпадают.
Затем
rm evidence/compare/scaling-db__scaling-db.md: файл новый и не отслеживается. - код 0, шапка называет
-
make bench_compare BEFORE=quick-probe-pool-10-5-20261011T094150Z AFTER=quick-probe-pool-10-5-20261011T094150Z CHANGE=scaling-improvement— код 0, вывод в.gitignore. Пробные метки propose лежат вevidence/bench/, в git не идут; если их нет — пропустить с пометкой в 9.1. -
make bench_compare BEFORE=quick-probe-pool-10-5-20261011T094150Z AFTER=quick-probe-pool-10-0-20261011T094150Z— отказ «different methodology» сstand.app_env.DATABASE__MAX_OVERFLOW, код 1. -
git status --porcelain— толькоbench/scaling.py,bench/compare.py,Makefile,.claude/rules/bench.md.
Затем коммит
feat: compare PostgreSQL sessions and connections in track 1 series. -
2. Гипотеза H4 до замеров
-
2.1
REPORT.md, раздел «Цена масштабирования (трек 1)», после H3 — гипотеза H4 «Пул без переполнения» (решение 5):- утверждение, предсказание в числах, что опровергнет;
- критерий «подтверждено» и порог двух ступеней;
- механизм — исходники
QueuePool,db_sessions_newсерий, микропроба цены соединения, проба основной ячейки (design, Context).
Числа проб помечены как «проба при выборе, метки в git не идут». Коммит
docs: record track 1 improvement hypothesis H4. Проверка:git log --oneline -3— коммит H4 старше будущего X, числа совпадают с design.
3. Изменение X, тест и регрессия
-
3.1 Пул (решение 2):
src/config/settings.py:max_overflow: int = Field(default=0, ge=0)и комментарий: соединение переполнения закрывается при возврате и под нагрузкой открывается заново — процесс PostgreSQL и SCRAM ~11 мс CPU реплики на каждое (design changescaling-improvement);config_example.toml:max_overflow = 0и одна строка комментария;- рабочий
config.toml:max_overflow = 5→0, через Edit; docker-compose.yml, комментарий у лимитовpostgres:API_REPLICAS × pool_size (переполнения нет) + migrate ≤ max_connections.
Проверка:
uv run python -c "from src.config.settings import Database; d = Database(); print(d.pool_size, d.max_overflow)"→10 0(сценарий «Пул по умолчанию»);uv run python -c "from src.config import settings; print(settings.database.max_overflow)"→0;docker compose --env-file .env config --quiet— код 0.
-
3.2
student-tests/fault_hook.py: действиеdb-sessionsбез аргументов —psql(project, "SELECT sessions FROM pg_stat_database WHERE datname = current_database();\n"), строка в docstring. Ещё строкаdb-sessionsв списке действий hook в.claude/rules/student-tests.md. Проверка: безFAULT_PROJECThook по-прежнему отказывает с кодом 2; вызов на стенде — 3.6. -
3.3
student-tests/test_failures.py:test_pool_keeps_connections(api, tight_api, stand)в разделе «Хранение» (решение 8).- Маркер
@pytest.mark.spec("data-storage", "Соединения пула не переоткрываются"). - Пачка:
- один пользователь
api.register(); - 48 потоков, у каждого свой
Api(str(api.client.base_url), timeout=15); - один
GET /users/meдоthreading.Barrierи 4 после; - все ответы 200 (
assert_ok(…, 200, "User")).
- один пользователь
- Прогрев: один
GET /users/meкtight_api, затем 2 пачки. - Калибровка:
s1 = int(stand("db-sessions")),s2 = int(stand("db-sessions"));s2 - s1 == 1, иначе сообщение «stand is noisy: …». - Проверка: 3 пачки, затем
s3;s3 - s2 == 1, иначе сообщение с числом новых сессий за пачки. - Клиенты потоков закрываются.
Проверка — 3.6.
- Маркер
-
3.4 Основной спек
openspec/specs/data-storage/spec.md: блок требования «Ограниченный пул соединений и таймауты» заменить текстом из дельтыspecs/data-storage/spec.mdэтого change, через Edit. Иначе сверка покрытия не найдёт сценарий маркера. Остальные дельты — при archive. Проверка:openspec validate data-storage --type spec --strictпроходит,grep -n "не переоткрываются" openspec/specs/data-storage/spec.mdнаходит сценарий. -
3.5
make lint,make check, затем коммит Xperf: keep a fixed PostgreSQL pool without overflow connections:src/config/settings.py,config_example.toml,docker-compose.yml;student-tests/fault_hook.py,student-tests/test_failures.py;.claude/rules/student-tests.md,openspec/specs/data-storage/spec.md.
Проверка:
git show --stat HEAD -- src— один файлsrc/config/settings.py; дерево чистое. Hash X — в журнал этапа. -
3.6 Красный и зелёный тест на коммите X. Выводы — в
<scratchpad>/scaling-improvement/redgreen.log.max_overflow = 5в рабочемconfig.toml(его монтирует обычный API стенда отказов), затемmake failure_checks FAULT_ARGS='-k pool_keeps_connections'— тест красный, в сообщении — число новых сессий больше 0.max_overflow = 0, тот же запуск — зелёный.- Полный
make failure_checks— все проверки отказов прошли (на одну больше, чем вevidence/tests/scaling-bench-checks.md).
Красный не воспроизвёлся — поднять число потоков до 64–96 (новый коммит теста). Не воспроизвёлся и так — остановиться и сообщить основной сессии; тест не ослаблять.
-
3.7 Регрессия на коммите X (выводы — в
<scratchpad>/scaling-improvement/regression.log):make down, затемmake run_docker: смонтированныйconfig.tomlправился, контейнеры нужно пересоздать;make lb_stats— обе репликиUP;make test—PASS;make student_test— без падений, сверка покрытия видит новый сценарий;make instances— две реплики;- соединений приложения после
make student_test— не больше 2 × 10:printf "SELECT count(*) FROM pg_stat_activity WHERE application_name = 'mtusi-messenger';\n" | docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAt'; make test_isolated—PASSи набор без падений;make test-persistence ACTION_SCRIPT=scripts/restart.sh—PASS;make test-failover ACTION_SCRIPT=scripts/stop-one.shдля каждой из двух реплик (make replicasи сдвиг очереди одним запросом между прогонами,balancer.md) —PASS; в концеmake replicas.
Нашёлся дефект — разбор и исправление отдельным коммитом X2 до R. Тогда R откатывает X и X2 вместе (4.1), а
REAPPLYвозвращает оба.
4. Откат R
-
4.1
git revert --no-commit <X> [<X2>], затемgit commit -m "revert: measure scaling-improvement baseline without the pool change" -m "This reverts commit <X>." -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>". Проверка:git diff --stat <X>^ HEAD -- src Dockerfile pyproject.toml uv.lock .dockerignore .python-versionпуст (код «до»);git status --porcelainпуст;- hash R — в журнал этапа.
Рабочий
config.tomlостаётся с0: стендbench/его не читает, а рабочий стенд на время замеров остановлен.
5. A/A на коде «до»
-
5.1 Проверка хоста (шапка задач).
vm_stat | grep Swapouts— «до». -
5.2 `nohup make bench_scaling SERIES=db4 SCALING_LABEL=scaling-db-aa
/scaling-improvement/aa.log 2>&1 &
, около 25 мин (db4— только4x1-pg0.5и4x1-pg2, решение пользователя сократить замеры; design, решение 3, «Изменено в apply»; профильscaling_db4добавлен вbench/run.pyи коммит до A/A). Ожидание циклами, ход —tailжурнала. После —Swapouts` «после». Проверка:evidence/bench/scaling-db-aa/meta.json:status: complete,git.dirty: false,host_warningsпуст;- 6 ячеек, без
generator_bound; meta.git.commitметки = R.
Прервалась — разбор причины, затем
make bench_scaling SERIES=db4 SCALING_LABEL=scaling-db-aa RESUME=1. -
5.3 Коммит только метки:
git add evidence/bench/scaling-db-aa,docs: add scaling db A/A label for scaling-improvement. Проверка:git status --porcelainпуст;git diff --stat <R> HEAD -- src Dockerfile pyproject.toml uv.lockпуст: код A/A и будущей метки «до» — код R.
6. «До» и «после»: make bench_ab
-
6.1 Проверка хоста (шапка задач),
Swapouts«до». Затем:uv run python bench/ab.py --before scaling-db-before --after scaling-db-nooverflow --reapply <R> --series db4 --dry-runпечатает 5 шагов: серия,git add,git commit,git revert, серия;nohup make bench_ab BEFORE=scaling-db-before AFTER=scaling-db-nooverflow REAPPLY=<R> SERIES=db4 > <scratchpad>/scaling-improvement/ab.log 2>&1 &, около 50 мин.
Ожидание — циклами по 30 мин, но по процессу
ab.py:run.pyмежду двумя сериями ненадолго пропадает. Цикл:until ! pgrep -f "[b]ench/ab.py" >/dev/null. Проверка: в журналеbench_ab done; вgit log— коммитdocs: add scaling-db-before bench evidenceи коммитRevert "revert: …". -
6.2
Swapouts«после». Коммит метки «после»:git add evidence/bench/scaling-db-nooverflow,docs: add scaling-db-nooverflow label. Проверка:- обе метки
complete,dirty: false,host_warningsпуст, 6 ячеек, безgenerator_bound; meta.git.commitметкиscaling-db-before= коммит метки A/A (5.3);git diff --stat <commit «до»> <commit «после»> -- src Dockerfile pyproject.toml uv.lock— толькоsrc/config/settings.py.
Сбой шага:
ab.pyназвал шаг. Серию продолжитьRESUME=1на том же commit, оставшиеся шаги — вручную, как печатает--dry-run(решение 4). - обе метки
7. Сравнения и критерий
-
7.1 Три сравнения, все с
CHANGE=scaling-improvement:make bench_compare BEFORE=scaling-db-before AFTER=scaling-db-nooverflow AA=scaling-db-aa— «до/после» с шумом;make bench_compare BEFORE=scaling-db-aa AFTER=scaling-db-before— таблица A/A;make bench_compare BEFORE=scaling-db AFTER=scaling-db-before— тот же код в другой сессии.
Проверка: три файла в
evidence/compare/, в шапке —scaling-improvement; у «до/после» — уровень шума, вывод по каждой конфигурации и раздел PostgreSQL. -
7.2 Критерий «подтверждено» по решению 5, только числами из таблиц 7.1:
4x1-pg0.5— «эффект» и медиана после / до ≥ 1,118;- механизм: «после» новых сессий ≤ 10 на R* и первой нарушившей, соединений на R* ≤ 40; «до» на первой нарушившей — ≥ 40 сессий;
- дрейфа нет: CPU реплик на запрос на 500/с у
4x1-pg0.5и4x1-pg2— ±5 %, шум A/A меньше двух ступеней.
Ещё: контроль
4x1-pg2,lb_chkdownиerror_codesметки «после» на R* и ниже (решение 2); R*(4 × 1) «после» против R*(2 × 1) = 1 101 меткиscaling-db— только справка (другая сессия).Итог — «подтверждено» или «не подтверждено» с причиной — в журнал для 9.1 и 10.1. Не подтверждено — путь решения 5:
- X остаётся или откатывается новым коммитом по правилу решения 5;
- отчёт — с отрицательным результатом;
- после 9–10 — остановка и вопрос основной сессии о запасном кандидате (решение 6).
Дрейф (не выполнен пункт 3) — сразу вопрос основной сессии.
8. Регрессия на итоговом коде и цена соединения
-
8.1 Рабочий стенд на итоговом коде:
make run_docker,make lb_stats— обе репликиUP,make test—PASS. -
8.2 Цена соединения и пинга на итоговом коде. Скрипты пробы propose:
<scratchpad>/scaling-improvement/probe_conn.py(в реплике: режимыping,noping,fresh) иprobe_conn_run.py(хост: CPU cgroup PostgreSQL до и после режима, вычет фона). Нет их — написать заново по design, Context, п. 3.Запуск:
python3 -I <scratchpad>/scaling-improvement/probe_conn_run.py <контейнер api> <контейнер postgres>против рабочего стенда.Проверка: порядок величин как в design — новое соединение ≈ 11 мс CPU реплики и ≈ 2,4 мс PostgreSQL, пинг ≈ 110–140 и 40–45 мкс на выдачу. Разошлось больше чем вдвое — разобраться до 9.1.
-
8.3 Регрессия стенда
bench/на итоговом коде, фоном одной цепочкой:make bench_quick && make bench_restore_quick && make bench_failover_quick && make bench_rollout_quick && make bench_scaling_quick. Проверка: все с кодом 0, меткиquick-*— в.gitignore. Рабочий стенд может работать: это самопроверки, без проверки хоста.
9. Evidence
-
9.1
evidence/storage/connection-cost.md:- шапка: спек
data-storage, change, дата, commit, стенд, хост; - команда, текст
probe_conn.pyи процедура хоста; - вывод 8.2 и как его читать: новое соединение против запроса из пула; пинг — 3 обмена и лишняя транзакция; SCRAM в event loop.
evidence/tests/scaling-improvement-checks.md:- шапка: спеки трёх дельт, change, даты, хэши (инструменты, H4, X,
R, метка A/A, «до», возврат, «после»), стенд, хост
(
docker version,docker info); - пробы propose — таблица из design, «в git не идут»;
- самопроверка
compare.py(1.5); - «Пул по умолчанию» (3.1);
- красный и зелёный тест (3.6), регрессия (3.7);
- проверки хоста и
Swapoutsдо и после A/A иmake bench_ab; - проверки по git (5.2, 6.2);
- итог критерия (7.2);
- регрессия быстрых профилей (8.3).
Без секретов и абсолютных путей домашнего каталога. Проверка:
grep -nE "/Users/|PASSWORD=|Bearer [A-Za-z0-9_-]{20,}" evidence/storage/connection-cost.md evidence/tests/scaling-improvement-checks.mdничего не находит.token_hashв тексте скрипта пробы — имя параметра, не секрет. - шапка: спек
-
9.2 Коммит evidence:
docs: add scaling-improvement comparisons, connection cost and checks(файлы 7.1 и 9.1). Проверка: дерево чистое.
10. Отчёт и документы
-
10.1
REPORT.md:- Подраздел «Подтверждённое улучшение: пул без переполнения
(change
scaling-improvement)» в разделе трека 1 — по требованию «Сравнение „до/после“ в отчёте» (дельтаload-benchmark):- как искали: серия
db,db_sessions_new, исходники, цена соединения —evidence/storage/connection-cost.md, проба; - почему был 10 + 5: design архива
2026-10-01-postgres-storage, решение 5, «ограниченный пул (уровень 4)»; цену переполнения и соединения тогда не мерили; - что изменено и что сохраняется: 503, рестарт PostgreSQL, 53300;
- H4 с итогом;
- методика: три метки, A/A, порог двух ступеней, контроль и детектор дрейфа;
- таблица «до/после» и таблица PostgreSQL — из
evidence/compare/scaling-db-before__scaling-db-nooverflow.md; - почему сработало и что осталось узким местом: насыщенная база ~450 мкс на запрос, хост на дефолтах;
- ограничения.
- как искали: серия
- Таблица доказательств — строка «„5“, трек 1: одно подтверждённое улучшение» с командами и файлами.
- «Архитектура». Расчёт соединений: 2 × 10 + 1 = 21, при замене 3 × 10 + 1 = 31.
- «Ограничения и следующие шаги»:
- граница пула k = 10;
- пункт «Улучшение по найденному узкому месту» — результатом;
- пинг при выдаче — найденный, измеренный, не применённый кандидат. Цифры — из 8.2 и проб; в design лабы 2 он записан как «один короткий round trip».
Проверка: у каждой новой строки есть команда, наблюдение и файл; числа — из таблиц команд и файлов меток.
- Подраздел «Подтверждённое улучшение: пул без переполнения
(change
-
10.2 Правила и
AGENTS.md:infra.md, пункт о пуле: постоянный набор 10 + 0 и почему, расчётAPI_REPLICAS × pool_size,/health/readyв той же очереди;bench.md: меткиscaling-db-aa,-before,-nooverflowв разделе серий;AGENTS.md:- «Переходное состояние»: снять пункт про
scaling-improvement; - таблица команд:
CHANGEуmake bench_compare; - карта кода:
evidence/storage/connection-cost.mdв строкеevidence/storage/.
- «Переходное состояние»: снять пункт про
Проверка:
grep -n "scaling-improvement" AGENTS.md— нет обещаний «впереди». -
10.3 Финал:
make lint,openspec validate scaling-improvement --strict;- задачи отмечены;
- коммит
docs: report confirmed pool improvement for track 1(или… pool improvement result, если не подтвердилось); graphify update .;- рабочий стенд
mtusi-lab3поднят,make lb_stats— обе репликиUP.
Проверка: дерево чистое.