Files
mtusi2026lab3/openspec/changes/scaling-improvement/design.md
T
2026-10-11 13:19:56 +03:00

45 KiB
Raw Blame History

Design

Context

Мотивация — proposal.md, «Why». Что требуется — дельты data-storage, service-configuration, load-benchmark. Стенд и порядок замеров — .claude/rules/bench.md («Серии трека 1», «Измеренное состояние — commit», «Сравнение меток»), пул и engine — infra.md. Найденное сериями — REPORT.md, «Цена масштабирования (трек 1)», и design архива 2026-10-11-scaling-bench (решение 11, «Найдено в verify»).

Код сейчас — HEAD bbd6f65. Код приложения тот же, что у метки scaling-db: git diff 46e8f75 HEAD -- src Dockerfile pyproject.toml uv.lock пуст.

  • Пул. src/config/settings.py: pool_size 10, max_overflow 5, pool_timeout_seconds 5. Те же 10 и 5 — в config_example.toml и в рабочем config.toml (он не в git). src/infra/db/engine.py передаёт их в create_async_engine с pool_pre_ping=True; пул — AsyncAdaptedQueuePool SQLAlchemy 2.1.1, драйвер asyncpg 0.31.
  • Готовность. /health/ready берёт соединение из того же пула и ждёт его не дольше 2 с (READINESS_DB_TIMEOUT_SECONDS).
  • Стенд bench/ читает настройки приложения только из дефолтов settings.py и окружения override, без config.toml. Окружение приложения пишется в паспорт (stand.app_env), и make bench_compare его сверяет. Пул, заданный окружением, — другая методика: замер «до/после» обязан менять дефолт в коде.
  • Стенд отказов (make failure_checks) поднимает обычный API через docker compose run api. У него смонтирован рабочий config.toml, так что пул — из этого файла. У «тесного» API пул 1 + 0 задан окружением.

Механизм проверен до change — пробы на bbd6f65, не замер для отчёта. Скрипты и журналы лежат в scratchpad сессии (scaling-improvement/probe_conn.py, probe_conn_run.py, probe_series.py, probe*.compose.yml, noping/).

  1. Исходники SQLAlchemy (sqlalchemy/pool/impl.py, QueuePool).

    • Очередь пула вмещает pool_size соединений.
    • _do_return_conn кладёт возвращённое соединение в очередь. Если там уже pool_size простаивающих, соединение закрывается.

    Соединения сверх 10 живут, только пока заняты. При спросе около 10 их открывают и закрывают снова и снова.

  2. Данные серий. db_sessions_new — прирост pg_stat_database.sessions за окно 20 с.

    • На 250 и 500/с у k ≥ 2 — 3–4 сессии, это фон.
    • На R* в scaling-b — от 103 (k = 1) до 283 (k = 6).
    • В scaling-db у 4 × 1 при 0,5 CPU: на R* 931/с — 12–24, на 984/с — 79–144. На 984/с соединений 60, CPU PostgreSQL на запрос 412–496 мкс против 278–292 на 931/с.
  3. Цена соединения — микропроба на рабочем стенде: PostgreSQL 2 CPU, реплика 1 CPU. Итерация — то, что запрос чтения делает с БД: функции repo «проверка сессии» и «страница истории». Итерации идут последовательно. Меряется CPU процесса пробы и cgroup PostgreSQL; прогонов два.

    Итерация CPU реплики, мкс CPU PostgreSQL, мкс
    соединение из пула, пинг при выдаче (как сейчас) 552–590 130–138
    соединение из пула, без пинга 442–454 90–94
    новое соединение на итерацию 11 225–11 318 2 378–2 386

    Новое соединение стоит в ~20 раз дороже запроса из пула.

    • Реплика. Почти всё — SCRAM-SHA-256: asyncpg (protocol/scram.pyx) считает PBKDF2 на 4 096 итераций циклом hmac.new() в потоке event loop. На ~10 мс реплика стоит, а pg_hba образа PostgreSQL — host all all all scram-sha-256.
    • PostgreSQL. Новый процесс, аутентификация и холодный кэш каталога. Подготовленные выражения тоже готовятся заново: их кэш у asyncpg — на соединение.
  4. Пинг при выдаче. Диалект asyncpg (_async_ping) на каждую выдачу соединения шлёт BEGIN, ; и ROLLBACK. В сериях на запрос приходится 0,2 commit и 1,8 rollback; 1,0 из них — транзакция пинга. В пробе без пинга rollback — 0,80.

  5. Проба основной ячейки. Ячейка 4 × 1 при PostgreSQL 0,5 CPU, профиль серии, данные 10 000. Фиксированные уровни 931, 1 041, 1 164 и 1 455/с, затем поиск до 2 ступеней. Один повтор, метки evidence/bench/quick-probe-*-20261011T094150Z (в git не идут). Пул задан окружением через третий файл compose. Вариант без пинга — на образе с копией engine.py.

    Вариант 931 1 041 1 164 подъёмом от 1 041 1 164 с нуля 1 455 R* Новых сессий за окно
    10 + 5 (сейчас) ✓ 282 ✗ 482 ✗ 435 ✗ 458 ✗ 465 (1 074/с) 931 9–52
    10 + 0 ✓ 275 ✓ 299 ✗ 454 ✓ 297 ✗ 456 (1 100/с) 1 164 3–4
    15 + 0 ✓ 281 ✓ 287 ✗ 473 ✗ 422 ✗ 464 (1 076/с) 1 041 4
    10 + 5 без пинга ✓ 231 ✓ 442 ✓ 430 — ✗ 384 (1 303/с) 1 164 9–264

    Как читать:

    • число — CPU PostgreSQL на успешный запрос, мкс;
    • ✓ / ✗ — ступень прошла или нарушила SLO;
    • в скобках — успешных ответов в секунду на перегрузке.

    Проверки LB не провалились ни разу. Ответов 5xx и отказов «too many clients» нет ни в одном варианте: ошибки SLO на перегрузке — это недосланные генератором запросы.

    Что видно:

    • Переоткрытие пропадает. Без переполнения новых сессий за окно — фон (3–4) на всех ступенях.
    • Излом сдвигается. 10 + 0 держит CPU PostgreSQL ~300 мкс на запрос до 1 164/с. У 10 + 5 он скачет до 482 уже на 1 041/с.
    • Насыщение остаётся. Выше излома PostgreSQL выбирает квоту и тратит ~450 мкс на запрос при любом пуле. Изменение отодвигает момент, когда база туда сваливается, но насыщенную базу дешевле не делает.
    • Бистабильность. 1 164/с подъёмом от 1 041/с за 5 с сваливается в насыщение, а с нуля после паузы проходит. Поиск R* это уже учитывает: после нарушения следующая ступень стартует с нуля с прогревом 15 с.
    • Без пинга база дешевле на ~50 мкс на запрос и держит больше: 1 303 против 1 074/с на перегрузке. Но переоткрытие остаётся — 204–264 новых сессий за окно.

Goals / Non-Goals

Goals:

  • Одно изменение кода приложения на найденном узком месте — пул без переполнения. Подтверждается make bench_ab с A/A того же кода в той же сессии хоста.
  • Механизм — в числах из таблиц команд (новые сессии, соединения и CPU PostgreSQL до и после), а не только в R*.
  • Тест свойства: красный без изменения, зелёный с ним.
  • Ни один вызов инструмента не дольше 10 мин; замеры идут фоном.

Non-Goals:

  • Снятие или удешевление пинга при выдаче. Это запасной кандидат (решение 6).
  • PgBouncer, запись одним SQL, другая аутентификация PostgreSQL (решение 1).
  • Переснимать серии a, b, pool, ab на новом пуле. Их метки остаются результатом 10 + 5.
  • Графики «до/после». plots.py не меняется: db_lines показывает одну метку, а доказательство — таблица сравнения (решение 7).
  • Насыщенная база выше излома. ~450 мкс на запрос под троттлингом CFS — свойство квоты 0,5 CPU, не лечится.

Decisions

1. Улучшение — пул без переполнения

Дефолт [database] max_overflow становится 0, pool_size остаётся 10.

Почему этот кандидат:

  • Бьёт в найденное узкое место. Это там, где серия db показала, что рост реплик вредит: 1 101 → 931/с.
  • Механизм виден трижды: по исходникам, по счётчику сессий, по пробе. Проба даёт R* 931 → 1 164 (+25 %) — больше порога в две ступени.
  • Меняется одно значение по умолчанию. Поведение при отказах прежнее: рестарт PostgreSQL, «too many clients» (53300), истёкшее ожидание пула — те же 503. Контракт не меняется.
  • Свойство проверяется по HTTP с hook стенда отказов (решение 8).
Кандидат Ожидаемый эффект Почему не он
Убрать пинг при выдаче (pool_pre_ping=False) проба: R* 931 → 1 164, CPU PostgreSQL на запрос −19 %, реплики — −110…136 мкс меняет поведение при отказе: после рестарта PostgreSQL запрос на мёртвом соединении получает 503, а спек data-storage («БД вернулась») требует штатного обслуживания; на пинге держится и test_connection_limit_reached. Запасной кандидат — пинг без потери поведения (решение 6)
Запись одним SQL (ключ и сообщение одним CTE) минус один обмен у записи, 20 % смеси: ~0,2 обмена на запрос против 3 у пинга < 2 % CPU — ниже шага сетки (5,7 %)
PgBouncer в transaction-режиме меньше процессов PostgreSQL при любом числе реплик новый компонент — смена методики (своя пара меток и A/A, bench.md); подготовленные выражения asyncpg в этом режиме требуют своей настройки
uvloop / httptools — уже включены (design scaling-bench, Context)
Дешевле SCRAM: scram_iterations (PostgreSQL 16+), md5 или trust нет 10 мс реплики на соединение ослабляет хранение пароля (лаба 7 — защита). Пул без переполнения убирает сами переподключения

2. Параметр — 10 + 0

Почему не 15 + 0 и не меньше 10:

  • 15 + 0 в пробе хуже: R* 1 041 против 1 164 у 10 + 0. Это один прогон, довод слабый, но направление то же, что в серии db: у насыщенной базы 60 соединений хуже 40.
  • 10 — тот постоянный набор, который пул держит и сейчас. В scaling-db у 2 и 4 реплик на 250 и 500/с — не больше 10 соединений на реплику (db_conn_replica_max 10, pool_busy_share 0) и только фоновые новые сессии. У них ниже насыщения не меняется ничего; изменение убирает только переполнение — одно изменение. У 1 × 1 на 500/с (75 % её потолка) пул уже доходил до 15, новых сессий — 53–79 за окно: там переоткрытие уходит уже на фиксированном уровне.
  • 15 + 0 держал бы 15 соединений на реплику всегда. Это 60 при 4 репликах и 90 при 6: вместе с миграциями и сэмплером — 92 из 100, без запаса.
  • Меньше 10 (5 + 0, 8 + 0) не пробовали. На R* у 1 × 1 пул доходит до 15: event loop занят, запросы держат соединение, пока ждут его. Меньший пул мог бы душить реплику — риск без данных.

Следствия:

  • Соединения стенда. Не больше 10 на процесс.
    • Рабочий стенд: 2 × 10 + migrate = 21 ≤ 100 (было 31).
    • Поочерёдная замена: 3 × 10 + 1 = 31 (было 46).
    • Стенд bench/: 10k + 1 (сэмплер) ≤ 100, граница пула — k = 10 (было 7).
  • H3 проверялась на 10 + 5: 4 реплики при max_connections 50 — 61 > 50. С 10 + 0 тот же опыт даёт 41 < 50, и отказов не будет. Метка scaling-pool остаётся результатом старого дефолта. Отчёт называет новую границу, серия pool не переснимается.
  • Ожидание в пуле. 11-й одновременный запрос ждёт в очереди пула (FIFO) не дольше pool_timeout 5 с, затем 503 unavailable — как раньше, когда были заняты все 15.
    • На фиксированных уровнях и на R* ожидания нет или оно короткое: в пробе pool_busy_share 0 на 931, 1 041 и 1 164/с с нуля; 0,15–0,3 — только выше R*.
    • Новых 503 на фиксированных уровнях и на R* не ждём. Выше R* срок пула может истекать раньше, чем при 15. Это видно в error_codes метки и на R* не влияет.
  • Готовность. /health/ready ждёт соединение в той же очереди до 2 с. На перегрузке проверка может не дождаться, и тогда LB исключит реплику после двух неудач. В пробе lb_chkdown 0 на всех ступенях, включая 1 455/с; в A/B он пишется в строку ступени (риски).
  • max_overflow остаётся настройкой (окружение, config.toml). Меняется только значение по умолчанию; пинг при выдаче не меняется.

Где меняется:

  • src/config/settings.py: max_overflow: int = Field(default=0, ge=0) и комментарий «почему 0»;
  • config_example.toml: max_overflow = 0 и одна строка комментария;
  • рабочий config.toml — руками (он не в git);
  • комментарий о соединениях у postgres в docker-compose.yml.

Через окружение compose — нельзя. Стенд bench/ должен видеть дефолт кода, а stand.app_env в паспортах меток — не меняться.

3. Где подтверждаем — серия db целиком

Серия db тем же профилем scaling_db, что у метки scaling-db:

  • 1, 2 и 4 реплики по 1 CPU при PostgreSQL 0,5 CPU;
  • 4 × 1 при 2 CPU;
  • 3 повтора, порядок ячеек тот же (зерно профиля).
Конфигурация Роль До (scaling-db) Ожидание после
4x1-pg0.5 основная: база насыщена, рост реплик вредил 931 (931–931); на 984/с — 60 соединений, 79–144 новых сессий 1 101–1 301
4x1-pg2 контроль: те же 4 реплики и тот же пул, база свободна (0,76 ядра из 2 на R*) 1 627 (1 627–1 627) меньше двух ступеней
2x1-pg0.5 реплики упираются в свой CPU, база — 77 % лимита 1 101 (1 101–1 101) меньше двух ступеней
1x1-pg0.5 одна реплика: переоткрытие на R* — ~5 % её CPU 630 (630–630) меньше двух ступеней

Почему вся серия, а не новый профиль из трёх конфигураций:

  • профиль уже есть: ни кода конфигураций, ни дельты «Серии трека 1»;
  • вся серия даёт R*(k) при насыщенной базе до и после — прямой ответ, перестаёт ли рост реплик вредить;
  • 1 × 1 стоит 3 ячейки по ~4 мин на прогон, ~36 мин на все три прогона. Это приемлемо.

Почему не серия ab (1 × 1 и 6 × 1 при PostgreSQL 2 CPU) — её предлагала рекомендация scaling-bench:

  • при 6 × 1 рост останавливает хост;
  • переоткрытие на R* — 283 сессии за окно, ~14/с × (11,2 мс реплики + 2,4 мс PostgreSQL) ≈ 0,19 ядра из ~8,1 занятых, то есть ~2 %. Это меньше одной ступени (5,7 %), так что подтвердить эффект там нельзя по устройству опыта;
  • её A/A и A/B стоили бы ещё ~66 мин.

То, что на дефолтных лимитах изменение почти ничего не даёт, показывает контроль 4x1-pg2 в той же сессии.

A/A — профиль scaling_db на коде «до», в той же сессии, прямо перед make bench_ab.

Метка scaling-db снята на том же коде приложения, но в другой сессии (2026-10-11, 08:31–09:20). Её сравнение с «до» — дополнительная оценка шума между сессиями, а не AA вердикта: bench.md требует A/A и «до/после» подряд. Контроль 4 × 1 при 2 CPU в разных сессиях уже расходился на две ступени: 1 627 в scaling-db против 1 819 в scaling-b.

Время.

  • Серия db — 49 мин (12 ячеек по ~4 мин). После изменения у 4x1-pg0.5 ступеней поиска больше, +1–2 мин.
  • A/A ~50 мин, make bench_ab ~100 мин — всего ~2,5 ч; с проверками хоста и коммитами — ~2 ч 40 мин.
  • Каждый прогон — фоном (nohup). Ожидание — циклом until ! pgrep -f "[b]ench/run.py", не больше 30 мин на вызов (Monitor или Bash с run_in_background). У make bench_ab ждать конца [b]ench/ab.py: между двумя сериями run.py ненадолго не работает.

4. Порядок коммитов и замеров

Порядок проверен по коду bench/ab.py. Все коммиты, кроме тех, что делает сам ab.py, — со строкой Co-Authored-By брифа.

  1. Инструменты сравнения. feat: compare PostgreSQL sessions and connections in track 1 series (решение 7): bench/scaling.py, bench/compare.py, Makefile, bench.md. Коммит до замеров: все три метки снимаются одним кодом стенда.

  2. H4. docs: record track 1 improvement hypothesis H4 — гипотеза и предсказание в REPORT.md (решение 5). Коммит старше всех меток.

  3. Изменение X. perf: keep a fixed PostgreSQL pool without overflow connections. В коммите:

    • src/config/settings.py, config_example.toml, комментарий docker-compose.yml;
    • тест и действие hook (решение 8);
    • требование data-storage из дельты, перенесённое в основной спек (сверка покрытия читает основные спеки).

    Перед коммитом — make lint и make check. Красный и зелёный тест и регрессия — на коммите X, до R: доказательства снимаются с закоммиченного кода. Найденный дефект — коммит X2, тогда R откатывает X и X2 вместе.

  4. Откат R. git revert --no-commit X, затем git commit с сообщением revert: measure scaling-improvement baseline without the pool change и телом This reverts commit X. (и Co-Authored-By). Проверка: git diff --stat X^ HEAD -- src Dockerfile pyproject.toml uv.lock .dockerignore .python-version пуст.

  5. A/A.

    • Проверка хоста по брифу и make stop.
    • nohup make bench_scaling SERIES=db SCALING_LABEL=scaling-db-aa, ожидание.
    • Проверка метки (задачи) и коммит docs: add scaling db A/A label for scaling-improvement.
  6. «До» и «после».

    • Проверка хоста.
    • nohup make bench_ab BEFORE=scaling-db-before AFTER=scaling-db-nooverflow REAPPLY=<R> SERIES=db.

    ab.py выполняет пять шагов:

    1. серия «до» на HEAD — коммите метки A/A, код R;
    2. git add evidence/bench/scaling-db-before;
    3. коммит docs: add scaling-db-before bench evidence;
    4. git revert --no-edit R — коммит Revert "revert: …", то есть снова код X;
    5. серия «после».

    Метку «после» ab.py не коммитит. Её коммитит агент: docs: add scaling-db-nooverflow label.

  7. Сравнения. make bench_compare BEFORE=scaling-db-before AFTER=scaling-db-nooverflow AA=scaling-db-aa CHANGE=scaling-improvement. Плюс таблица A/A (BEFORE=scaling-db-aa AFTER=scaling-db-before) и шум между сессиями (BEFORE=scaling-db AFTER=scaling-db-before), обе с тем же CHANGE.

  8. Evidence, отчёт и документы — отдельными коммитами.

Что проверяет ab.py (problems()) и чем это выполнено:

  • Каталогов меток нет, BEFORE ≠ AFTER — имена новые.
  • Дерево чистое. Метка A/A закоммичена до запуска. Метки quick-* и пробные сравнения в .gitignore, scratchpad — вне репозитория.
  • REAPPLY — предок HEAD: R в текущей ветке.

Что проверяет агент — этого ab.py не видит:

  • Код A/A = код «до». git diff --stat R <commit метки A/A> -- src Dockerfile pyproject.toml uv.lock пуст, а meta.git.commit метки scaling-db-before равен commit метки A/A.
  • dirty: false у трёх меток. Серия считает чистоту без своего каталога метки. Метки A/A и «до» — на чистом дереве, «после» — на коммите возврата.
  • Между «до» и «после» в src отличается только src/config/settings.py: git diff --stat <commit «до»> <commit «после»> -- src.

Между A/A и make bench_ab — только коммит метки и проверка хоста: ни тестов, ни сборок.

Сбой посреди серии. ab.py останавливается и называет шаг. Метку продолжают make bench_scaling SERIES=db SCALING_LABEL=<метка> RESUME=1 на том же commit; оставшиеся шаги — вручную, ровно как их печатает uv run python bench/ab.py … --dry-run. Хост стал неготов — Telegram и остановка (бриф).

5. H4 и критерий «подтверждено»

H4. Пул без переполнения — текст для REPORT.md до замеров.

  • Утверждение. У насыщенного PostgreSQL рост реплик вредит из-за переполнения пула. Под нагрузкой реплики открывают соединения сверх 10, а каждое новое стоит PostgreSQL ~2,4 мс CPU и реплике ~11 мс. База раньше уходит в троттлинг. Пул без переполнения отодвигает этот излом.
  • Предсказание для 4x1-pg0.5:
    • медиана R* 931 → 1 101–1 301 (+18…+40 %), не меньше двух ступеней (≥ 1 041);
    • новых сессий за окно «после» — не больше 10 и на R*, и на первой нарушившей ступени (фон — 3–4); «до» на первой нарушившей — не меньше 40;
    • соединений на R* «после» — не больше 40;
    • CPU PostgreSQL на запрос на R* «после» — не больше 330 мкс.
  • Предсказание для остальных:
    • у 4x1-pg2, 2x1-pg0.5 и 1x1-pg0.5 |Δ R*| меньше двух ступеней;
    • CPU реплик на запрос на 500/с у 2x1-pg0.5, 4x1-pg0.5 и 4x1-pg2 — в пределах ±5 %: переоткрытия там нет и до изменения;
    • у 1x1-pg0.5 CPU на запрос на 500/с может снизиться на несколько процентов, а p95 и p99 на 500/с — заметнее: переоткрытие у неё было уже там.
  • Предсказание для серии: «после» R*(4 × 1) ≥ R*(2 × 1) при 0,5 CPU — рост реплик перестаёт вредить.
  • Опровергнет — хотя бы одно:
    • у 4x1-pg0.5 разбросы пересекаются, Δ не больше шума A/A или меньше двух ступеней;
    • переоткрытие «после» не исчезло: механизм не тот.

Порог — две ступени сетки, R* «после» / R* «до» ≥ √1,25 ≈ 1,118. Сетка поиска после двух делений — 931, 984, 1 041, 1 101, 1 164 …, шаг 1,25^¼ ≈ 5,7 %. Значит, 931 → 1 041 — ровно две ступени, +11,8 %. В bench.md это округлено до «≥ 12 %», и сдвиг ровно на две ступени формально под порог не попадал бы. Правило уточняется до замеров (задачи), числа не меняются.

Подтверждено, если выполнено всё:

  1. У 4x1-pg0.5 вывод make bench_compare … AA=scaling-db-aa — «эффект», и медиана «после» ≥ медиана «до» × 1,118.
  2. Механизм — по таблице «PostgreSQL на R* и первой нарушившей ступени»:
    • «после» новых сессий за окно ≤ 10 на обеих ступенях;
    • соединений на R* ≤ 40;
    • «до» на первой нарушившей — ≥ 40 новых сессий.
  3. Дрейфа сессии нет:
    • CPU реплик на запрос на 500/с — в пределах ±5 % у 2x1-pg0.5, 4x1-pg0.5 и 4x1-pg2 (у 1x1-pg0.5 изменение само его снижает);
    • шум A/A меньше двух ступеней.

Если контроль 4x1-pg2 сдвинулся на две ступени и больше, а пункт 3 выполнен, эффект основной ячейки засчитывается. Предсказание для контроля тогда опровергнуто, и отчёт объясняет его таблицей PostgreSQL (у контроля «до» на R* — ~220 новых сессий за окно). Если не выполнен пункт 3, это дрейф сессии хоста: не засчитывается ничего, а переснимать ли — решает основная сессия.

Не подтвердилось:

  • в отчёте — честный отрицательный результат: H4 опровергнута, числа — из таблиц;
  • X остаётся, если ни одна конфигурация не стала хуже на две ступени и больше: переподключения и задержки event loop по ~10 мс всё равно уходят;
  • если какая-то стала хуже — X откатывается новым коммитом (git revert), и это тоже пишется;
  • затем остановка и вопрос основной сессии о запасном кандидате (решение 6): он добавляет ~2,5 ч и меняет engine.

6. Запасной кандидат — пинг только после простоя

Что. pool_pre_ping заменяется проверкой соединения, которое простаивало ≥ 1 с:

  • событие пула checkout: run_async(lambda c: c.fetchrow(";")), без транзакции; при ошибке — DisconnectionError и новое соединение;
  • время простоя пишет событие checkin в connection_record.info.

Почему так. Под нагрузкой соединение возвращается и выдаётся снова через миллисекунды, и 3 обмена и лишняя транзакция на запрос исчезают. После рестарта PostgreSQL каждое соединение пула простояло дольше рестарта, так что его проверят, и поведение «БД вернулась» сохраняется. Так же работает aliveBypassWindowMs (500 мс) у HikariCP.

Ожидание — как у пробы без пинга: R* 931 → 1 164 у 4x1-pg0.5, минус 110–136 мкс CPU реплики и 40–44 мкс CPU PostgreSQL на запрос.

Цена:

  • код и тесты fault («БД вернулась», 53300) — ~45 мин;
  • make bench_ab SERIES=db — ~100 мин;
  • A/A scaling-db-aa годится, если код «до» совпадает с её кодом (X откачен); иначе новая A/A, ещё ~50 мин.

Итого 2,5–3,5 ч. Запускать или нет, решает основная сессия.

В отчёте при любом исходе пинг — найденный и измеренный, но не применённый кандидат: микропроба, проба основной ячейки и причина, по которой он не применён.

7. Сравнение серий показывает механизм

  • bench/scaling.py, config_stats. По каждой конфигурации — медианы по завершённым ячейкам на ступени R* (step_at) и на ближайшей нарушившей выше неё (fail_step): уровень первой нарушившей, db_us_per_request, db_sessions_new, db_conn_max. Имена полей — в стиле существующих (db_cpu_r).
  • bench/compare.py, render_series. После таблицы «R* по общим конфигурациям» — раздел «PostgreSQL на R* и первой нарушившей ступени». Строка — конфигурация × ступень, столбцы «до → после»: уровень, CPU PostgreSQL на запрос (мкс), новых сессий за окно, соединений PostgreSQL.
  • Шапка. Параметр --change (по умолчанию scaling-bench) попадает в строку шапки серии «Спек … change …». Makefile передаёт его как $(if $(CHANGE),--change "$(CHANGE)"). Сравнение матрицы не меняется.
  • Прежние файлы evidence/compare/ не пересоздаются: в них добавился бы раздел. Они остаются выводом своих commit.
  • Самопроверка:
    • метка сама с собой: BEFORE=AFTER=scaling-db с CHANGE — Δ 0, в новом разделе одинаковые значения (у 4x1-pg0.5 первая нарушившая — 984/с). Файл не отслеживается и удаляется;
    • пробная метка сама с собой — вывод в .gitignore;
    • две пробные метки с разным пулом → отказ «разная методика» (stand.app_env). Это верно и подтверждает решение 2: пул меняется в коде, а не окружением.

Почему compare.py, а не plots.py. Файл сравнения — главное доказательство «до/после» и должен быть самодостаточен. db_lines у plots.py показывает одну метку.

8. Проверка свойства тестом

Действие hook db-sessions (student-tests/fault_hook.py): SELECT sessions FROM pg_stat_database WHERE datname = current_database() через существующий psql. Строка в docstring hook и в student-tests.md.

Тест test_pool_keeps_connections (student-tests/test_failures.py, маркер fault, @pytest.mark.spec("data-storage", "Соединения пула не переоткрываются")) — на обычном API:

  • Пачка.
    • 48 потоков, у каждого свой Api (keep-alive).
    • Каждый поток делает один запрос GET /users/me до threading.Barrier и 4 после него. Пользователь один.
    • Все ответы — 200. Пачка — 192 запроса, около 48 одновременно, при пуле 10.
  • Прогрев. Один запрос к «тесному» API: его соединение могли оборвать прежние тесты (fill-connections), и переподключение не должно попасть в окно. Затем 2 пачки: пул набирает свой размер.
  • Калибровка. s1 = stand("db-sessions"), сразу s2 = stand("db-sessions"). Должно быть s2 − s1 == 1: это сессия самого первого вызова hook, которую PostgreSQL учитывает к её концу. Иначе стенд шумит, и тест падает с этим сообщением.
  • Проверка. 3 пачки, затем s3 = stand("db-sessions"). Должно быть s3 − s2 == 1; иначе тест падает с числом новых сессий за пачки.

Почему счётчик, а не список соединений. При 10 + 5 лишние соединения закрываются до снимка pg_stat_activity, а оставшиеся 10 могут оказаться прежними — снимок переоткрытие пропустит. Накопительный счётчик его видит: новый backend сообщает о себе в конце первой транзакции или при выходе. Проверки PostgreSQL (pg_isready) аутентификацию не проходят и сессий не добавляют.

Красный и зелёный.

  • Красный: max_overflow = 5 в рабочем config.toml (стенд отказов монтирует его) и make failure_checks FAULT_ARGS='-k pool_keeps_connections'.
  • Зелёный: max_overflow = 0.
  • Не краснеет — поднять число потоков до 64–96. Не краснеет и так — остановиться и сообщить; тест не ослаблять.

Сверка покрытия. Требование data-storage из дельты переносится в основной спек в том же коммите X — тем же текстом (как задача 9.1 scaling-bench). Остальные дельты — при archive.

«Пул по умолчанию» (service-configuration в сверку покрытия не входит) проверяется командой uv run python -c "from src.config.settings import Database; d = Database(); print(d.pool_size, d.max_overflow)" → 10 0. Вывод идёт в evidence.

9. Документы, evidence и отчёт

Правила:

  • infra.md, пункт о пуле:
    • постоянный набор 10 + 0 и почему (переоткрытие, цена соединения);
    • расчёт API_REPLICAS × pool_size;
    • /health/ready ждёт в той же очереди.
  • bench.md:
    • раздел сравнения: таблица PostgreSQL, CHANGE;
    • порог двух ступеней — ×1,118;
    • пул метки — дефолт кода, а не окружение стенда;
    • метки этого change.

Evidence:

  • метки evidence/bench/scaling-db-aa/, scaling-db-before/, scaling-db-nooverflow/;

  • evidence/compare/scaling-db-before__scaling-db-nooverflow.md (с AA), scaling-db-aa__scaling-db-before.md, scaling-db__scaling-db-before.md;

  • evidence/storage/connection-cost.md — микропроба на итоговом коде (стенд, команда, текст скрипта, вывод);

  • evidence/tests/scaling-improvement-checks.md:

    • красный и зелёный тест, регрессия;
    • «Пул по умолчанию»;
    • самопроверка compare.py;
    • проверки хоста и Swapouts до и после каждого прогона;
    • проверки по git (код A/A = «до», «до» → «после» — один файл).

    Шапка — по брифу: спеки, change, дата, commit, стенд, хост.

REPORT.md:

  • H4 — до замеров.
  • Подраздел «Подтверждённое улучшение: пул без переполнения» в разделе трека 1 — по требованию «Сравнение „до/после“ в отчёте», числа из таблиц.
  • Строка таблицы доказательств «5», трек 1: одно подтверждённое улучшение.
  • Расчёт соединений в «Архитектуре»: 2 × 10 + 1, при замене 3 × 10 + 1.
  • В «Ограничениях» — граница пула (k = 10), а пункт «Улучшение по найденному узкому месту» заменить результатом.
  • Пинг при выдаче — найденный, измеренный, не применённый кандидат.
  • SCRAM asyncpg в event loop — цена нового соединения.

Прочее: AGENTS.md — «Переходное состояние» и CHANGE у make bench_compare. PLAN.md — при archive.

Risks / Trade-offs

  • [Бистабильность у излома: 1 164/с то проходит, то нет] → три повтора, а поиск после нарушения стартует с нуля. Критерий — медиана и две ступени, в предсказании названа нижняя граница (1 041).
  • [Дрейф между сессиями] (контроль 1 627 против 1 819 в разных сессиях) → A/A и «до/после» подряд. Детектор дрейфа — CPU реплик на запрос на 500/с у конфигураций с 2 и 4 репликами; контроль 4x1-pg2 — в той же серии.
  • [Меньший потолок соединений душит реплики, упёртые в свой CPU] → 10 — тот же постоянный набор, что и сейчас. Есть контрольные конфигурации, а в метке «после» видны pool_busy_share и error_codes.
  • [/health/ready ждёт в очереди пула, и LB исключает реплику на перегрузке] → в пробе 0, в A/B смотрим lb_chkdown.
    • Только выше R* — побочный эффект, он идёт в отчёт.
    • На R* и ниже — изменение не засчитывается: оно ломает отказоустойчивость. Вопрос основной сессии.
  • [Тест не краснеет на 10 + 5] → больше потоков; не помогло — остановка и отчёт, тест не ослабляется.
  • [Рабочий config.toml остаётся 10 + 5] → правка руками и пересоздание контейнеров: файл смонтирован, и замена inode не видна работающему контейнеру. Новые клоны получают шаблон.
  • [Опыт серии pool (H3) на новом дефолте не воспроизведётся] → метка scaling-pool остаётся результатом 10 + 5, отчёт называет новую границу k = 10.
  • [Эффект — только при узком лимите PostgreSQL] → так и пишется. На дефолтных лимитах рост останавливает хост, и улучшение его почти не касается; это показывает контроль 4x1-pg2.
  • [ab.py коммитит без Co-Authored-By] → это поведение цели проекта, исключение брифа.
  • [Прогоны идут ~2,5 ч] → nohup, ожидание до 30 мин на вызов, RESUME=1, проверка хоста перед A/A и перед make bench_ab.

Migration Plan

Порядок — решение 4 и tasks.md:

  1. инструменты сравнения;
  2. H4;
  3. X с тестом и регрессией;
  4. R;
  5. A/A;
  6. make bench_ab;
  7. сравнения и критерий;
  8. регрессия на итоговом коде и цена соединения: рабочий стенд с новым config.toml, быстрые профили стенда bench/;
  9. evidence;
  10. отчёт и документы.

Откат. git revert коммита X: дефолт снова 5. В рабочем config.toml значение возвращается руками. Метки остаются в evidence/ как результат своих commit.