- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
222 lines
15 KiB
Markdown
222 lines
15 KiB
Markdown
# Tasks
|
||
|
||
Как строить — `design.md` (дальше «решение N»), что должно получиться —
|
||
дельта `specs/load-benchmark/spec.md`. Перед первым файлом слоя
|
||
прочитать его правило: `bench.md`, `docker.md`, `run-modes.md`.
|
||
Замер для отчёта снимается с закоммиченного кода. Коммит — только после
|
||
подтверждения пользователя, `make bench` полной матрицы — только с его
|
||
согласия (`bench.md`, «Измеренное состояние — commit», «Результаты»).
|
||
Рабочий стенд (`mtusi-lab2`) не трогать ни на одном шаге.
|
||
|
||
## 1. Проба `auto_explain`
|
||
|
||
- [x] 1.1 Проверить решение 5 до остального кода, на временном проекте
|
||
compose `mtusi-bench` с override из задачи 2.1:
|
||
- Postgres с `shared_preload_libraries=auto_explain`, миграции, API;
|
||
- пара сообщений через HTTP;
|
||
- включение `auto_explain` через `ALTER SYSTEM` + `pg_reload_conf()`,
|
||
маркеры `RAISE LOG`;
|
||
- один запрос истории уже открытым соединением пула.
|
||
|
||
Проверка: в `docker logs` между маркерами есть запись `duration: …
|
||
plan:` с `Query Text` запроса `messages`, `Query Parameters` и
|
||
`Buffers`. После `ALTER SYSTEM RESET` новых записей нет. Стенд удалён
|
||
(`down -v`). Если план не пишется — остановиться и обсудить с
|
||
пользователем, а не менять способ молча.
|
||
|
||
## 2. Стенд на compose
|
||
|
||
- [x] 2.1 `bench/bench.compose.yml` и `bench/bench.env` (решение 1):
|
||
- имена `mtusi-bench-*` и сеть `mtusi-bench`;
|
||
- `ports: !reset []`, у `api` и `migrate` — `volumes: !reset []`;
|
||
- образ `mtusi-messenger:bench`;
|
||
- у api — `healthcheck: disable`, у всех — `restart: "no"`;
|
||
- лимиты и `AUTH__SESSION_TTL_SECONDS` из `${BENCH_*:?}`;
|
||
- `command` Postgres с `auto_explain`;
|
||
- в `bench.env` только несекретные имена и порты.
|
||
|
||
Проверка: `docker compose -p mtusi-bench --env-file bench/bench.env -f
|
||
docker-compose.yml -f bench/bench.compose.yml config` с переменными
|
||
`BENCH_*` и паролями показывает лимиты, отсутствие `ports` и
|
||
`config.toml`, сеть `mtusi-bench`. Без `BENCH_*` — ошибка `:?`.
|
||
Рабочий `.env` на вывод не влияет: с `--env-file` у API
|
||
`DATABASE__USER=bench`, без флага — значение из рабочего `.env`
|
||
(сам `.env` не правится).
|
||
- [x] 2.2 `bench/run.py`: класс `Stand` поверх compose (решения 1, 2):
|
||
- одна функция вызова с `-p mtusi-bench`, обоими `-f` и собранным
|
||
окружением: пароли из `secrets` на прогон, `BENCH_*` из новых полей
|
||
`Profile`;
|
||
- на размер: `down -v`, `up --wait postgres valkey`, `run --rm
|
||
migrate`, `up --no-deps --no-build api`, ожидание готовности;
|
||
- `check_free` по контейнерам проекта и `mtusi-bench-k6`;
|
||
- предупреждение в вывод и `host_warnings`, если сумма лимитов памяти
|
||
API, Postgres и Valkey больше памяти VM минус 1,5 ГиБ;
|
||
- уборка в `finally` и по Ctrl+C.
|
||
|
||
Проверка: `uv run python bench/run.py --profile quick --label
|
||
quick-stand --sizes 1000` проходит размер, предупреждения о VM нет
|
||
при лимитах 2 + 3 + 0,5 ГБ на VM 7,75 ГиБ. С `--memory 6g` (отладка)
|
||
предупреждение есть. Во время прогона
|
||
`docker ps` показывает `mtusi-bench-{postgres,valkey,api,k6}` без
|
||
портов. После — нет контейнеров, сети и volume `mtusi-bench*`. Ctrl+C
|
||
посреди наполнения — то же; `make run_docker` на 8080 всё время
|
||
отвечает, его `StartedAt` не меняется.
|
||
|
||
## 3. Идентификация в k6
|
||
|
||
- [x] 3.1 `bench/k6/lib.js` и `prepare.js` (решение 3):
|
||
- `authHeaders(token)` — Bearer;
|
||
- регистрация с паролем из `crypto.randomBytes`, вход по Basic;
|
||
- токены в `fixture.json`;
|
||
- `createChat` и `sendMessage` с токеном.
|
||
- [x] 3.2 `prefill.js`, `write.js`, `read.js`, `cursors.js`, `tail.js` —
|
||
токен отправителя или читателя из фикстуры. Проверка задач 3.1–3.2:
|
||
- короткий прогон проходит все этапы без 401 и `errors`;
|
||
- в access-логе API нет `X-User-Id`-запросов;
|
||
- `grep -r` по каталогу метки на токены и пароли из `.work/` (снять
|
||
до уборки) ничего не находит;
|
||
- `.work/` после прогона удалён.
|
||
|
||
## 4. Обслуживание БД и метрики хранилища
|
||
|
||
- [x] 4.1 Обслуживание после наполнения (решение 4): `VACUUM (ANALYZE)`
|
||
и `CHECKPOINT` через `docker exec … psql` от пользователя контейнера,
|
||
строка этапа в выводе. Затем размеры таблицы и индексов `messages`,
|
||
`count(*)`, `db_bytes_per_message` в `meta.sizes` и в сводку.
|
||
Проверка: в выводе короткого прогона строки этапов идут по порядку
|
||
наполнение → обслуживание → курсоры. В `meta.json` у каждого размера
|
||
поля объёма заполнены, `count(*)` = N.
|
||
- [x] 4.2 `db_cpu_cores` в конце `RUN_FIELDS` и `PREFILL_FIELDS`, `db` в
|
||
строке прогона (решение 6). Проверка: в `runs.csv` и `prefill.csv`
|
||
прежние столбцы на месте и в том же порядке, новый — последним и
|
||
заполнен.
|
||
- [x] 4.3 Сторож Postgres и Valkey: пометка `stand_down`, остановка
|
||
матрицы с именем контейнера (решение 6). Проверка: `docker kill
|
||
mtusi-bench-postgres` во время прогона чтения короткого профиля —
|
||
прогон помечен, команда называет контейнер, код ≠ 0, стенд убран.
|
||
|
||
## 5. План запроса истории
|
||
|
||
- [x] 5.1 `bench/k6/explain.js`: первая страница, середина и последний
|
||
курсор пула, проверка 200 и полной страницы.
|
||
- [x] 5.2 Этап «план» в `run.py` (решение 5): маркеры, включение и
|
||
выключение `auto_explain`, разбор журнала, ровно три записи
|
||
`messages` или `BenchError` с размером. Затем psql-пара с индексом и
|
||
без в `BEGIN … ROLLBACK`, проверка индекса по `pg_indexes`, файл
|
||
`explain-<размер>.txt`, раздел «Планы запроса истории» в
|
||
`summary.md`. Проверка на коротком прогоне:
|
||
- у каждого размера есть файл с тремя планами приложения и парой
|
||
psql;
|
||
- сводка показывает узел, буферы и время;
|
||
- после этапа `\d messages` в Postgres стенда содержит
|
||
`ix_messages_chat_id_created_at_id`;
|
||
- при выключенном вызове `explain.js` (временная правка, не
|
||
коммитить) команда падает с размером и убирает стенд.
|
||
|
||
## 6. Паспорт и сравнение меток
|
||
|
||
- [x] 6.1 Паспорт (решение 7):
|
||
- `stand.postgres`: образ, версия, настройки;
|
||
- `stand.valkey`: образ, версия, `maxmemory`;
|
||
- `limits` по трём контейнерам;
|
||
- `app_env` без `PASSWORD`;
|
||
- версии SQLAlchemy, asyncpg и redis.
|
||
|
||
Проверка: в `meta.json` короткого прогона поля заполнены, `grep -i
|
||
password` по каталогу метки находит только имена ключей, не значения.
|
||
- [x] 6.2 `bench/compare.py` (решение 8): рекурсивная методика,
|
||
таблица памяти с байтами в БД. Проверка на двух коротких метках:
|
||
- метка сама с собой — нули во всех ячейках;
|
||
- метка с `--memory 1g` против обычной — отказ с ключом
|
||
`limits.api.memory` и обоими значениями;
|
||
- ручная правка `stand.postgres.settings.shared_buffers` в копии
|
||
`meta.json` — отказ с этим ключом.
|
||
- [x] 6.3 `bench/ab.py` без `bench_inproc`, проверка занятости — каталог
|
||
метки стенда. Проверка: `uv run python bench/ab.py --before a --after
|
||
b --reapply HEAD --dry-run` на чистом дереве печатает план без
|
||
`bench_inproc`. Занятая метка и нечистое дерево — отказ до первого
|
||
шага.
|
||
|
||
## 7. Удаление `inproc.py` и цели Makefile
|
||
|
||
- [x] 7.1 Удалить `bench/inproc.py`, цель `bench_inproc` и строку
|
||
`evidence/profile/quick-*.txt` в `.gitignore`. Обновить комментарии
|
||
целей `bench*` в `Makefile`: заголовок без «трек 1», оценки времени —
|
||
по факту задачи 8.2. Проверка: `grep -rn inproc` вне
|
||
`openspec/changes/archive` и этого change пуст. `make -n bench
|
||
bench_quick bench_compare bench_ab` печатает команды без ошибок.
|
||
|
||
## 8. Проверка стенда и коммит кода
|
||
|
||
- [x] 8.1 `make lint`. Проверка: без замечаний.
|
||
- [x] 8.2 `make bench_quick` целиком. Проверка:
|
||
- код 0, все размеры и прогоны без пометок `errors`;
|
||
- в сводке планы на 10k;
|
||
- время прогона и скорость наполнения записаны для оценки полной
|
||
матрицы. Если оценка заметно больше часа — сказать пользователю
|
||
до baseline.
|
||
- [x] 8.3 Показать `git status` и `git diff --stat`, предложить
|
||
сообщение, после подтверждения закоммитить код стенда (`feat: run
|
||
load bench on PostgreSQL with query plans`). Проверка: `git status`
|
||
чистый, на этом commit `run.py` пишет `dirty: false`.
|
||
|
||
## 9. Документация
|
||
|
||
- [x] 9.1 `.claude/rules/bench.md`:
|
||
- раздел «Что доработать под лабу 2» убрать;
|
||
- в «Что не меняется между метками» — лимиты и образы Postgres и
|
||
Valkey, настройки Postgres образа с `auto_explain`, окружение
|
||
приложения из override, обслуживание после наполнения;
|
||
- в «Как писать» — граница чёрного ящика для Postgres стенда
|
||
(решение 4) вместо исключения `--child`;
|
||
- раздел «Диагностика» удалить;
|
||
- таблица инструментов без `inproc.py`.
|
||
|
||
Проверка: правило не упоминает `MemoryStore`, `X-User-Id` и
|
||
`bench_inproc`.
|
||
- [x] 9.2 `AGENTS.md`:
|
||
- строки `bench*` в таблице команд с оценками времени по факту;
|
||
- карта кода: `bench.compose.yml`, `bench.env`, `explain.js`, без
|
||
`inproc.py` и `evidence/profile/`;
|
||
- в «Переходном состоянии» убрать пункт `bench/`.
|
||
|
||
Проверка: `grep -n "inproc\|не доработан" AGENTS.md` пуст.
|
||
|
||
## 10. Базовый замер и отчёт
|
||
|
||
- [x] 10.1 Записать гипотезы H1–H4 (решение 10) в раздел экспериментов
|
||
`REPORT.md` до запуска полной матрицы. Проверка: раздел есть в diff
|
||
до появления `evidence/bench/baseline/`.
|
||
- [x] 10.2 Подготовить хост (питание, swap, `memory_pressure`, нет
|
||
посторонних контейнеров) и с согласия пользователя запустить `make
|
||
bench BENCH_LABEL=baseline`. Проверка:
|
||
- код 0, `status: complete`, 54 прогона;
|
||
- в паспорте `dirty: false`, без `host_warnings`;
|
||
- файлы `explain-10k.txt`, `explain-100k.txt`, `explain-500k.txt`
|
||
есть.
|
||
|
||
Предупреждение о хосте — переснять, а не игнорировать.
|
||
- [x] 10.3 Показать изменения, после подтверждения закоммитить
|
||
`evidence/bench/baseline/` (`docs: add PostgreSQL baseline bench
|
||
evidence`).
|
||
- [x] 10.4 `REPORT.md`:
|
||
- раздел экспериментов: стенд и лимиты трёх контейнеров, профиль,
|
||
таблица результатов по ячейкам, ссылка на каталог, итог по H1–H4
|
||
как получилось;
|
||
- в разделе архитектуры — обоснование индекса истории: запрос,
|
||
планы первой, средней и последней страницы на 10k / 100k / 500k,
|
||
сравнение без индекса, ссылки на `explain-*.txt`;
|
||
- строка уровня 4 «индекс истории и EXPLAIN» в таблице
|
||
доказательств вместо TODO;
|
||
- ограничения: один большой чат, настройки Postgres по умолчанию,
|
||
generic и custom plan, Docker Desktop;
|
||
- убрать «EXPLAIN — следующий change» из «Ограничений» и
|
||
«Переходного состояния» `AGENTS.md`.
|
||
|
||
Проверка: каждое число в тексте есть в `summary.md`, `runs.csv` или
|
||
`explain-*.txt` метки `baseline`. Commit метки указан.
|
||
- [x] 10.5 Показать изменения, после подтверждения закоммитить отчёт и
|
||
документацию (`docs: report PostgreSQL baseline and history index
|
||
plans`). `graphify update .`. Проверка: `git status` чистый,
|
||
`openspec validate bench-postgres --strict` проходит.
|