Files
qrtx c3c4c54ec4 docs(report): document lab 3 results and compact benchmark evidence
Describe scaling limits, pool tuning and verified readiness draining. Retain 54 aggregated runs, validation results and two graphs without raw logs or evidence READMEs.
2026-10-29 11:50:49 +03:00

171 lines
29 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: **Пинаев Олег Константинович, БПИ2302**.
- Целевая оценка: **5, трек 1 — цена масштабирования**.
- Версия: API — коммит `24f32c3`, инфраструктура — `676b38c`, проверки — `5c8bcf0`; основа — skeleton `0ab3a34`. Хеши и образы измеренной версии сохранены в [measurements.json](evidence/measurements.json), актуальной проверенной версии — в [checks.json](evidence/checks.json).
- Источники: `README.md`, `COURSE.md`, `contracts/`, документация PostgreSQL, Redis, Node.js и Docker. ИИ использовался при разработке, подготовке проверок, замеров и отчёта.
## Запуск из чистого clone
Нужны Docker с Compose, Python **3.9+**, Node.js **24.20.0**, pnpm **10.14.0**. Образы: `node:24.20.0-bookworm-slim`, `postgres:17.6-bookworm`, `redis:7.4.5-alpine`, `nginx:1.30.6-alpine`. Для графиков используется закреплённый в команде диапазон Matplotlib, для нагрузки — `grafana/k6:1.3.0`.
```sh
cp .env.example .env
pnpm install --frozen-lockfile
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
chmod +x scripts/restart.sh scripts/stop-one.sh
python -X utf8 scripts/collect-report-checks.py --base-url http://127.0.0.1:8080
```
Учебный пароль PostgreSQL заменить в локальном `.env`, сам файл не публиковать. `APP_PORT` задаёт только публичный порт Nginx; в контейнерах API слушает 8080. `POSTGRES_*` — настройки общей БД, `DB_POOL_MAX` — максимум соединений **одной** API, `SESSION_TTL_SECONDS` — срок сессии, `IDEMPOTENCY_TTL_SECONDS` — срок идемпотентности не менее 86400 с, `CACHE_PREFIX` — пространство ключей Redis. Адреса БД и Redis внутри Compose устанавливаются именами сервисов. API не публикуют порты наружу.
Миграции выполняет отдельный сервис `migrate`; API запускаются после успешного завершения миграции и готовности хранилищ, Nginx — после готовности API. Перед HTTP-проверками должны быть healthy обе API и доступен `/health/ready` через Nginx. `/swagger` и `/docs` доступны через тот же LB. На Windows используется `.cmd`-обёртка с Git Bash; при нестандартной установке Git задаётся `GIT_BASH`. В выполненных проверках локальный `.env` задавал порт **18080**, поэтому их команды используют этот порт. Запуск из полностью чистого clone отдельно не проверялся.
Безопасная остановка — `docker compose down`: named volumes остаются. **Намеренное удаление учебных данных** — `docker compose down --volumes`; для обычного перезапуска эту команду не использовать.
## Архитектура и решения
Клиент → **Nginx → NestJS/Fastify × 2 → PostgreSQL**, Redis используется как общий кэш. Из lab2 сохранены пользователи, чаты, членство, Argon2id, Bearer-сессии, cursor-пагинация и согласованность кэша через эпохи. PostgreSQL остаётся источником истины; сессии хранятся в общей таблице, в БД записывается SHA-256 токена. Переключение API не требует повторного входа. Потеря Redis приводит к чтению из PostgreSQL, недоступность БД — к 503.
Новые элементы lab3 — заголовок `X-Instance-Id`, несколько реплик одного Compose-service, общая идемпотентность POST сообщения, балансировка и проверки отказа. `INSTANCE_ID` получает hostname контейнера. `container_name` и sticky sessions не используются.
Идемпотентность хранится в PostgreSQL с уникальным ключом `(user_id, chat_id, key)`. В одной транзакции API резервирует ключ через `INSERT ... ON CONFLICT`, создаёт сообщение, изменяет эпоху истории и связывает ключ с сообщением. Конкурирующий повтор получает то же сообщение; другое содержимое с тем же ключом возвращает 409. После истечения TTL запись удаляется при следующем обращении с этим ключом; фонового удаления всех истёкших записей нет. Счётчик истории разделён на 16 строк; запись и увеличение одного счётчика выполняются одним CTE.
Nginx применяет `least_conn`. Каждый обход получает адреса API из Docker DNS и проверяет `/health/ready` **параллельно**, ограничивая каждый HTTP-запрос одной секундой; после обхода выдерживается пауза 2 с. Backend добавляется после двух успехов и исключается после двух неудач; исчезнувший из DNS адрес удаляется сразу. Сетевые таймауты реплик не суммируются, но DNS, планирование CPU и reload добавляют задержку: пауза 2 с не означает обнаружение за 2 с. Пассивные проверки используют `max_fails=2 fail_timeout=2s`, connect timeout — 2 с, read timeout — 30 с.
Readiness выполняет `SELECT 1`, liveness не обращается к БД. При SIGTERM/SIGINT ранний хук HTTP-адаптера сначала включает **draining**: `/health/ready` возвращает 503 без запроса к БД, `/health/live` продолжает возвращать 200. API ещё 7 с обслуживает обычные запросы, пока Nginx исключает её после двух неудачных проверок. Задержка согласована с двумя параллельными обходами по `(1 с таймаута + 2 с паузы)` и запасом 1 с на обновление upstream; это расчёт для текущих настроек, не гарантия при произвольной нагрузке хоста.
После окна draining Fastify прекращает приём новых соединений и ждёт завершения активных HTTP-запросов. Их ответы на этапе закрытия получают `Connection: close`, чтобы keep-alive не задерживал остановку. Только затем NestJS закрывает Prisma/Redis; повторное начало shutdown не запускает второй таймер и повторное закрытие HTTP. Compose, restart-hook и stop-one-hook дают процессу до 30 с до принудительного завершения. Проверка подключения/SQL ограничена 5 с, транзакции — 10 с. Образ разделён на build/migrate/runtime, API работает от UID/GID 10001.
Обычный профиль — две API по **1 CPU / 512 МиБ**, PostgreSQL — **1 CPU / 512 МиБ**, Nginx — **0,5 CPU / 128 МиБ**, Redis — **0,5 CPU / 256 МиБ**. Пул по умолчанию 15 на API. В исследовании общий бюджет соединений задавался отдельно: по 32/16/8 для 1/2/4 API, до 32 суммарно.
## Доказательства критериев
Повторные проверки выполнены 29.10.2026; команды, длительности, метрики и состояния контейнеров собраны в одном [checks.json](evidence/checks.json).
| Проверка | Команда/сценарий | Результат |
| --- | --- | --- |
| Структура, сборка, линтер | `python scripts/check_contract.py`, `pnpm lint`, `pnpm build` | PASS |
| Публичный smoke | `python -X utf8 tests/smoke.py --base-url http://127.0.0.1:18080` | PASS, включая `X-Instance-Id` и POST с `Idempotency-Key` |
| Общая идемпотентность | `test/idempotency.mjs` через `docker compose run` | PASS: два экземпляра приложения, 12 конкурентных запросов с одним ключом, одинаковое сообщение; другой текст — 409, чужой участник — 404 |
| Полный перезапуск | Публичный `tests/resilience.py --mode persistence` с `scripts/restart.cmd` | PASS, 59,507 с; API/Nginx/PG/Redis действительно перезапущены, контейнеры и volumes сохранены, прежние данные и сессия доступны |
| Публичный отказ | `tests/resilience.py --mode failover` с `scripts/stop-one.cmd` | PASS: до отказа две реплики, 73 успешные записи, 1 неудачная попытка, первая запись после завершения hook за 7,900 с от его запуска |
| Ресурсы и доступ | `test/grade4.py --scenario resources` | PASS: реальные CPU/RAM совпадают с профилем, в снимке контейнеров публичный порт есть только у Nginx, `migrate` завершён с кодом 0 |
| Отказ каждой API | `test/grade4.py --scenario failover --concurrency 4 --observe-seconds 10` | PASS: поочерёдно остановлены обе реплики; прежняя сессия, подтверждённые записи и отсутствие дублей проверены |
| Поочерёдная замена | `test/grade4.py --scenario rolling --concurrency 4 --observe-seconds 10` | PASS: ID обеих API заменены по очереди, трафик продолжался, контейнер миграции не менялся |
| Завершение активного запроса | `node --test --test-reporter=tap test/draining.mjs` | PASS, 2 теста: запрос завершён до закрытия БД, liveness доступен при draining, повторный shutdown идемпотентен, readiness не возвращает запоздалый 200 |
| Пороги readiness Nginx | `test/nginx-readiness.sh`, `test/nginx-readiness-parallel.sh` в изолированных контейнерах | PASS: пороги двух успехов/неудач сохранены, четыре пробы запускаются параллельно |
| SIGTERM и draining | `python -X utf8 test/check_shutdown.py --base-url http://127.0.0.1:18080` | PASS: readiness `200 → 503 → закрыто`; 114 ответов 503 при liveness=200; LB исключил API через 3,282 с при живом HTTP, остановка 9,963 с, exit code 143 без SIGKILL |
| Совместимость миграции | `python -X utf8 test/check_migration_compat.py` | PASS в отдельной временной БД: миграция 28,386 с, 77 записей старого API без ошибок; общая сессия и взаимное чтение старой/новой версии |
| Трек 1 | Матрица 1/2/4 API, рост CPU, квота PG и размер пула | 54 сохранённых прогона, [CSV](evidence/scaling.csv), [агрегаты и диагностика](evidence/measurements.json), рисунки ниже |
Все 16 проверок актуальной версии имеют итоговый PASS. Первый вариант прямого shutdown-теста завершился ошибкой из-за того, что считал клиентские ошибки соединения в парных пробах признаком нездорового HTTP-ответа liveness. В повторе дедлайн проб увеличен с 0,3 до 1 с; HTTP-статусы и транспортные ошибки считаются отдельно. Получены 114 ответов liveness=200 при readiness=503 и ноль транспортных ошибок в этих парах. Неудачная попытка сохранена в `previous_attempts`, хеши прежнего теста — в `source_before_recheck_sha256`. Предыдущие 13 проверок версии без draining, включая историю повтора сохранности, оставлены в компактном `previous_validation`.
Hook полного перезапуска сохраняет число API и volumes, останавливает Nginx/API/PG/Redis, затем поднимает хранилища, API и LB. Hook отказа сопоставляет полученный `TARGET_INSTANCE_ID` с hostname и оставляет именно эту API остановленной. Сборщик доказательств после проверки восстанавливает две реплики.
## Эксперименты и отказы
### Отказ и замена API
Четыре параллельных клиента через LB читают профиль и пишут сообщения; неподтверждённая запись повторяется с исходным ключом. Метрики ниже относятся к окну действия и 10 с наблюдения после него.
| Воздействие | Успешные RPS чтения / записи | Ошибки чтения / записи | Наблюдаемый результат |
| --- | ---: | ---: | --- |
| Остановка первой API | 21,199 / 14,348 | 0 / 0 | После окончания остановки чтение/запись успешны на 8,581 / 8,570 с от начала действия |
| Остановка второй API | 19,580 / 13,140 | 0 / 0 | После окончания остановки чтение/запись успешны на 9,259 / 9,304 с от начала действия |
| Замена первой API | 19,516 / 12,519 | 0 / 2 | Новый контейнер готов через 31,297 с, сохранившаяся реплика отвечала уже через 0,051 с |
| Замена второй API | 18,670 / 12,175 | 0 / 0 | Новый контейнер готов через 24,332 с, сохранившаяся реплика отвечала уже через 0,056 с |
В сценарии отказа проверена 1001 подтверждённая запись, в сценарии замены — 1082; потеря подтверждённых сообщений и дубли не обнаружены. Последний ответ останавливаемой API наблюдался через 4,718 и 5,443 с от начала действия: в окне draining она ещё обслуживала запросы до исключения из LB. Это наблюдение конкретных прогонов, а не теоретическая верхняя граница исключения backend. Время создания нового контейнера не равно времени недоступности сервиса: другая API продолжала обслуживать запросы. Нулевые ошибки двух отказов не означают их отсутствие при любых нагрузках: публичный сценарий и первая замена зафиксировали переходные неудачные попытки.
### Трек 1: цена масштабирования
Гипотеза: дополнительные API при неизменном суммарном бюджете не дают линейного роста, поскольку делят CPU, создают отдельные пулы и используют одну БД. Увеличение нужного ресурса или ограничение невыгодного параллелизма должно улучшать качество.
Генератор и наблюдатели делят ресурсы с приложением. Набор синтетический: новый чат с 30 сообщениями на прогон, первая страница до 50 сообщений, 80% чтений и 20% отправок. Время регистрации/входа не входит в измеряемое окно. База между прогонами не очищалась.
В основной матрице k6 одна итерация равна одному запросу, задан постоянный arrival rate, 128 VU на сценарий, таймаут 5 с, POST без автоматических повторов. Измерение 30 с после 10 с смешанного прогрева. 36 прогонов: 1/2/4 API × общий CPU 1/2 × 40/80 RPS × три повтора. Общая RAM API — 1 ГиБ, общий максимум соединений — 32, PG — 1 CPU / 512 МиБ во всех вариантах. Порядок попарный: `one-small → one → two-small → two → four-small → four`; внутри каждого профиля 40/80 чередуются.
Экспериментальный критерий качества — ошибки ≤1% и **p95 всех запросов ≤1000 мс**. Достаточная подача — 98–102% планового числа начатых запросов и не более 2% пропусков.
| API | CPU суммарно | CPU / RAM одной API | Медиана p95 на 40 RPS, мс | Проход / нарушение / недоподача |
| ---: | ---: | --- | ---: | --- |
| 1 | 1 | 1 / 1024 МиБ | 1363 | 0 / 3 / 0 |
| 2 | 1 | 0,5 / 512 МиБ | 1338 | 0 / 3 / 0 |
| 4 | 1 | 0,25 / 256 МиБ | 808 | 2 / 0 / 1 |
| 1 | 2 | 2 / 1024 МиБ | 751 | 2 / 1 / 0 |
| 2 | 2 | 1 / 512 МиБ | **452** | **3 / 0 / 0** |
| 4 | 2 | 0,5 / 256 МиБ | 1044 | 1 / 2 / 0 |
При фиксированных 2 CPU две API прошли все повторы на 40 RPS, четыре — один из трёх. Рост числа процессов не улучшил качество. Четыре API при 1 CPU дали два прохода.
При увеличении CPU **двух API с 1 до 2** p95 трёх повторов изменился с **1119 / 1757 / 1338** на **777 / 452 / 404 мс**. Все шесть повторов получили достаточную нагрузку, ошибок нет. Медиана p95 снизилась примерно **в 2,96 раза**, медиана максимальной среди API доли throttled-периодов — **18,83 → 1,30%**. Это повторяемое улучшение задержки при прежних RAM, пуле и БД.
На 80 RPS у двух API с общим 1 CPU было 658 / 473 / 499 ошибок, при 2 CPU — 0 / 31 / 0. У четырёх API — 219 / 1 / 101 против 0 / 3 / 0.
![Число реплик, фиксированный бюджет и рост CPU](evidence/scaling.png)
### Ограничение PostgreSQL и увеличение его квоты
Раннее сравнение: четыре API с суммарными 2 CPU / 1 ГиБ, пул по 15, то есть до 60 соединений. Linux Node-генератор через Nginx, 60 заданных RPS, по три повтора по 120 с после 20 с прогрева чтениями. PostgreSQL получил 1 CPU вместо 0,5, RAM осталась 512 МиБ. Облегчённый наблюдатель v3 держал одно постоянное psql-соединение.
| Метрика | PG 0,5 CPU | PG 1 CPU |
| --- | ---: | ---: |
| Средняя загрузка PG, CPU | 0,32–0,39 | 0,32–0,39 |
| Загрузка относительно выделенной квоты | 64–78% | 32–39% |
| Периоды с CPU throttling PG | 33–55% | 3–8% |
| Медиана p95 успешных запросов, мс | 826 | **296** |
| Ошибки за три повтора | 121 | **1** |
| Средние успешные RPS | 52,81 | 53,00 |
| Медиана среднего получения соединения, мс | 23,61 | **1,17** |
При квоте 0,5 CPU среднее потребление ниже лимита, но во время всплесков квота регулярно исчерпывалась. В проблемной области наблюдались ошибки получения соединений и ожидания блокировок записи; четыре API не добавляли ресурсов общей БД. Увеличение CPU базы снизило p95 примерно в 2,8 раза и ошибки при почти одинаковом числе отправленных запросов. Это подтверждает влияние CPU-квоты PG на задержки и надёжность.
Последующий контроль **PG 1 → 2 CPU** выполнен отдельно: две API с общими 2 CPU / 1 ГиБ, пул 32, k6, 80 RPS, одинаковые 30 с смешанного прогрева и 30 с измерения. При 1 CPU получены два прохода и одно нарушение задержки: p95 **793 / 2026 / 744 мс**. При 2 CPU — два недоподанных повтора и один проход: **2122 / 1555 / 713 мс**. Throttling PG исчез, но устойчивого выигрыша не получено. Следовательно, усиление БД после снятия жёсткой квоты не гарантирует дальнейшего роста.
### Ограничение общего числа соединений
Четыре API, PG 1 CPU / 512 МиБ, остальные ресурсы прежние. Сравниваются пулы по 15 и по 8 на API: общий максимум **60 → 32**. Node-генератор, 100 заданных RPS, по три повтора по 60 с после 15 с прогрева чтением.
| Метрика | 60 соединений | 32 соединения |
| --- | ---: | ---: |
| Успешных запросов за 180 с | 13 447 | **14 543** |
| Средние успешные RPS | 74,71 | **80,79** |
| Ошибки | 488 | **4** |
| Ошибки получения соединений | 418 | **0** |
| Медиана успешных RPS повторов | 83,93 | 82,05 |
| Медиана p95 успешных запросов, мс | 289 | 389 |
Средний полезный поток вырос **на 8,15%**, ошибок стало меньше. Однако все 488 ошибок исходного варианта пришлись на один нестабильный повтор, а фактически отправленный поток вырос с 77,42 до 80,82 RPS. Это наблюдаемый выигрыш надёжности и среднего полезного потока, а не доказательство ускорения каждого запроса или увеличения предельного RPS. Ограничение пула согласуется с гипотезой защиты общей БД от невыгодного параллелизма; само увеличение числа соединений производительность не гарантирует.
![Отдельные сравнения CPU API, квоты PG и пула соединений](evidence/improvements.png)
### Исходные данные и повторение
В `evidence/` оставлены **пять файлов**: `checks.json`, `measurements.json`, `scaling.csv`, `scaling.png`, `improvements.png`. JSON содержит 54 прогона из семи исходных серий, их HTTP-агрегаты, p50/p95/p99, CPU/RAM, очереди, SQL-состояния, профили, manifest и хеши исходных результатов. CSV — плоская таблица тех же прогонов. Запросы по отдельности, stdout/stderr, временные ряды, экспериментальные README и дубли рисунков удалены. Ненужные предварительные и отменённые серии в отчёт не включены.
Повтор основной матрицы в отдельный временный каталог:
```sh
python -X utf8 scripts/run-saturation.py --profiles one-small one two-small two four-small four --confirm-rates 40 80 --confirm-seconds 30 --no-expand --output .artifacts/scaling/repeat
python -X utf8 scripts/summarize-scaling-diagnostics.py .artifacts/scaling/repeat
python -X utf8 scripts/audit-saturation.py .artifacts/scaling/repeat
```
После серии runner восстанавливает обычные две API. Варианты исторических сравнений требуют соответствующих квот PG и размеров пулов, записанных в `measurements.json`; их не следует повторять с текущим пулом 8 и выдавать за старый вариант с пулом 15. Инструкции измерителей — в `scripts/diagnostics/`.
Пересчитать CSV и два рисунка из сохранённых данных без новой нагрузки:
```sh
uv run --no-project --with 'matplotlib>=3.9,<4' python scripts/report-evidence.py --plot
```
## Ограничения и следующие шаги
Один Docker-host, одна БД, один Redis и один LB. Проверен отказ и замена API, но не выживание при потере узла PostgreSQL, Nginx или всего ноутбука. Резервирование хранилищ и распределённый кластер не реализованы. Rolling-проверка использовала тот же образ; совместимость схемы lab2/lab3 проверена отдельно, но старая API из lab2 не умеет `Idempotency-Key`, поэтому во время смешанного развёртывания нельзя обещать идемпотентность POST, попавшего на старую версию.
В штатном режиме readiness зависит от ответа PG: краткие задержки базы способны исключить живую API и усилить ошибки. Draining использует 7-секундное окно под текущие параллельные проверки Nginx; при изменении таймаутов, паузы или порогов LB это окно нужно пересогласовать. Активные запросы завершаются в пределах общего 30-секундного бюджета Docker; бесконечно долгие запросы этот бюджет не продлевают. Чистый bootstrap на другой машине и под другим Docker-окружением не проверен. Нагрузочные сравнения не повторялись после добавления draining: их данные относятся к прежнему образу, проверки остановки и отказов — к актуальному.
Итог исследования: две API — устойчивый рабочий вариант при текущем бюджете; увеличение их CPU улучшило задержки, усиление PG с 0,5 до 1 CPU улучшило работу зависимого пути, ограничение соединений сопровождалось снижением ошибок. Дальнейший рост реплик, пула или квоты PG сам по себе выигрыша не гарантирует. Следующий шаг для уточнения границы — независимый генератор или больший запас хоста и чередование вариантов с достаточной фактической подачей.