Files
mtusi2026lab3/bench/AGENTS.md
T

18 KiB
Raw Blame History

bench/ — нагрузочный стенд лабы 3

Нужен для трёх вещей из README.md:

  • уровень «4»: поочерёдный отказ каждой реплики под нагрузкой — RPS, ошибки, время восстановления (профиль failover);
  • уровень «4»: поочерёдная замена (rolling update) под нагрузкой, миграция однократно и совместима с работающей версией (профиль rollout);
  • уровень «5», трек 1 «Цена масштабирования»: серии конфигураций реплик и лимитов, точка насыщения, одно подтверждённое улучшение (scaling).

Порядок работы по шагам — bench/RUNBOOK.md. Здесь — правила, которые действуют на каждом шаге. Стенд лабы 2 (матрица 10k/100k/500k, EXPLAIN, восстановление из backup) и его метки остались в репозитории лабы 2: другая задача и другая методика, их числа сюда не переносятся.

Что есть

Файл Команда Что делает
run.py make bench-failover, bench-rollout, bench-scaling SERIES=…, *-quick оркестратор: стенд, профили, файлы метки
common.py — docker, стенд compose vlad-bench, паспорт, хост, бюджет, контекст «нового» образа для rollout
analysis.py uv run python bench/analysis.py --selftest разбор без docker: журналы запросов, события Docker, журнал HAProxy, агрегаты сэмплера, признаки узкого места (THRESHOLDS), автомат поиска R* (Search)
loadgen.py — (его вызывает run.py через docker exec) генератор на stdlib: открытая модель, несколько процессов; setup, step (ступень смеси), constant (постоянная интенсивность с журналом каждого запроса), retry (повтор неуспешных записей с тем же ключом)
sampler.py — (контейнер vlad-bench-sampler) раз в секунду: cgroup каждого контейнера (CPU, троттлинг, память), CPU ВМ; в режиме list ещё статистика HAProxy и pg_stat_activity / pg_stat_database
compare.py make bench-compare BEFORE= AFTER= [AA=] «до/после» серий по общим конфигурациям, шум A/A, вывод «эффект / шум / в пределах разрешения»
plots.py make bench-plots LABELS="…" [PLOTS=…] SVG: R* по конфигурациям, R* от числа реплик с линией линейного роста, сводка и точка насыщения
bench.compose.yml, bench.env — override стенда: имена, лимиты BENCH_*, реплики, без портов, без swap

Профили и серии (поля — PROFILES и SERIES в run.py, целиком в meta.json):

Профиль / серия Что Время
failover 2 реплики с лимитами рабочего стенда, 100 записей с ключом + 100 чтений/с; каждая реплика в режимах stop, kill, pause с возвратом (6 фаз) ~6 мин
rollout та же нагрузка; scripts/rolling-update.sh меняет обе реплики на образ с expand-ревизией 9001_rollout_probe ~3 мин
scaling a бюджет 4 CPU / 2 ГиБ: 1 × 4, 2 × 2, 4 × 1 ~45 мин
scaling b реплики по 1 CPU: 1, 2, 3, 4 ~60 мин
scaling db PostgreSQL 0,5 CPU при 1, 2, 4 репликах — управляемое насыщение общей зависимости ~45 мин
scaling ab ячейки «до/после» улучшения и A/A (CONFIGS) ~30 мин на метку
*-quick, scaling quick самопроверка стенда; метки quick-* в отчёт не идут (.gitignore) 1,5–4 мин

Стенд — свой проект compose vlad-bench: тот же compose.yaml с override bench.compose.yml и подстановками bench.env, а не .env рабочего стенда. Контейнеры: vlad-bench-postgres, vlad-bench-valkey, vlad-bench-lb (HAProxy с рабочим infra/haproxy/haproxy.cfg), реплики vlad-bench-api-N, генератор vlad-bench-gen (базовый образ Dockerfile), сэмплер vlad-bench-sampler (образ приложения, --cgroupns host), сеть vlad-bench-net. Генератор ходит только через LB (http://haproxy:8080), при одной реплике тоже: серии сравнивают конфигурации на одном пути запроса. Каждая ячейка серии и каждый профиль — свежий стенд: down -v, хранилища, миграции, реплики, LB.

Файлы меток:

  • evidence/failover/<метка>/: summary.md, phases.csv (строка на фазу: обнаружение, возврат в LB, ошибки по окнам, восстановление, RPS, p95, повтор и сверка), timeline.csv (посекундно от действия), resources.csv (CPU и память по окнам фазы), meta.json, raw/ (события Docker, журнал HAProxy, журнал запросов .csv.gz);
  • evidence/rollout/<метка>/: summary.md, windows.csv (до / во время / после), timeline.csv (ответы старых и новых реплик по секундам), resources.csv, meta.json (раздел rollout: реплики, образы, ревизия схемы до и после, события контейнеров, проверки), raw/ (строки скрипта, журнал LB, события, запросы);
  • evidence/scaling/<метка>/: summary.md, runs.csv (строка на ступень), searches.csv (строка на ячейку), samples.csv (посекундно по контейнерам в окнах ступеней), stand.json (паспорт хранилищ), p95-by-rate.svg, cpu-by-component.svg, meta.json (план ячеек, бюджет, пороги, код, пул приложения), raw/ (итог генератора каждой ступени);
  • evidence/compare/<до>__<после>.md — compare.py; evidence/plots/<имя>/ — plots.py.

Хеш кода src_sha256 (по src/ и migrations/ внутри образа) и пул приложения по умолчанию (app_defaults) — в паспорте метки. Образ метки mtusi-messenger-vladimirceva:bench-<метка> остаётся в docker; образы quick-* стенд удаляет.

Методика не меняется между метками

Метки сравнимы, только если между ними различается код приложения (одно изменение) и больше ничего. Не меняются:

  • машина и сессия: «до», A/A и «после» — на одной машине, подряд, без перезагрузки и без другой нагрузки; рабочий стенд остановлен (make stop), посторонних контейнеров нет. Числа с другой машины рядом не ставятся;
  • профиль (run.py): лимиты (PostgreSQL 2 CPU / 1 ГиБ, HAProxy 1 / 256 МиБ, Valkey 0,5 / 128 МиБ, генератор 2 / 1 ГиБ, сэмплер 0,25 / 256 МиБ, реплика — 512 МиБ на CPU, без swap), данные (пользователи, читаемый чат, чаты записи), смесь 70/20/10, ступени и окна, SLO, лестница и деления поиска, порог досрочного выхода, зерно порядка ячеек. Новый параметр методики — поле профиля, а не константа в коде;
  • хранилища и LB: те же пины образов, что у рабочего стенда, тот же haproxy.cfg и valkey.conf; PostgreSQL — настройки образа плюс max_connections из конфигурации (по умолчанию 100);
  • приложение: значения по умолчанию src/config.py, окружение стенда — только срок сессии (stand.json, app_env). Изменение пула или другой настройки для «до/после» — правка значения по умолчанию в коде, а не окружение стенда: иначе src_sha256 не отличит метки;
  • генератор и сэмплер: loadgen.py, sampler.py, их лимиты.

Поменял что-то из списка — новая методика: метки переснимаются, в REPORT.md — что и почему. Нельзя менять профиль, чтобы результат выглядел лучше. --configs у серий a, b, db — только если конфигурация не помещается в ВМ Docker; это пишется в паспорт и в отчёт.

Честность результатов

  • В evidence/failover/<метка>/, evidence/rollout/<метка>/, evidence/scaling/<метка>/ пишет только run.py, в evidence/compare/ — только compare.py, в evidence/plots/ — только plots.py. Руками эти файлы не править и не пересобирать из памяти.
  • Каталог метки не перезаписывается. Неудачная метка (aborted, предупреждения о хосте, пометки) не удаляется молча и не выдаётся за результат: сними новую метку и скажи пользователю, почему старая не годится. Удалять каталог метки — только с согласия пользователя.
  • Числа в REPORT.md переносятся из summary.md, *.csv и compare/*.md как есть: дельты не считать вручную, медианы не округлять «в пользу» гипотезы.
  • Гипотезы и прогнозы трека 1 записаны в REPORT.md до замеров и после них не переписываются; итог (подтверждена, опровергнута, частично) — отдельным абзацем ниже. Опровергнутая гипотеза — тоже результат.
  • Пороги признаков узкого места (THRESHOLDS) заданы до замеров. Их изменение — смена методики (переснять серии), а не подгонка вывода.
  • Проект не под git: измеренный код называет src_sha256 в паспорте. Если проект станет git-репозиторием, замер для отчёта — с закоммиченного кода, коммит — только с согласия пользователя.

Как устроен стенд (не ломать)

  • Чёрный ящик: run.py не импортирует src и в приложение не ходит; все запросы к API — генератор по HTTP через LB внутри сети стенда.
  • Исключение — PostgreSQL стенда: docker exec … psql от пользователя контейнера, SQL через stdin, только для обслуживания и сверки: VACUUM (ANALYZE), CHECKPOINT, число строк и разных текстов в чате записи, ревизия alembic_version, наличие колонки пробной ревизии. Данных, видимых приложению, оркестратор не меняет; схему меняет только миграция приложения (профиль rollout — тем же scripts/rolling-update.sh, что и рабочий стенд).
  • Сэмплер читает cgroup всех контейнеров ВМ (--cgroupns host), но роли назначает оркестратор по ID своих контейнеров; чужие в результаты не идут. В режиме list у него одно соединение с PostgreSQL (слот max_connections) и опрос статистики HAProxy внутри сети.
  • Все вызовы compose — с -p vlad-bench, обоими -f и --env-file bench/bench.env; скрипт замены получает то же через COMPOSE_PROJECT_NAME, COMPOSE_FILE, COMPOSE_ENV_FILES. Без этого down -v удалил бы чужой volume, а compose прочитал бы рабочий .env. Пароли хранилищ — новые на прогон, никуда не пишутся.
  • Пароли пользователей стенда живут только в памяти loadgen.py setup, токены — в файле фикстуры внутри контейнера генератора; в stdout, результаты и паспорт они не попадают.
  • Все отметки времени — часы ВМ Docker: генератор, события Docker (поток docker events, а не буфер демона), журнал HAProxy (docker logs -t), сэмплер. Начало и конец скрипта замены оркестратор переводит на часы ВМ по измеренному смещению (clock_offset_s).
  • Только стандартная библиотека Python на хосте и в генераторе. Новых зависимостей и образов (k6, wrk и т. п.) не добавлять.
  • Один прогон за раз: блокировка bench/.bench.lock. Остатки прерванного прогона run.py не удаляет сам: отказывается стартовать и печатает команды уборки (только контейнеры, сеть и volume vlad-bench*).
  • Чужие контейнеры не останавливать и не удалять; процессы по порту не убивать.
  • Столбцы runs.csv, searches.csv, phases.csv, timeline.csv, resources.csv не переименовывать и не удалять: по ним сравниваются метки и строятся графики. Новая метрика — новый столбец в конце.

Пометки и что с ними делать

Где Пометка Значит Действие
meta.json aborted прогон прерван результат частичный: серия — RESUME=1 на том же коде; профиль — новая метка
meta.json host_warnings батарея, давление на память, посторонние контейнеры, выгрузка страниц или сон хоста во время прогона устранить и переснять
searches.csv generator_bound на первой нарушившей ступени генератор у своего предела R* — нижняя граница; сказать пользователю, не выдавать за предел системы
searches.csv stand_down:… хранилище или LB упали или перезапускались ячейку не использовать, переснять серию
searches.csv cap поиск дошёл до потолка rate_cap предел не найден: сказать пользователю
phases.csv over_bound обнаружение отказа дольше формулы haproxy.cfg это результат, а не сбой: объяснить в отчёте
phases.csv verified=False ключей отправлено ≠ строк в базе профиль падает сам; разбираться в дефекте, не переснимать вслепую

Проверка правок стенда

make fmt && make lint, uv run python bench/analysis.py --selftest, затем самопроверки: make bench-failover-quick (~1,5 мин), make bench-rollout-quick (~1,5 мин), make bench-scaling-quick (~4 мин). Прогоны доходят до конца, aborted нет, в failover сверка ok, в rollout все проверки True, в серии есть R* обеих ячеек. Docker недоступен из sandbox — попросить пользователя запустить команду и прислать вывод.