From d8d551aae40aacbed0599be18e44092d3c67c0fd Mon Sep 17 00:00:00 2001 From: Artyom Date: Wed, 28 Oct 2026 20:16:19 +0300 Subject: [PATCH] Propose the scaling cost track as an openspec change Track 1 of grade 5 asks to compare one, two and four API replicas at a fixed total CPU and memory budget, to grow resources until a shared dependency saturates, to show with database, balancer and pool metrics why more replicas stop helping, and to confirm one improvement with a before and after measurement. The hypotheses are stated before any run: at 4 CPU / 2 GiB the 1x4, 2x2 and 4x1 layouts reach the same ceiling within 15 percent; with one CPU per replica throughput grows almost linearly up to four replicas and by less than 1.5 times from four to eight, because PostgreSQL saturates on the chat row lock held across three round trips and on CPU, while the balancer stays far from its limit. The new lab3-scaling-cost capability fixes the method: open-model k6 with the level 4 profile, three repeats per point, equal workers, pool and balancer concurrency across layouts, CPU pinning per component, raw samples per step, plots from summary files, and an improvement chosen only after the bottleneck is found. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../add-lab3-scaling-cost/.openspec.yaml | 2 + .../changes/add-lab3-scaling-cost/design.md | 48 ++++++++++++++ .../changes/add-lab3-scaling-cost/proposal.md | 37 +++++++++++ .../specs/lab3-scaling-cost/spec.md | 65 +++++++++++++++++++ .../changes/add-lab3-scaling-cost/tasks.md | 31 +++++++++ 5 files changed, 183 insertions(+) create mode 100644 openspec/changes/add-lab3-scaling-cost/.openspec.yaml create mode 100644 openspec/changes/add-lab3-scaling-cost/design.md create mode 100644 openspec/changes/add-lab3-scaling-cost/proposal.md create mode 100644 openspec/changes/add-lab3-scaling-cost/specs/lab3-scaling-cost/spec.md create mode 100644 openspec/changes/add-lab3-scaling-cost/tasks.md 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`