Files
mtusi2026lab3/openspec/changes/archive/2026-10-02-bench-postgres/tasks.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +03:00

222 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` проходит.