diff --git a/openspec/changes/add-lab3-scaling-cost/.openspec.yaml b/openspec/changes/add-lab3-scaling-cost/.openspec.yaml new file mode 100644 index 00000000..1bb6456d --- /dev/null +++ b/openspec/changes/add-lab3-scaling-cost/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-28 diff --git a/openspec/changes/add-lab3-scaling-cost/design.md b/openspec/changes/add-lab3-scaling-cost/design.md new file mode 100644 index 00000000..ad7ce13a --- /dev/null +++ b/openspec/changes/add-lab3-scaling-cost/design.md @@ -0,0 +1,48 @@ +## Context + +Стенд уровня «4»: HAProxy (round robin, `maxconn` на реплику, очередь `timeout queue 3s`, `option http-server-close`) → `api` × `API_REPLICAS` (gunicorn, `WEB_CONCURRENCY` воркеров, пул asyncpg `DB_POOL_MAX_SIZE` на воркер) → PostgreSQL 2 CPU / 1 GiB и Valkey (кэш сессий). Нагрузка — k6 в сети `edge`, профиль `infra/k6/messages.js`. Отправка сообщения — одна транзакция: `BEGIN`, `SELECT … FOR UPDATE` строки чата с участниками, поиск ключа, CTE «сообщение + ключ + `last_message_at`», `COMMIT`: пять обращений к БД, три из них под блокировкой строки чата. Машина одна: VM Docker Desktop 16 CPU / 7,65 GiB, в ней же стенды других лаб (во время замеров простаивают). + +## Goals / Non-Goals + +**Goals:** серии, которые повторяются одной командой; честное равенство ресурсов внутри серии A; метрики каждого кандидата в узкое место на каждом шаге; одно улучшение с замером до и после. + +**Non-Goals:** абсолютные RPS как свойство приложения на другом железе; оптимизация всего подряд; смена профиля нагрузки. + +## Decisions + +### Оркестратор серий — `scripts/scaling.py` из заготовки + +Конфигурация `RxC` применяется `docker compose up -d --no-deps --wait api lb` с переменными окружения, затем ожидание R реплик `UP` в LB. Шаг: сброс `pg_stat_statements`, запуск сэмплеров (`docker stats`, HAProxy CSV, `pg_stat_activity` — раз в секунду), k6, снятие топа запросов; окно агрегирования — от метки `LOAD-START` + прогрев до конца замера. Альтернатива — отдельный стенд на конфигурацию (`down`/`up`) — дольше в разы и пересоздаёт PostgreSQL с холодным кэшем. + +### Равенство ресурсов в серии A + +- **CPU закреплены** (`cpuset`), чтобы компоненты не делили ядра: PostgreSQL — 0–1, LB — 2, Valkey — 3, k6 — 4–6, API — с 7-го: ровно `R×C` CPU (серия A — всегда 7–10, серия B — 7…7+R−1). Переменные `*_CPUSET` пустые по умолчанию: обычный стенд не закреплён. +- **Воркеры = CPU реплики**, пул 8 на воркер: 32 соединения в любой конфигурации A. +- **Очередь LB на реплику** `API_SERVER_MAXCONN = 32 × воркеры`: суммарно 128 одновременных запросов к API в любой конфигурации A. Иначе одна реплика 1×4 получала бы 64, а четыре 4×1 — 256, и сравнивались бы очереди, а не реплики. +- **Память** `2048 / R` MiB на реплику. +- k6 получает 3 CPU / 512 MiB, чтобы не стать узким местом на верхних шагах; его CPU пишется в каждую строку. + +### Сетка интенсивностей + +Геометрический поиск `start:1.5:max` с `start = 100 × R×C` rps; конфигурация останавливается после двух шагов подряд, насыщенных во всех повторах. 3 повтора на точку, прогрев 10 с, замер 30 с (≥3 000 запросов на точку даже на нижнем шаге — p99 устойчив). Потолок по SLO (наибольшая ненасыщенная интенсивность) грубый из-за шага 1,5, поэтому рядом пишется пик успешных RPS (медиана повторов на лучшем шаге): в открытой модели при перегрузке он и есть пропускная способность. + +### Серия B переиспользует точку 4×1 + +4×1 в серии B совпадает с 4×1 серии A (1 CPU, 512 MiB, 1 воркер, те же CPU 7–10), поэтому серия B прогоняет 1×1, 2×1 и 8×1, а 4×1 берётся из A. Экономия — 18 прогонов. + +### Признаки насыщения на шаге + +CPU PostgreSQL против `PG_CPUS × 100 %`; в `pg_stat_activity` — активные, ждущие блокировку (`wait_event_type = Lock`) и всего клиентских соединений против `max_connections` и суммарного пула; CPU и очередь (`qcur`, `qtime`) LB; CPU API против `R×C × 100 %`; сброшенные итерации k6. Топ `pg_stat_statements` показывает, какой оператор съел время БД. + +### Улучшение выбирается после серии B + +Кандидаты из proposal, каждый привязан к узкому месту: блокировка строки чата → меньше обращений к БД под блокировкой; пул → размер пула; очередь в API → `maxconn`; CPU API на установку соединений → keep-alive LB→API; соединения PostgreSQL → PgBouncer. Выбор и его обоснование дописываются сюда отдельным коммитом до реализации. + +## Risks / Trade-offs + +- [Один host: k6, LB, API и PostgreSQL делят VM] → закрепление CPU, CPU генератора в каждой строке, снимок `docker stats` всего хоста перед серией. +- [Троттлинг CFS при мелких квотах] → это и есть часть цены 4×1, видна по p99. +- [База растёт от шага к шагу] → размер базы пишется в каждую строку; серии начинаются с пустой базы. +- [Тепловой режим ноутбука и фоновые процессы] → 3 повтора, медиана и min–max, чередование не делается ради простоты, порядок шагов фиксирован и записан. +- [Часы сэмплеров и k6] → все метки ставятся часами хоста, окно — по метке `LOAD-START` из вывода k6. +- [Открытая модель упирается в `MAX_VUS`] → сброшенные итерации считаются признаком насыщения, а не ошибкой генератора. diff --git a/openspec/changes/add-lab3-scaling-cost/proposal.md b/openspec/changes/add-lab3-scaling-cost/proposal.md new file mode 100644 index 00000000..35e322b7 --- /dev/null +++ b/openspec/changes/add-lab3-scaling-cost/proposal.md @@ -0,0 +1,37 @@ +## Why + +Уровень «4» показал, что две реплики переживают отказ, но не то, во что обходится каждая следующая. Трек 1 «Цена масштабирования» рубрики «5» `README.md` требует сравнить 1/2/4 реплики при фиксированном суммарном CPU/RAM, провести серию с ростом ресурсов, найти точку насыщения БД, LB или пула, объяснить, почему реплики перестают помогать, и подтвердить одно улучшение замером до и после. Закрывает строку трека 1 в `REPORT.md`. + +## Гипотезы (до измерений) + +- **H1, фиксированный бюджет API 4 CPU / 2 GiB.** 1×4, 2×2 и 4×1 (воркеров столько же, сколько CPU) дают одинаковый потолок успешных RPS в пределах ±15 %: упор — суммарный CPU интерпретатора, дробление его не создаёт и не снимает. 4×1 хуже по p99 из-за мелкой квоты CFS. +- **H2, рост 1→2→4→8 реплик по 1 CPU.** До 4 реплик пропускная способность растёт почти линейно (≥3,2× от одной), от 4 к 8 — меньше чем в 1,5 раза. Насыщается общий PostgreSQL: блокировка строки горячего чата (`SELECT … FOR UPDATE` держится три обращения к БД) и CPU у лимита. LB не узкое место: CPU ниже половины лимита, очередь `qcur` пуста, пока не насыщен API. +- **H3, улучшение.** Мера против найденного узкого места даёт не меньше +15 % потолка или вдвое меньший p95 при той же нагрузке и тех же ресурсах. + +## What Changes + +- `scripts/scaling.py` — оркестратор серий: конфигурация `реплики×CPU`, воркеры, пул, очередь LB на реплику, закрепление контейнеров за CPU, поиск колена с ≥3 повторами, `summary.csv` и сырьё на шаг. +- Сэмплеры: `docker stats`, статистика HAProxy, `pg_stat_activity`, `pg_stat_statements`, размер базы. +- `compose.yaml`: закрепление CPU (`cpuset`) через переменные; по умолчанию стенд не меняется. +- `tools/plot_track1.py` — графики. +- Цели `make track1-*` и `make plots`. +- Одно улучшение, выбранное по найденному узкому месту. Кандидаты: короче критическая секция записи сообщения, размер пула, `maxconn` реплики в LB, keep-alive LB→API, PgBouncer. + +## Capabilities + +### New Capabilities +- `lab3-scaling-cost`: методика серий, фиксированный бюджет, рост ресурсов, признаки насыщения, сырые данные, графики, подтверждённое улучшение. + +### Modified Capabilities +- нет; если улучшение меняет наблюдаемое поведение стенда, дельта добавляется к затронутой capability. + +## Impact + +- Стенд: `compose.yaml` (переменные закрепления CPU), `.env.example`. +- Обвязка: `scripts/scaling.py`, `scripts/docker-stats.sh`, `scripts/lb-stats.sh`, `scripts/pg-stats.sh`, `scripts/probe.py`, `tools/plot_track1.py`, `Makefile`, `pyproject.toml`. +- Код: только если улучшение — изменение приложения. +- Отчёт: раздел трека 1, `evidence/track1/`. + +## Non-goals + +Несколько узлов, Swarm, HA PostgreSQL и LB — трек 2 и Out of scope. Новые зависимости приложения и смена контракта не вводятся. Профиль нагрузки не меняется ради «улучшения»: число чатов и доля чтений те же, что на уровне «4». diff --git a/openspec/changes/add-lab3-scaling-cost/specs/lab3-scaling-cost/spec.md b/openspec/changes/add-lab3-scaling-cost/specs/lab3-scaling-cost/spec.md new file mode 100644 index 00000000..9441ce56 --- /dev/null +++ b/openspec/changes/add-lab3-scaling-cost/specs/lab3-scaling-cost/spec.md @@ -0,0 +1,65 @@ +## Purpose + +Определяет, как стенд измеряет цену горизонтального масштабирования API: сравнение числа реплик при фиксированном бюджете, рост ресурсов до насыщения общей зависимости, доказательства точки насыщения и подтверждение улучшения замером до и после. + +## ADDED Requirements + +### Requirement: Повторяемые серии одной командой + +Оператор SHALL запускать каждую серию трека одной командой `make` на поднятом стенде. Каждый шаг серии SHALL выполняться открытой нагрузкой постоянной интенсивности из сети балансировщика (тот же профиль, что на уровне «4»: 80 % отправок сообщения с уникальным `Idempotency-Key`, 20 % чтений первой страницы истории, новые синтетические пользователи и чаты на каждый прогон) с прогревом перед окном замера; метрики считаются только по окну замера. Каждая точка «конфигурация × интенсивность» SHALL повторяться не менее 3 раз. Серия SHALL дописывать строку на прогон в `summary.csv` и сохранять сырьё шага в отдельном каталоге. + +#### Scenario: Строка итогов на каждый прогон + +- **WHEN** выполняется `make track1-a` +- **THEN** в `evidence/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** шаг завершился +- **THEN** CPU генератора нагрузки в строке итогов ниже его лимита, иначе шаг считается недостоверным и это видно по полю CPU генератора + +### Requirement: Фиксированный бюджет реплик + +Серия A SHALL сравнивать конфигурации 1×4, 2×2 и 4×1 (реплики × CPU на реплику) при одинаковом суммарном бюджете API 4 CPU и 2 GiB. Число воркеров реплики SHALL равняться её CPU, а суммарные пул соединений с БД и допустимая конкуренция LB к API SHALL быть одинаковыми во всех конфигурациях. Реплики API SHALL быть закреплены за одним и тем же набором из 4 CPU, а PostgreSQL, балансировщик, Valkey и генератор нагрузки — каждый за своими CPU с теми же лимитами во всех шагах. + +#### Scenario: Конфигурации равны по ресурсам + +- **WHEN** выполняется `make track1-a` +- **THEN** для каждой конфигурации `docker inspect` реплик даёт одинаковый набор CPU, а произведения «реплики × CPU», «реплики × память», «реплики × воркеры × пул» и «реплики × очередь LB на реплику» совпадают + +### Requirement: Рост ресурсов до насыщения + +Серия B SHALL наращивать число реплик 1→2→4→8 с постоянными ресурсами на реплику (1 CPU, 512 MiB, 1 воркер), повышая интенсивность каждой конфигурации, пока два шага подряд не окажутся насыщенными во всех повторах. Шаг SHALL считаться насыщенным, если доля ошибок больше 1 %, сброшенных итераций больше 1 % от предложенных или p95 больше 500 мс. Потолком конфигурации SHALL считаться медиана успешных RPS на наибольшей интенсивности, не насыщенной ни в одном повторе. + +#### Scenario: Точка насыщения обоснована метриками + +- **WHEN** выполняется `make track1-b` +- **THEN** `evidence/track1/series-b/summary.csv` содержит потолок каждой конфигурации, а в каждой строке видны CPU PostgreSQL против его лимита, ожидания блокировок и активные соединения в `pg_stat_activity` против `max_connections` и суммарного пула, очередь и CPU балансировщика; по ним в отчёте названо насыщенное звено + +### Requirement: Графики из сырья + +Оператор SHALL строить графики трека одной командой из файлов `summary.csv` без повторного прогона нагрузки: успешные RPS и p95/p99 от предложенной интенсивности, потолок по конфигурациям, CPU по компонентам. + +#### Scenario: Графики построены + +- **WHEN** выполняется `make plots` +- **THEN** в `evidence/track1/plots/` появляются PNG-файлы: зависимость пропускной способности и задержек от нагрузки, потолок по конфигурациям и CPU по компонентам; точка — медиана повторов, разброс — минимум и максимум + +### Requirement: Подтверждённое улучшение + +Одно улучшение SHALL быть направлено против звена, найденного насыщенным в серии B, и SHALL подтверждаться замером до и после на той же конфигурации, с теми же ресурсами, профилем нагрузки и интенсивностями, не менее 3 повторов на точку. Улучшение SHALL считаться подтверждённым, только если его эффект больше разброса повторов: интервалы «минимум–максимум» до и после не пересекаются по потолку или по p95 на одной интенсивности. Публичные проверки уровней «3» и «4» после улучшения SHALL проходить. + +#### Scenario: До и после на одной конфигурации + +- **WHEN** выполняется `make track1-compare` +- **THEN** `evidence/track1/compare/summary.csv` содержит прогоны «до» и «после» на одинаковых интенсивностях с ≥3 повторами, и по ним видно, на сколько изменились потолок и p95 + +#### Scenario: Улучшение не ломает контракт + +- **WHEN** после внедрения улучшения выполняются `make test`, `make student-test` и `make lint` +- **THEN** все проходят diff --git a/openspec/changes/add-lab3-scaling-cost/tasks.md b/openspec/changes/add-lab3-scaling-cost/tasks.md new file mode 100644 index 00000000..618b54f7 --- /dev/null +++ b/openspec/changes/add-lab3-scaling-cost/tasks.md @@ -0,0 +1,31 @@ +## 1. Стенд под измерения + +- [ ] 1.1 `compose.yaml`: закрепление CPU каждого сервиса через `*_CPUSET` (пусто по умолчанию), `.env.example` +- [ ] 1.2 Проверка группы: `docker compose --profile bench config --quiet`, `make limits` по-прежнему `PASS` + +## 2. Сэмплеры и оркестратор + +- [ ] 2.1 `scripts/docker-stats.sh`, `scripts/lb-stats.sh`, `scripts/pg-stats.sh` (activity, statements, reset, размер базы) +- [ ] 2.2 `scripts/scaling.py`: конфигурация `RxC` с воркерами, пулом, очередью LB на реплику и закреплением CPU; поиск колена с повторами; `summary.csv` и сырьё шага; `probe.py` — ожидание реплик в LB +- [ ] 2.3 `tools/plot_track1.py` и `make plots`; цели `make track1-a`, `track1-b`, `track1-compare`, `track1` +- [ ] 2.4 Проверка группы: `make lint`, `make check`, пробный шаг `scaling.py` на одной интенсивности + +## 3. Серии + +- [ ] 3.1 Снимок `docker stats` всего хоста, версии и лимиты → `evidence/track1/` +- [ ] 3.2 Серия A: 1×4, 2×2, 4×1 при 4 CPU / 2 GiB, ≥3 повтора +- [ ] 3.3 Серия B: 1×1, 2×1, 8×1 (4×1 — из серии A), ≥3 повтора +- [ ] 3.4 Проверка группы: насыщенное звено названо по метрикам `summary.csv` и топу `pg_stat_statements` + +## 4. Улучшение + +- [ ] 4.1 Выбор улучшения по узкому месту серии B, запись в `design.md` +- [ ] 4.2 Реализация улучшения +- [ ] 4.3 `make track1-compare`: до и после на той же конфигурации и интенсивностях, ≥3 повтора +- [ ] 4.4 Проверка группы: `make lint`, `make student-test`, `make test` + +## 5. Отчёт + +- [ ] 5.1 `make plots`, `evidence/track1/README.md` с картой файлов +- [ ] 5.2 `REPORT.md`: раздел трека 1 — гипотезы, методика, таблицы серий, насыщение, улучшение, ограничения, выводы +- [ ] 5.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`