Files
qrtx c1fec73ccc perf(bench): add scaling experiments and saturation diagnostics
Compare API and PostgreSQL CPU budgets and connection pool limits. Collect repeatable measurements and generate report aggregates and graphs.
2026-10-29 11:49:51 +03:00

109 lines
8.9 KiB
Markdown

# Диагностическая серия масштабирования
Из корня репозитория, при работающем Docker и собранном образе API:
```powershell
python -X utf8 scripts/run-scaling-diagnostics.py --client container --output .artifacts/scaling/diagnostics-r100
```
Значения по умолчанию: профили one/two/four, только 100 запланированных
запросов/с, три повтора на профиль, 15 с прогрева и 60 с измерения, 80% чтений истории и 20%
записей. Пул берётся из Compose: по умолчанию 15 на реплику для one/two,
8 для four; фактические значения сохраняются в `manifest.json`.
В каждом прогоне — новый чат и 30 исходных
сообщений. Всего 9 прогонов: 11 минут 15 секунд прогрева и измерений плюс время запуска
контейнеров и сбора данных (ориентировочно около 15 минут, не жёсткий тайм-аут). Меньшие нагрузки
по умолчанию исключены; при необходимости их можно явно задать через `--rates`.
Нагрузка для профиля перестаёт повышаться, если минимум в двух из трёх повторов
встречается один из признаков: больше 5% слотов пропущено из-за опоздания генератора,
больше 5% пропущено из-за лимита одновременно выполняемых запросов, больше 1% ошибок
среди отправленных запросов или p95 успешных ответов превышает 1000 мс. Это границы
эксперимента, а не установленный SLA и не доказательство насыщения сервера.
Для полной матрицы всех запрошенных ступеней добавьте `--full-matrix`. Тогда
превышения порогов записываются в `threshold_crossings` и не прерывают профиль.
Точки с большими пропусками генератора не доказывают максимальную ёмкость API.
Ошибки запуска, отсутствие результата или неполные диагностические данные всё
ещё останавливают серию с восстановлением обычного профиля two.
Сбор инструментированного пула включается только через `test/compose.diagnostics.yaml`.
Preload сохраняет callback/Promise-интерфейсы pg.Pool и раз в секунду пишет
`/tmp/scaling-pool.jsonl` внутри API. Очередь и занятые соединения наблюдаются каждые
100 мс; краткие очереди могут не попасть в выборку, поэтому дополнительно измеряется
время каждого получения соединения. Оно включает создание новых соединений и
задержки event loop, а не только ожидание очереди. Cчётчики приобретений накопительные,
max-показатели относятся к интервалу записи.
PostgreSQL, Nginx и Redis наблюдаются через один постоянный docker exec на сервис
с паузой 2 с между выборками. Наблюдатель версии 3 выполняет SQL через одно
постоянное psql-соединение (`\watch 2`); результат находится в `postgres-sql.jsonl`.
Сохраняются cgroup CPU/memory, ожидания активных
запросов PostgreSQL, число простаивающих транзакций, состав upstream Nginx и события
reload. Тексты SQL, токены, пароли и сообщения не записываются. Наблюдатели потребляют
часть ресурсов тех же контейнеров; это одинаковая методика для всех профилей.
В каталоге прогона:
- `benchmark.json`: исходные HTTP-замеры и границы измеряемого окна в epoch ms;
- `api-*.jsonl`: пул, event loop и cgroup API (включают также прогрев и предыдущие
повторы того же профиля; summary выбирает только текущее измеряемое окно);
- `postgres/nginx/redis.jsonl`: наблюдения остальных сервисов;
- `postgres-sql.jsonl`: SQL-снимки постоянного psql-наблюдателя версии 3;
- `*.stderr`, `nginx-events.log`: ошибки наблюдателей и события Nginx;
- `summary.json`: показатели в измеряемом окне; скорости CPU рассчитаны из
приращений счётчиков, память — максимум по выборкам;
- `execution.json`: команда и временные границы прогона.
`manifest.json` в корне фиксирует настройки, причины остановки нагрузки, ID образов,
хеши сборщиков, окружение Docker и лимиты контейнеров. После завершения или исключения runner восстанавливает профиль
two без диагностического preload. При принудительном завершении процесса это можно
сделать вручную:
```powershell
docker compose -f compose.yaml -f configs/two.yaml up -d --no-build --no-deps --wait api
```
Проверки сборщика:
```powershell
node --test test/pool-diagnostics.mjs test/benchmark-scaling.mjs
python -X utf8 test/diagnostic-summary.py
```
Для отдельной проверки влияния Windows-клиента и публикации порта можно запустить
тот же генератор в Linux-контейнере:
```powershell
python -X utf8 scripts/run-scaling-diagnostics.py --client container --rates 100 --repetitions 3 --output .artifacts/scaling/diagnostics-linux-client-r100
```
Клиент использует тот же собранный образ (только Node и benchmark-скрипт), не имеет
лимита CPU/RAM и обращается к `http://nginx` по сети Compose. Это другой путь HTTP:
без Windows port forwarding, но с конкуренцией за ресурсы той же Docker VM. Такой
контроль помогает проверить влияние клиентского пути, но не заменяет внешний
генератор на отдельной машине. Не запускайте его одновременно с основной серией.
После нагрузки можно оценить накладные расходы наблюдателя PostgreSQL на простое:
```powershell
python -X utf8 scripts/calibrate-scaling-observer.py --output .artifacts/scaling/observer-calibration
```
Выполняются три фазы по 30 с: без наблюдателя, с наблюдателем и снова без него.
Это оценка собственных расходов сборщика, а не поправочный коэффициент к нагрузке.
После завершения серии соберите таблицу и графики. Matplotlib можно запустить
через временное окружение uv, не меняя зависимости API:
```powershell
python -X utf8 scripts/summarize-scaling-diagnostics.py .artifacts/scaling/diagnostics-pg1cpu-full-20261028
uv run --no-project --with "matplotlib>=3.9,<4" python scripts/plot-scaling-diagnostics.py .artifacts/scaling/diagnostics-pg1cpu-full-20261028
```
Графики `performance`, `resources`, `delivered-load` сохраняются в PNG и SVG.
Линии показывают медианы повторов, затенение — диапазон min/max, а не доверительный
интервал. Отдельный график задержек и ошибок по фактически отправленным RPS помогает
учесть пропуски генератора. Превышение номинальной нагрузки не означает, что сервер
фактически получил столько запросов.