# Design ## Context Мотивация — `proposal.md`, требования — дельта `load-benchmark`. Что есть сейчас: - `bench/run.py` (оркестратор, только stdlib) поднимает сеть `mtusi-bench` и два контейнера через `docker run`: - `mtusi-bench-api` — образ `mtusi-messenger:bench`, `--cpus=1 --memory=2g --memory-swap=2g --no-healthcheck`; - `mtusi-bench-k6` — `grafana/k6` с пином, `sleep infinity`, сценарии запускаются через `docker exec`. Каждый размер — новый контейнер API, то есть пустой `MemoryStore`. Методика (размеры, конкуренция, повторы, прогрев, лимиты) — поля `Profile`, они целиком пишутся в `meta.json`. - `bench/k6/lib.js` собирает заголовок `X-User-Id`, а регистрация в `prepare.js` идёт без пароля. На коде лабы 2 первый же запрос `prepare.js` получает 400, следующие — 401. - `bench/inproc.py` в режиме `--child` импортирует `src.infra.memory.MemoryStore`, которого больше нет. - Рабочий стенд — `docker-compose.yml`, проект `mtusi-lab2`: Postgres 18.6 и Valkey 9.1.2 с пинами, healthcheck и одноразовый `migrate`; значения из `.env`, `config.toml` монтируется. У `make failure_checks` уже есть образец отдельного проекта с override (`student-tests/failures.compose.yml`, `ports: !reset []`). - Настройки приложения по умолчанию (`src/config/settings.py`): пул 10 + 5, `pool_timeout` 5 с, `statement_timeout` 5 с, срок сессии 3600 с, кэш с таймаутом 0,2 с. - Запрос страницы истории (`get_chat_messages_page`): `WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4` по индексу `ix_messages_chat_id_created_at_id`. asyncpg выполняет его как prepared statement. - В закреплённом образе Postgres есть `auto_explain.so` (проверено `ls /usr/lib/postgresql/18/lib/`). ## Goals / Non-Goals **Goals:** - `make bench` и `make bench_quick` работают на коде лабы 2 и меряют систему в том составе, в котором она развёрнута: API, PostgreSQL, Valkey. - План запроса истории — часть каждой метки. Его снимают с того запроса, который выполнило приложение, а не с копии SQL. - Метки сравнимы между собой: лимиты, образы и настройки хранилищ входят в методику и проверяются `make bench_compare`. **Non-Goals:** - Неравномерные размеры чатов, сравнение ≥2 индексов или запросов, стоимость записи по вариантам индекса — change `track2-query-plans`. Здесь читаемый чат один и большой. - Backup и восстановление — `track2-backup-restore`. - Изменения `src/`, миграций, контракта и `student-tests/`. - Настройка Postgres (`shared_buffers` и т.п.): в стенде действуют настройки образа, как у рабочего стенда. Подбор параметров — не цель этого change. - Сравнение с метками лабы 1: другое хранилище — другая методика. ## Decisions ### 1. Стенд — отдельный проект compose `mtusi-bench` с override Стенд поднимается из того же `docker-compose.yml` под проектом `mtusi-bench` с override `bench/bench.compose.yml`, по образцу `make failure_checks`. Override задаёт следующее. - **Имена.** `container_name: mtusi-bench-<сервис>` для postgres, valkey и api; сеть `networks.default.name: mtusi-bench`. Имена остаются в префиксе `mtusi-bench-*` из `bench.md`. Watcher, снимки cgroup и k6 (`docker run --network mtusi-bench`) работают по прежним именам. - **Без портов на хосте:** `ports: !reset []` у всех сервисов. - **Без файлов рабочего стенда.** `volumes: !reset []` у `api` и `migrate` убирает монтирование `config.toml`. Образ для обоих — `mtusi-messenger:bench`, оркестратор собирает его сам, как сейчас. - **У api:** `healthcheck: disable: true`, `restart: "no"`, лимиты `cpus`, `mem_limit` и `memswap_limit` из переменных. - **У postgres и valkey:** `restart: "no"` и свои лимиты. У postgres ещё `command: ["postgres", "-c", "shared_preload_libraries=auto_explain"]` (решение 5). Окружение compose собирает оркестратор: - `--env-file bench/bench.env` заменяет `.env` рабочего стенда. Проектный каталог — корень репозитория, и без флага compose прочитал бы рабочий `.env` для подстановок. В `bench/bench.env` — только несекретные имена и порты: `POSTGRES_USER`, `POSTGRES_DB`, `APP__PORT=8080` и т.п. - `POSTGRES_PASSWORD` и `VALKEY_PASSWORD` генерирует `secrets` на каждый прогон. Они передаются в окружение процесса `docker compose`, никуда не пишутся и в паспорт не попадают (решение 7). - Лимиты и срок сессии приходят из полей `Profile` переменными `BENCH_*`. Override ссылается на них с `:?`, поэтому без оркестратора стенд не поднимется. - Процесс `docker compose` получает собранное окружение, а не `os.environ`: случайная переменная `POSTGRES_*` из shell пользователя не попадёт в стенд. Все вызовы идут через одну функцию с `-p mtusi-bench` и обоими `-f`. На каждый размер: 1. `down -v --remove-orphans` — прежний стенд и volume; 2. `up -d --wait postgres valkey`; 3. `run --rm migrate`; 4. `up -d --no-deps --no-build api`; 5. ожидание `/health/ready` изнутри контейнера, как сейчас. `check_free` отказывается стартовать, если остались контейнеры проекта или `mtusi-bench-k6`, и печатает команду уборки. Уборка в `finally` — `down -v` и `docker rm -f mtusi-bench-k6`. **Альтернативы:** - Оставить `docker run` и добавить Postgres и Valkey так же. Тогда пины, healthcheck, пароль Valkey через `sh -c` и запуск миграций дублировались бы в `run.py` и расходились бы с compose при обновлении образа. Требование «тот же пин, что в compose» держалось бы на памяти. - Рабочий стенд или `make run_docker` — нельзя: спек запрещает трогать его базу и кэш, а его настройки зависят от `.env`. ### 2. Лимиты хранилищ и настройки приложения — поля `Profile` Новые поля `Profile`. Они одинаковы у `full` и `quick` и пишутся в `meta.json` вместе с остальными. | Поле | Значение | Зачем | |---|---|---| | `db_cpus`, `db_memory` | `"4"`, `"3g"` (swap = память) | объект замера — API на 1 CPU, как на лабе 1. Postgres не должен быть первым ограничением: у приложения пул до 15 соединений, то есть до 15 активных процессов БД, а 4 CPU хватает с запасом. Кто упёрся первым, видно по столбцам CPU (решение 6) | | `cache_cpus`, `cache_memory` | `"2"`, `"512m"` | Valkey выполняет команды в одном потоке, и лимит в 2 CPU не даёт квоте cgroup притормаживать его вместе с фоновыми потоками. Данные ограничивает `maxmemory 64mb` из `valkey.conf`, остальное — запас на процесс | | `session_ttl_seconds` | `21600` | размер 1M с наполнением идёт до ~40 мин. Срок 3600 с по умолчанию на медленном хосте мог бы истечь посреди прогона и дать 401 | Остальные настройки приложения — значения по умолчанию из `settings.py`: пул 10 + 5, таймауты и кэш. Их видно в паспорте (`app_env` и версия кода). Postgres работает на настройках образа (`shared_buffers` 128 МБ и т.д.). Свой `postgresql.conf` не монтируется: настройки — как у рабочего стенда, отличие одно — `shared_preload_libraries` (решение 5). Что даёт память Postgres при настройках образа. Свои буферы Postgres — 128 МБ, остальное читается через кэш страниц ОС. Кэш страниц входит в лимит памяти cgroup контейнера. Таблица `messages` на 1M с индексами — ориентировочно 250–350 МБ, так что в 3 ГБ она помещается целиком вместе с WAL. Больший лимит без изменения `shared_buffers` результат не изменит. Настройка Postgres — Non-Goal. **Бюджет VM.** Docker Desktop на машине автора — 12 CPU и 7,75 ГиБ. | Контейнер | CPU | Память | |---|---|---| | API | 1 | 2 ГБ | | Postgres | 4 | 3 ГБ | | Valkey | 2 | 0,5 ГБ | | Итого лимиты | 7 | 5,5 ГБ | k6 работает без лимита, порог пометки `generator` — 4 ядра. На k6, ядро VM и сам Docker остаётся около 2 ГиБ и 5 CPU. Если сумма лимитов памяти превышает память VM без запаса 1,5 ГиБ (VM уменьшили в настройках Docker Desktop), лимит перестаёт быть гарантией. Тогда оркестратор пишет предупреждение в вывод и `host_warnings`, как о swap. **Альтернативы:** - Тот же 1 CPU у Postgres: уже на `c=10` неясно, кто ограничивает throughput. - 2 CPU / 2 ГБ (первый вариант): хватает по оценке, но запас меньше. Пользователь попросил дать хранилищам больше. - Без лимитов у хранилищ: тогда их ресурсы зависят от того, что ещё запущено в VM, и метки разных дней перестают быть сравнимыми. ### 3. Идентификация в k6: регистрация с паролем, Basic, Bearer - `prepare.js` для каждого пользователя: - генерирует пароль `crypto.randomBytes` (`k6/crypto`); - регистрирует пользователя с паролем; - входит по `Authorization: Basic` (`k6/encoding`, UTF-8 base64); - кладёт токен в `fixture.json` рядом с id. - `lib.js`: `authHeaders(token)` → `Authorization: Bearer `, как `Actor.headers()`. `createChat` и `sendMessage` принимают токен отправителя. `read.js`, `cursors.js`, `tail.js` и новый `explain.js` читают историю токеном читателя. - `fixture.json` лежит в рабочем каталоге `.work/`, а его оркестратор удаляет в `finally`. Сырые итоги k6 (`raw/*.json`) пишутся только сценариями без `setup()`, поэтому `setup_data` с токенами в них не попадает. Задача проверки — `grep` по каталогу метки на значения токенов и паролей после короткого прогона. - Срок сессии стенда — `session_ttl_seconds` из `Profile` (решение 2). Логин один на пользователя на размер. KDF (Argon2id, ~11 входов на размер) в замер не попадает. ### 4. Обслуживание БД после наполнения: `VACUUM (ANALYZE)` и `CHECKPOINT` После последней порции наполнения оркестратор выполняет `VACUUM (ANALYZE)` по базе стенда, затем `CHECKPOINT`. Обе команды идут через `docker exec mtusi-bench-postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"` от пользователя контейнера, без пароля в командной строке. Зачем: - после массовой вставки autovacuum и autoanalyze запускаются когда захотят, в том числе посреди измеряемого прогона. План и время зависели бы от того, успела ли статистика обновиться; - явный `VACUUM (ANALYZE)` даёт всем меткам одинаковую статистику и карту видимости; - `CHECKPOINT` сбрасывает грязные страницы наполнения до замера, а не во время первого прогона чтения. Это новый пункт «Что не меняется между метками» в `bench.md`. **Граница чёрного ящика** (`bench.md`, «Как писать»). Приложение по-прежнему видит только HTTP от k6. Оркестратор обращается к PostgreSQL стенда напрямую только для измерения и обслуживания: - обслуживание (решение 4); - размеры таблиц; - включение и выключение `auto_explain`; - журнал PostgreSQL; - план без индекса в откатываемой транзакции. Данных, видимых приложению, он не меняет. Это исключение записывается в правило рядом с прежним исключением для `--child` (которое уходит вместе с `inproc.py`). ### 5. План запроса истории — `auto_explain` на запросах приложения Postgres стенда запускается с `shared_preload_libraries=auto_explain`. По умолчанию `auto_explain.log_min_duration = -1`, и модуль ничего не делает: в измеряемых прогонах его нет. Этап «план» идёт после обслуживания и сбора курсоров, до первого прогона размера. 1. Маркер начала: `DO $$ BEGIN RAISE LOG 'bench-explain start'; END $$`. 2. Включение: `ALTER SYSTEM SET auto_explain.log_min_duration = 0`, `log_analyze = on`, `log_buffers = on`, `log_timing = on`, `log_format = text`, затем `SELECT pg_reload_conf()`. SIGHUP применяет настройки и в уже открытых соединениях пула приложения. 3. `k6/explain.js`, 1 VU, три последовательных запроса истории читаемого чата с `limit` профиля, у каждого проверка 200 и полной страницы: - без курсора (первая страница); - курсор из середины пула; - последний курсор пула (последняя полная страница). 4. Выключение: `ALTER SYSTEM RESET` тех же параметров, `pg_reload_conf()`, маркер конца. 5. Разбор `docker logs mtusi-bench-postgres` между маркерами. Записи `LOG: duration: … plan:` с продолжением по строкам с табуляцией. Берутся только записи, у которых `Query Text` читает `messages`; запросы сессии и карточки чата отбрасываются. Записей должно быть ровно три, в порядке запросов. Иначе — `BenchError` с размером, и стенд убирается (сценарий «План не найден»). 6. Сравнение без индекса — для средней страницы. Из записи берутся `Query Text`, `Query Parameters` (Postgres 16+ пишет их по умолчанию) и имя индекса из узла `Index Scan using <имя>` или `Index Only Scan` / `Bitmap Index Scan`. В psql (SQL через stdin, не через shell): ```sql BEGIN; PREPARE page AS ; EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(<параметры>); DROP INDEX <имя>; EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(<параметры>); ROLLBACK; ``` Первый `EXPLAIN` — тот же запрос с индексом в той же сессии psql, чтобы пара отличалась только индексом. `DROP INDEX` берёт `ACCESS EXCLUSIVE` на `messages` до `ROLLBACK`. Нагрузки в этот момент нет, пул приложения простаивает. После `ROLLBACK` оркестратор проверяет по `pg_indexes`, что индекс на месте (сценарий «Индекс остаётся»). Если план приложения не использовал индекс, сравнения нет, а в файле и сводке это сказано прямо. 7. Файл `explain-<размер>.txt` (`explain-10k.txt` и т.д.): - шапка: размер, позиция каждой страницы (`after` из пула курсоров), commit; - три плана приложения как есть; - вывод psql с индексом и без. В `summary.md` — раздел «Планы запроса истории»: размер, страница, узел, `shared hit` / `read`, строки и время. **Почему не копия SQL в psql:** - копия запроса в `bench/` разошлась бы с `src/core/repos/message.py` при первой правке, а стенд не может импортировать `src`; - запрос с литералами в psql даёт custom plan, а приложение выполняет prepared statement asyncpg, и после пяти выполнений Postgres может перейти на generic plan; - `auto_explain` показывает именно тот план, который получило приложение, с его параметрами. Сравнение без индекса всё равно идёт через psql, но текстом и параметрами из записи приложения, без копии. Там custom plan — это отмечается в файле. **Почему не `pg_stat_statements`:** он даёт текст и статистику, но не план и не буферы одного выполнения. ### 6. Метрики хранилища - `Stand.snapshot()` читает ещё `cpu.stat` контейнера `mtusi-bench-postgres`. Новые столбцы `db_cpu_cores` дописываются в конец `RUN_FIELDS` и `PREFILL_FIELDS` (`bench.md`: столбцы не переименовываются, новые — в конце). Строка прогона в терминале печатает и `db`. - На размер после обслуживания: `pg_table_size('messages')`, `pg_indexes_size('messages')`, `count(*)` и `db_bytes_per_message` = (таблица + индексы) / число строк. На этот момент в таблице ровно N сообщений читаемого чата: чат записи ещё пуст. Поля идут в `meta.sizes` и в таблицу «Память и наполнение» сводки рядом с RSS. - Сторож (`Watcher`) проверяет ещё `Running`, `OOMKilled` и `RestartCount` контейнеров Postgres и Valkey. Если один из них упал, прогон получает пометку `stand_down`, матрица останавливается, а `BenchError` называет контейнер. При падении API, как и раньше, — `oom` или `app_down`. ### 7. Паспорт `static_passport` пополняется: - `stand.postgres`: - образ из `docker compose config --format json` (тот же пин) и `Image` контейнера; - `SHOW server_version`; - `settings` — значения из `pg_settings`: `shared_buffers`, `effective_cache_size`, `work_mem`, `maintenance_work_mem`, `max_connections`, `synchronous_commit`, `fsync`, `wal_level`, `checkpoint_timeout`, `max_wal_size`, `random_page_cost`, `jit`, `autovacuum`, `plan_cache_mode`, `shared_preload_libraries`; - `stand.valkey`: образ, `valkey_version` из `INFO server`, `maxmemory`, `maxmemory-policy`; - `limits`: словарь по контейнерам `api`, `postgres`, `valkey`, а не один словарь API. Значения читаются у запущенных контейнеров, как сейчас; - `app_env`: окружение контейнера API из `docker inspect`. Остаются только ключи в формате настроек (`SECTION__FIELD`), из них удаляются все, где есть `PASSWORD`; - версии библиотек образа: к FastAPI, Starlette, pydantic и uvicorn добавляются SQLAlchemy, asyncpg и redis. ### 8. `make bench_compare` и `make bench_ab` - `methodology()` разворачивает вложенные словари в плоские ключи и сравнивает: - `profile.*`; - `limits.<контейнер>.*`; - `generator.image`; - `stand.postgres.image` и `stand.valkey.image`; - `stand.postgres.settings.*`; - `stand.app_env.*` (окружение API лежит в паспорте под `stand`). Остальное поведение — как в спеке: отказ при различии, «не проверено» для ключа одной метки. - Таблица памяти: байты RSS на сообщение и байты на сообщение в БД в обеих метках. - `ab.py`: шаги без `bench_inproc`, `git add` только `evidence/bench/`, проверка занятости — только каталог метки стенда. - Совместимость с метками лабы 1 не нужна: их в этом репозитории нет. ### 9. Удаление `inproc.py` Удаляются `bench/inproc.py`, цель `bench_inproc`, строка `evidence/profile/quick-*.txt` в `.gitignore` и раздел «Диагностика» в `bench.md`. Упоминания уходят из `AGENTS.md` (команды, карта кода). Скрипт остаётся в `7b775a2` (Migration в дельте спека). Формат времени, который он сверял, проверяют `make test` и `student-tests` (`contract.py` проверяет `created_at` по HTTP). ### 10. Базовый замер и гипотезы Порядок: 1. Код стенда закоммичен после подтверждения пользователя. 2. `make bench_quick` проверяет стенд: метка `quick-*` в git не идёт. 3. Хост подготовлен (`bench.md`, «Результаты»). 4. С согласия пользователя запускается `make bench BENCH_LABEL=baseline`. 5. Доказательства коммитятся после подтверждения. 6. Числа и планы переносятся в `REPORT.md`. Гипотезы записываются в `REPORT.md` до запуска полной матрицы. По `bench.md` результат пишется как получился: - **H1.** p50 чтения при той же конкуренции не растёт с 10k до 1M больше чем на величину шума: страница — keyset по индексу. `Buffers` средней и последней страницы того же порядка, что у первой, на всех размерах. - **H2.** Без индекса тот же запрос — `Seq Scan` и сортировка, буферы — порядка размера таблицы, время растёт линейно с N. - **H3.** На `c=10` и `c=50` чтение и запись упираются в CPU API (`app_cpu_cores` ≈ 1), а Postgres загружен меньше (`db_cpu_cores`). - **H4.** Скорость записи на кривой наполнения до 1M падает слабо: глубина B-дерева растёт логарифмически. ## Risks / Trade-offs - [`auto_explain` не запишет план: настройка не дошла до соединения пула или формат журнала другой] → маркеры начала и конца, ровно три ожидаемые записи, иначе отказ с размером. Первая задача реализации — проба на `bench_quick` до остального. - [Наполнение 1M через HTTP идёт дольше оценки (15–25 мин): запись — это ещё проверка сессии, вставка и commit с fsync на диске VM Docker] → ETA в выводе пересчитывается по факту. Если полная матрица выходит заметно дольше часа, сказать пользователю до baseline, а не менять методику молча. - [Рабочие наборы 1M (таблица ~250–350 МБ с индексами) больше `shared_buffers` 128 МБ: часть чтений идёт из кэша ОС внутри лимита 3 ГБ контейнера] → это свойство стенда, видно по `shared read` в планах. Прогрев перед каждым прогоном и одинаковое обслуживание делают его одинаковым у меток. В ограничениях отчёта сказано, что настройки Postgres — по умолчанию. - [Один большой читаемый чат: селективность `chat_id` около 100%, план может отличаться от плана при многих маленьких чатах] → в отчёте это ограничение. Неравномерные чаты — `track2-query-plans`. - [План приложения может быть generic, а сравнение в psql — custom] → тип плана видно в выводе. В файле планов это отмечено, сравнение «с индексом / без» идёт внутри одной сессии psql. - [`DROP INDEX` в откатываемой транзакции блокирует `messages`] → только на стенде, между прогонами, без нагрузки. После `ROLLBACK` индекс проверяется. - [`shared_preload_libraries=auto_explain` — отличие от рабочего Postgres] → при `log_min_duration = -1` модуль ничего не делает. Оно записано в паспорте (`settings.shared_preload_libraries`) и в спеке. - [Сырые итоги 54 прогонов и ~25 порций наполнения в git] → как на лабе 1, это килобайты на файл. `quick-*` в `.gitignore`. - [Шум хоста macOS / Docker Desktop] → прежние меры `bench.md`: состояние хоста в паспорте, A/A для уровня шума при сравнениях трека 2. ## Migration Plan Развёртывания нет: меняется только инструмент `bench/` и документация. Порядок — по `tasks.md`: сначала проба `auto_explain`, затем стенд и k6, `bench_quick`, коммит кода, `baseline`, отчёт. Откат — `git revert` коммитов change. Рабочий стенд и его volume не затрагиваются ни на одном шаге.