Files
mtusi2026lab3/openspec/changes/archive/2026-10-02-bench-postgres/design.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

31 KiB
Raw Blame History

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 размер 500k с наполнением идёт ~20 мин на машине автора. На медленном хосте срок 3600 с по умолчанию мог бы истечь посреди прогона и дать 401
sizes (профиль full) 10k, 100k, 500k вместо 1M лабы 1, по просьбе пользователя сократить прогон: ~30 мин вместо ~45. Диапазон ×50 достаточен, чтобы увидеть, растёт ли страница с длиной истории; 500k ≥ 100k трека 2
prefill_chunk 25000 вместо 50 000: на Postgres наполнение ~850 сообщ/с, и порция в 50 000 шла бы ~59 с, на границе требования «прогресс не реже раза в минуту». Заодно кривая наполнения в два раза подробнее

Остальные настройки приложения — значения по умолчанию из settings.py: пул 10 + 5, таймауты и кэш. Их видно в паспорте (app_env и версия кода). Postgres работает на настройках образа (shared_buffers 128 МБ и т.д.). Свой postgresql.conf не монтируется: настройки — как у рабочего стенда, отличие одно — shared_preload_libraries (решение 5).

Что даёт память Postgres при настройках образа. Свои буферы Postgres — 128 МБ, остальное читается через кэш страниц ОС. Кэш страниц входит в лимит памяти cgroup контейнера. Таблица messages на 500k с индексами — ориентировочно 130–150 МБ (bench_quick: 272 байта на сообщение на 10k), так что в 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.randomUUID() (WebCrypto k6, без импорта): 73 символа, в пределах 12–128 контракта;
    • регистрирует пользователя с паролем;
    • входит по Authorization: Basic (k6/encoding, UTF-8 base64);
    • кладёт токен в fixture.json рядом с id.
  • lib.js: authHeaders(token) → Authorization: Bearer <token>, как 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 <uuid> 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):

    BEGIN;
    PREPARE page AS <Query Text>;
    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 контейнеров Postgres и Valkey и при падении останавливает k6. После каждого прогона и порции Stand.down_storages() смотрит Running, OOMKilled и RestartCount: при restart: "no" упавший контейнер остаётся остановленным, так что живой проверки Running хватает. Если хранилище упало, прогон получает пометку 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.valkey.maxmemory* — лимит и политика вытеснения из valkey.conf: образ не ловит правку конфигурации;
    • stand.app_env.* (окружение API лежит в паспорте под stand).

    Остальное поведение — как в спеке: отказ при различии, «не проверено» для ключа одной метки.

  • Таблица памяти: байты RSS на сообщение и байты на сообщение в БД в обеих метках.

  • ab.py: шаги без bench_inproc, git add только evidence/bench/<BEFORE>, проверка занятости — только каталог метки стенда.

  • Совместимость с метками лабы 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 до 500k больше чем на величину шума: страница — keyset по индексу. Buffers средней и последней страницы того же порядка, что у первой, на всех размерах.
  • H2. Без индекса тот же запрос — Seq Scan и сортировка, буферы — порядка размера таблицы, время растёт линейно с N.
  • H3. На c=10 и c=50 чтение и запись упираются в CPU API (app_cpu_cores ≈ 1), а Postgres загружен меньше (db_cpu_cores).
  • H4. Скорость записи на кривой наполнения до 500k падает слабо: глубина B-дерева растёт логарифмически.

Risks / Trade-offs

  • [auto_explain не запишет план: настройка не дошла до соединения пула или формат журнала другой] → маркеры начала и конца, ровно три ожидаемые записи, иначе отказ с размером. Первая задача реализации — проба на bench_quick до остального.
  • [Наполнение 500k через HTTP идёт дольше оценки (~10 мин): запись — это ещё проверка сессии, вставка и commit с fsync на диске VM Docker] → ETA в выводе пересчитывается по факту. Если полная матрица выходит заметно дольше 30 минут, сказать пользователю, а не менять методику молча.
  • [Рабочий набор 500k (таблица с индексами ~130–150 МБ) около 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 не затрагиваются ни на одном шаге.