Files
mtusi2026lab3/REPORT.md
T

18 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Койчакаев Багавдин, БВТ2301.
  • Целевая оценка: 5; законченный трек: 1 — цена масштабирования.
  • Состав реализации: API ЛР2, HAProxy, минимум две API-реплики, общие PostgreSQL и Valkey, конкурентная идемпотентность в PostgreSQL.
  • Внешние источники: контракт и материалы курса. Использованы Python 3.12.8, psycopg 3.2.3, argon2-cffi 23.1.0, redis-py 5.2.1; при подготовке использовался Codex.

Запуск

cp .env.example .env
# задайте POSTGRES_PASSWORD и CURSOR_SECRET (случайный ключ минимум 32 байта)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 180
make check
make validate
make test BASE_URL=http://127.0.0.1:8080
make test-idempotency BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080

Приложение слушает только внутреннюю сеть Compose. Единственный опубликованный порт — loopback порт HAProxy 8080. Миграции запускает одноразовый сервис migrate перед API, под advisory lock PostgreSQL. Первая схема сохраняется совместимой с базой ЛР2; миграция 002_idempotency добавляет таблицу ключей и индекс срока хранения.

Архитектура и решения

HTTP client → HAProxy :8080 → API × 2+ → PostgreSQL (messages, sessions, idempotency)
                              ↘ общий Valkey (TTL lookup hint; PostgreSQL остаётся источником истины)

HAProxy round-robin балансирует запросы между адресами DNS api, повторно разрешая адрес каждые 2 секунды. Проверка GET /health/ready выполняется раз в секунду; две ошибки исключают backend, два успеха возвращают его. Connect timeout — 1 секунда, timeout ожидания/ответа — 10 секунд. API слушает 0.0.0.0:8080 внутри сети и на SIGTERM прекращает serve_forever; Compose ждёт до 10 секунд для штатного завершения.

Сессия проверяется PostgreSQL на каждом запросе; значение Valkey лишь ускоряет lookup и не авторизует пользователя без живой строки в PostgreSQL. Общий CURSOR_SECRET нужен, чтобы cursor истории, созданный одной репликой, принимался другой. Секрет и пароль БД находятся только в локальном .env, игнорируемом Git и Docker build context.

Для каждого POST сообщения обязателен ключ [A-Za-z0-9._:-]{1,128}. Уникальная область — пользователь, метод, путь чата и ключ; body хешируется после нормализации JSON, а пропущенный attachment_ids равен []. pg_advisory_xact_lock сериализует одновременные запросы одной области во всех API-процессах; PostgreSQL хранит отпечаток body и точный JSON результата вместе с сообщением в одной транзакции. Совпавший запрос возвращает тот же 201 и Message; отличающийся body — 409; запись можно использовать заново спустя 24 часа. Ошибка/откат транзакции не оставляет частично зарегистрированный ключ. Каждый API-ответ включая ошибку содержит непустой X-Request-Id и идентификатор процесса в X-Instance-Id.

Роли и версии

Роль Service Версия Health/volume/порты
API api (Compose scale) Python 3.12.8 slim Bookworm, pinned digest в Dockerfile /health/ready, без host-порта, без локального состояния
Балансировщик haproxy 3.0.8 Alpine HAProxy backend checks, единственный порт 127.0.0.1:8080
База postgres 16.4 Bookworm pg_isready, общий volume postgres_data, внутренний порт 5432
Кэш сессий valkey 8.0.1 Alpine PING, volume valkey_data, AOF everysec, внутренний порт 6379
Миграции migrate тот же образ API одноразовый контейнер; выполняется до запуска реплик

CPU/RAM limits заданы в compose для API, HAProxy, PostgreSQL и Valkey. api не имеет container_name, поэтому штатное горизонтальное масштабирование поддерживается.

Проверки уровня 3 и 4

Публичный smoke проверяет обязательный API через HAProxy. Дополнительный параллельный тест запускает 32 запроса с одним ключом и одним body одновременно; все ответы вернули один ID сообщения, наблюдались две реплики. Persistence-сценарий перезапустил API, HAProxy, PostgreSQL и Valkey без удаления volumes; тот же Bearer-токен прочитал те же данные. Три failover-прогона остановили API-реплику по очереди и повторили сценарий после восстановления. Каждый наблюдал две реплики до отказа; новые записи восстановились за 2,902 с, 1,543 с и 1,447 с; ошибок было 0 во всех трёх прогонах (113, 125 и 114 успешных записей); сообщение до отказа и все подтверждённые записи остались доступны, дубли отсутствовали. В конце теста остановленная реплика оставалась остановленной; Compose восстановил её перед следующим прогоном и после финальной проверки.

Rolling replacement под нагрузкой выполняется скриптом scripts/rolling-update.sh: пул сначала увеличивается до трёх, затем контейнеры заменяются по одному с сохранением активного backend. Под нагрузкой 60 секунд, concurrency 16: 50 291 успешная запись (836,949 RPS), 24 ошибки из 50 315 запросов (0,048%), p50/p95/p99 = 6,118/55,938/85,729 мс. После завершения пул восстановлен до двух здоровых реплик. Метрики сохранены в evidence/rolling-update-load.json; успешность запросов при замене не абсолютная, что отражено в ограничениях.

Трек 1 — цена масштабирования

Гипотеза. При равном суммарном CPU/RAM перенос ресурса с одного API на несколько реплик улучшит RPS только до насыщения общей PostgreSQL или пула соединений. При фиксированной мощности на реплику добавление API в какой-то момент перестанет повышать throughput; увеличение пула сверх полезного уровня добавит конкуренцию за БД, а не пропускную способность.

Методика. scripts/track1_experiment.py пересоздаёт API при каждом профиле, ждёт readiness и 5 секунд стабилизации, затем трижды измеряет закрытый цикл POST-сообщений по 30 секунд с concurrency 16. Перед каждым sample очищаются только учебные таблицы messages и idempotency_keys, затем выполняется ANALYZE; порядок вариантов перемешивается детерминированным seed. Сессии/пользователи остаются в PostgreSQL. Фиксированный бюджет: 2 vCPU и 1 GiB RAM суммарно для API, разделённые между 1/2/4 репликами. Серия роста: 0,5 vCPU и 256 MiB на реплику для 1/2/4/8 реплик. Отдельное сравнение при четырёх репликах меняет DB_POOL_MAX 5/10/20. PostgreSQL ограничен 2 CPU и 1 GiB; HAProxy — 0,25 CPU и 128 MiB. Записываются успешные RPS, ошибки, p50/p95/p99, CPU/RAM компонентов и число сообщений. Сводки и исходные данные — evidence/track1-results.json, график — evidence/track1-rps.svg.

Чтобы определить точку насыщения, scripts/track1_offered_load.py подаёт фиксированный поток 250/500/750/1000 POST RPS на восемь API-реплик (0,5 CPU / 256 MiB каждая) по три раза в перемешанном порядке; HTTP-клиент переиспользуется в потоках, число in-flight ограничено, Docker stats во время нагрузочного окна не опрашивается. Throughput рассчитан по фактическому времени вместе с drain. Затем scripts/track1_offered_scale.py делает три парных прогона 8/12 реплик при предложенных 1000 RPS. Между повторами масштабирование возвращается к восьми репликам, чтобы освободить DB-соединения до очистки синтетических таблиц. Все исходные измерения лежат в evidence/offered-load-results.json и evidence/offered-scale-results.json; график rate sweep — evidence/offered-load.svg.

Профиль Реплики Пул/реплика медиана RPS (min–max) медиана ошибок p50/p95/p99, ms API CPU mean/peak, % API RAM peak, MiB
fixed-1 1 10 418,5 (389,7–456,3) 0,017% 32,3/53,0/82,4 174,3/190,2 61,9
fixed-2 2 10 698,6 (653,6–749,2) 0% 8,0/62,4/92,9 74,0/109,5 60,9
fixed-4 4 10 837,7 (590,7–900,3) 0,007% 5,2/57,5/101,9 38,2/53,3 62,4
scaled-1 1 10 103,7 (102,1–108,8) 0,064% 111,1/313,3/484,9 47,8/53,3 83,5
scaled-2 2 10 274,6 (244,8–276,3) 0,048% 22,9/183,7/290,4 37,6/52,9 140,0
scaled-4 4 10 680,7 (635,3–875,7) 0% 6,0/71,0/123,1 40,8/53,2 79,2
scaled-8 8 10 764,2 (655,4–787,6) 0% 9,5/70,6/111,2 29,0/50,1 82,0
pool-5 4 5 921,2 (837,9–1061,3) 0,003% 5,3/49,2/89,8 40,4/53,3 62,6
pool-10 4 10 808,9 (611,5–969,2) 0,020% 5,5/66,7/108,3 38,9/51,9 99,5
pool-20 4 20 951,3 (573,5–1044,2) 0,003% 5,4/45,3/89,2 41,7/52,5 63,1

Среда: macOS 26.5.1 arm64, 8 host CPU; Docker Engine 29.8.2; Docker VM 8 CPU / 4 106 605 444 байта RAM (~3 918 MiB); Python клиента 3.14.6; Python API 3.12.8; PostgreSQL 16.4. Закрытая серия длилась 30 секунд, rate-controlled серия — 15 секунд на sample. Во всех замерах JSON фиксирует размер синтетических таблиц; перед sample messages и idempotency_keys очищались, остальные пользовательские данные сохранялись. Closed-loop percentiles подвержены coordinated omission; rate-controlled серия имеет короткие окна и оценивает только эту среду. Все результаты ограничены одним Docker-host; потеря узла одновременно затрагивает API, HAProxy, PostgreSQL и локальные volumes.

Предложено, RPS Медиана успешных RPS (min–max) Медиана ошибок Медиана p95, ms
250 249,6 (249,6–250,0) 0% 9,9
500 499,6 (419,6–499,9) 0% 41,6
750 745,9 (693,2–748,7) 0,018% 100,9
1000 810,1 (553,2–879,3) 2,753% 1 611,3

Парное сравнение при 1000 предложенных RPS:

API-реплик Успешные RPS, медиана (min–max) p95, медиана, ms Ошибки POST за 3 повтора Диагностика PostgreSQL
8 727,0 (584,4–851,5) 1 504,7 874 / 45 000 SELECT прошёл
12 555,8 (546,0–774,9) 1 986,4 12 / 45 000 Все 3 запроса отклонены: too many clients already

Поиск насыщения и улучшение. В rate-controlled серии 250 и 500 предложенных RPS полностью принимались без ошибок (медианный p95 9,9 и 41,6 мс). При 750 RPS медиана успешной пропускной способности составила 745,9 RPS, p95 — 100,9 мс. При 1000 RPS throughput вырос лишь до 810,1 RPS, медианная доля ошибок достигла 2,75%, а p95 — 1 611 мс. Это показывает knee общей цепочки между 750 и 1000 RPS; повторяемость ограничена тремя короткими прогонами, поэтому это не универсальная производственная ёмкость.

Компонентное ограничение установлено отдельной проверкой DB-пула. При DB_POOL_MAX=10 восемь реплик могут открыть до 80 соединений, а двенадцать — до 120. Фактический max_connections PostgreSQL равен 100. В трёх прогонах с 12 репликами и нагрузкой 1000 RPS, помимо роста задержки, PostgreSQL трижды отказал даже в диагностическом SELECT с FATAL: sorry, too many clients already; после возврата к восьми репликам запросы к БД снова проходили. Наблюдение сохранено в evidence/db-saturation-observation.txt, а метрики сравнения — evidence/offered-scale-results.json. Таким образом, насыщение пула/БД возникает между восемью и двенадцатью репликами при текущем лимите пула; дальнейшее увеличение API без снижения размера пула или повышения DB connection budget ухудшает доступность общих соединений. 8→12 RPS-диапазоны перекрываются, поэтому причинный вывод основан на подтверждённом исчерпании connection slots, а не только на падении медианного throughput.

Подтверждённое улучшение при фиксированном суммарном бюджете 2 vCPU / 1 GiB: переход fixed-1→fixed-2 поднял медиану с 418,5 до 698,6 RPS (+66,9%); диапазоны трёх повторов не пересекаются (389,7–456,3 и 653,6–749,2 RPS). p50 снизился с 32,3 до 8,0 мс, p95 изменился с 53,0 до 62,4 мс. Серии DB_POOL_MAX=5/10/20 при низкой конкуренции и HAProxy 0,25/0,5 CPU имеют перекрывающиеся диапазоны; их эффект не заявляется как отдельное улучшение. Все измерения ограничены одной Docker VM и конкретным синтетическим профилем.

Результаты и ограничения

Офлайн структурная проверка, API smoke, гонка идемпотентности, перезапуск и failover пройдены; подробный stdout сохранён в evidence/lab3-checks.txt. Полная OpenAPI/JSON Schema проверка требует openapi-spec-validator==0.7.2 из requirements-dev.txt; установить зависимость в этой среде не удалось из-за недоступного DNS PyPI. HTTP используется только на loopback для синтетических данных. Эта схема выдерживает отказ одного API-процесса при работающих HAProxy, host, PostgreSQL и Valkey; она не выдерживает потерю Docker-host, HAProxy или PostgreSQL. При отказе Valkey действующие сессии проверяются по PostgreSQL. Отдельной HA базы данных и второго узла нет. Под нагрузкой при rolling replacement замерены 24 ошибки на 50 315 запросов (0,048%); для повторения именно операции создания сообщения клиент должен повторить запрос с тем же Idempotency-Key. Другие POST-операции не обещают прозрачную идемпотентность.