Propose remeasuring SQLAlchemy scaling as an OpenSpec change

This commit is contained in:
Artyom
2026-11-05 22:40:04 +03:00
parent 5c8f605cd3
commit 74a39fa93e
5 changed files with 168 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-05
@@ -0,0 +1,62 @@
## Context
Уровни 3/4 подтверждены на SQLAlchemy 2.0.45, Alembic 1.16.5 и pre-ping.
CTE отправки строится один раз, но PostgreSQL Insert с ON CONFLICT не даёт cache key:
компиляция повторяется на каждый запрос. Пилот проверяет нагрузку текущего образа.
## Goals / Non-Goals
Измерить текущий путь HTTP → HAProxy → SQLAlchemy → PostgreSQL, подтвердить причину
предела контрольными прогонами. Изменение только адаптера порта MessageLog зоны messaging;
доменные dataclass, pydantic-граница и сборка не меняются. Новых миграций нет.
## Decisions
1. Новый каталог evidence/track1-sqlalchemy, отдельный Compose project, HTTP 18083,
stats 23083. Volumes сохраняются: новые пользователи/чаты каждого прогона изолируют
горячие данные, размер накопленной БД записывается. Старые измерения не смешиваются.
2. Профиль прежний: 80% POST, 20% GET первой страницы, 20 пользователей/10 чатов;
10 с прогрева + 30 с измерения, 3 повтора, пауза 5 с. Геометрическая сетка 1.5,
два полностью насыщенных шага подряд завершают поиск. SLO: p95 ≤500 мс,
ошибки ≤1%, dropped ≤1%. Пилот не входит в итоговые медианы.
3. A: 1×4/2×2/4×1, суммарно 4 CPU/2048 MiB, 4 воркера, пул 32, maxconn 128,
API CPU 7–10. B: 1×1/2×1/8×1, 4×1 берётся из A; память 512 MiB на реплику.
PostgreSQL 2 CPU (0–1), LB 1 CPU (2), Valkey 0.5 CPU (3), k6 3 CPU (4–6).
4. Сначала базовые серии на 5c8f605; затем кэширование неизменного Core CTE через
lambda_stmt с enable_tracking=False. Все значения запроса передаются отдельными
bindparam: замыкания с пользовательскими данными запрещены. Цена — один compiled
объект на движок; состояние пользователя между запросами не сохраняется.
SQL/индексы и блокировки не меняются: chats PK → членство → квитанция → сообщение,
блокировка сохраняется до явного COMMIT. Проверка одинакового SQL и интеграционные
тесты гонок/TTL/rollback проверяют сохранение семантики.
5. Сравнение before/after на 8×1 чередуется внутри каждого повтора, интенсивности
выбираются после B и фиксируются в Makefile. Контроль пулов 4/8/16 и maxconn
16/32/64, затем 4×1 против 8×0.5 на CPU 7–10. Только последовательная нагрузка.
6. Каждый шаг хранит provenance (дата, полный SHA, образ и реальные лимиты), k6 JSON,
CPU/RAM, pg_stat_activity/statements, статистику LB. Возмущённые попытки сохраняются
отдельно, повтор никогда не перезаписывает сырьё. Исчерпание повторов завершает
серию ошибкой. Графики строятся только по принятым тройкам.
## Risks / Trade-offs
- Короткое окно не доказывает длительную стабильность → явно ограничить вывод.
- Накопление БД и порядок конфигураций влияют на результат → фиксировать размер,
чередовать before/after, не удалять данные ради равных стартовых условий.
- Общая VM и тепловой режим → CPU pinning, контроль постороннего CPU/разрывов,
сохранить отклонённые прогоны; не считать виртуальные CPU физическими ядрами.
- Улучшение может перенести предел в БД → отдельно назвать предел до и после,
не обещать линейного роста. Исторический asyncpg — только контекст, не парный опыт.
## Migration Plan
Собрать отдельные образы before/after, без изменения схемы. После измерений вернуть
обычную конфигурацию, проверить check/lint/student-test, smoke/persistence/failover,
лимиты и идемпотентность. Синхронизировать specs и архивировать оба завершённых change.
Остановить только свой Compose project, сохранив volumes.
## Документация
Context7: /sqlalchemy/sqlalchemy/rel_2_0_45, core/connections.rst, SQL compilation
caching и lambda_stmt. Прямой lambda_stmt(post_message) отвергнут библиотекой из-за
timedelta внутри функции; enable_tracking=False допустим для полностью статического
дерева с явными bindparam. Версия проверена локально: 2.0.45.
@@ -0,0 +1,29 @@
## Why
Трек «5» из README.md требует измерений цены масштабирования текущей реализации.
Старые серии относятся к raw asyncpg, а SQLAlchemy 2.0.45 добавляет компиляцию CTE,
сессии и pre-ping. Строки трека в REPORT.md пока не подтверждают текущий код.
## What Changes
- Повторить серии A/B и контрольные прогоны на SQLAlchemy, сохранив старое evidence отдельно.
- Исключить удаление volumes, перезапись сырья при повторе и принятие возмущённых прогонов.
- Проверить гипотезу о цене повторной компиляции CTE и измерить кэширование до/после.
- Записать методику, версии образов, реальные лимиты, сырые метрики, графики и ограничения.
## Capabilities
### Modified Capabilities
- `lab3-scaling-cost`: происхождение измерений, сохранение данных и попыток;
актуальная граница транзакции SQLAlchemy и проверяемое улучшение.
## Impact
Обвязка `scripts/scaling.py`, цели Makefile, графики, адаптер `messaging`, собственные тесты,
`evidence/track1-sqlalchemy`, REPORT.md. Контракт и схема PostgreSQL сохраняются.
## Non-goals
Out of scope из openspec/config.yaml: лабы 4–7, новые API, другие узлы и репликация БД.
Не изменяются нормативные файлы, лабы 1–2, чужие стенды и .pipeline. Публикаций нет.
@@ -0,0 +1,54 @@
## MODIFIED Requirements
### Requirement: Повторяемые серии одной командой
Оператор SHALL запускать каждую серию трека одной командой `make` на поднятом стенде. Каждый шаг серии SHALL выполняться открытой нагрузкой постоянной интенсивности из сети балансировщика (тот же профиль, что на уровне «4»: 80 % отправок сообщения с уникальным `Idempotency-Key`, 20 % чтений первой страницы истории, новые синтетические пользователи и чаты на каждый прогон) с прогревом перед окном замера; метрики считаются только по окну замера. Каждая точка «конфигурация × интенсивность» SHALL повторяться не менее 3 раз. Серия SHALL дописывать строку на прогон в `summary.csv` и сохранять сырьё шага в отдельном каталоге. Прогон, на который повлияла посторонняя нагрузка на общей VM (CPU вне контейнеров стенда больше одного ядра, разрыв сэмплов больше 10 с или прогон k6 дольше нагрузки на 90 с), SHALL отбраковываться в `disturbed.csv` и повторяться после того, как VM успокоится.
#### Scenario: Строка итогов на каждый прогон
- **WHEN** выполняется `make track1-a`
- **THEN** в `<TRACK1>/series-a/summary.csv` на каждую пару «конфигурация × интенсивность» есть не менее 3 строк с полями: конфигурация (реплики, CPU и память на реплику, воркеры, пул, очередь LB на реплику), предложенная интенсивность, номер повтора, успешные RPS, доля ошибок, сброшенные итерации, p50/p95/p99, CPU каждого компонента, память API, число соединений и ожиданий блокировок PostgreSQL, очередь LB, размер базы, признак насыщения
#### Scenario: Сырьё шага сохранено
- **WHEN** завершён любой шаг серии
- **THEN** в каталоге шага лежат итог k6 в JSON без токенов, сэмплы `docker stats`, статистики HAProxy и `pg_stat_activity` в CSV и топ запросов `pg_stat_statements`
#### Scenario: Возмущённый прогон повторяется
- **WHEN** во время прогона соседний стенд собирает образ и CPU VM вне контейнеров стенда превышает одно ядро
- **THEN** строка прогона попадает в `disturbed.csv`, а в `summary.csv` записывается повтор, сделанный после 15 с тишины
#### Scenario: Генератор не мешает измерению
- **WHEN** шаг завершился
- **THEN** CPU генератора нагрузки в строке итогов ниже его лимита, иначе шаг считается недостоверным и это видно по полю CPU генератора
#### Scenario: Данные и попытки сохранены
- **WHEN** оператор повторяет шаг либо запускает серию на существующем стенде
- **THEN** volumes и пользовательские данные сохраняются, новые попытки получают отдельные каталоги; исчерпание повторов возмущённого шага завершает серию ошибкой, а такой шаг не попадает в итоговую выборку
#### Scenario: Происхождение результатов проверяемо
- **WHEN** измерения относятся к новой версии SQL-слоя
- **THEN** они сохраняются в отдельном TRACK1 с датой, полным SHA, идентификаторами образов и реальными лимитами; исторические результаты остаются отдельно и не входят в текущие медианы
### Requirement: Короткая критическая секция отправки сообщения
Отправка сообщения SHALL выполнять проверку участия, назначение времени, запись ключа идемпотентности и сообщения одной атомарной командой PostgreSQL внутри транзакции с последующим COMMIT. Между блокировкой чата и COMMIT SHALL NOT выполняться другие бизнес-запросы для новой записи. Наблюдаемое поведение API (коды, тела, идемпотентность, порядок истории) SHALL NOT меняться. Основание: идемпотентность contracts/README.md и улучшение трека 1 README.md.
#### Scenario: Запись и ключ атомарны
- **WHEN** транзакция отправки прерывается до COMMIT
- **THEN** ни сообщение, ни ключ не видны другим репликам; повтор с тем же ключом сохраняет одно сообщение
#### Scenario: Под нагрузкой транзакции не ждут приложение
- **WHEN** выполняется make track1-compare на 8×1
- **THEN** сырьё содержит измеренные ожидания блокировок и idle in transaction до и после; отчёт учитывает ожидание явного COMMIT и не приравнивает один изменяющий оператор к отсутствию транзакционных пауз
#### Scenario: Отстающие часы реплики не ломают порядок
- **WHEN** часы реплики отстают от отметки последнего сообщения чата
- **THEN** новое сообщение получает created_at на 1 мкс позже последнего, а история остаётся упорядоченной по (created_at, id)
@@ -0,0 +1,21 @@
## 1. Методика и безопасная обвязка
- [ ] 1.1 Проверить пилот, исключить удаление volumes и перезапись попыток, сохранять provenance и реальные лимиты.
- [ ] 1.2 Проверить обвязку собственными тестами, make check/lint/student-test и smoke.
## 2. Базовые серии SQLAlchemy
- [ ] 2.1 Снять хост и серию A: 1×4/2×2/4×1, 3 повтора каждой точки.
- [ ] 2.2 Снять серию B: 1×1/2×1/8×1, найти и объяснить насыщенное звено.
## 3. Улучшение messaging
- [ ] 3.1 Кэшировать неизменный CTE; проверить API, гонки, TTL, rollback и изоляцию параметров.
- [ ] 3.2 Провести ≥3 чередующихся повтора before/after на одной конфигурации.
- [ ] 3.3 Провести контроль пулов/maxconn и числа процессов на одинаковых CPU.
## 4. Доказательства и завершение
- [ ] 4.1 Построить и проверить графики, сравнение, ограничения, REPORT и индекс evidence.
- [ ] 4.2 Выполнить make check/validate/lint/student-test, smoke/persistence/failover, limits и lb-check на итоговом коде.
- [ ] 4.3 Сверить числа с сырьём, закрыть связанные задачи SQLAlchemy, синхронизировать specs и архивировать завершённые changes.