feat: coordinate timeout chain and add failover load profile

HAProxy checks get fastinter 500ms and timeout check 2.5s (hung replica
detected within 6.5 s), http-reuse never with uvicorn keep-alive 60 s so
the LB closes idle replica connections, and app connections set
idle_in_transaction_session_timeout so a frozen replica releases its
idempotency key. The bench stand runs behind HAProxy with N replicas and
gains the failover profile (make bench_failover / bench_failover_quick):
constant-rate writes with a key and reads while each replica is stopped,
killed or paused, with per-second timeline, detection and recovery time
and write reconciliation. Driver commands idle-conns and hang-key check
the keep-alive and hung-transaction decisions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-10 23:21:12 +03:00
co-authored by Claude Opus 5.5
parent b76a666621
commit 459f84c75c
25 changed files with 2400 additions and 269 deletions
+36 -12
View File
@@ -93,25 +93,44 @@ paths:
## Цепочка таймаутов
Числа живут в конфигах и в таблице `REPORT.md`. Правило — соотношения
между ними:
Числа живут в конфигах и в таблице `REPORT.md`, обоснование каждого
звена — design change `graceful-failover`, решение 1. Правило —
соотношения между ними:
- худшее время обнаружения отказа ≤ 10 с (рубрика «3»: «не позднее
10 секунд»). HAProxy начинает следующую проверку через `inter` после
конца предыдущей, поэтому для зависшей реплики (соединение есть,
ответа нет) худшее ≈ `fall × (inter + timeout check)`, а не `inter ×
fall + timeout check`: при 1 с / 2 / 3 с — 8 с, замер `docker pause` —
7,3–7,7 с (change `replicas-lb`). Остановленную реплику проверка не ждёт:
отказ соединения сразу или `timeout connect`, пропавший адрес DNS
убирает за 1–2 с. В `REPORT.md` — и формула, и замер по режимам
(change `graceful-failover`);
10 секунд»). HAProxy начинает следующую проверку через интервал после
конца предыдущей, а после первой неудачи — через `fastinter`. Поэтому
для зависшей реплики (соединение есть, ответа нет) худшее — `inter +
timeout check + (fall − 1) × (fastinter + timeout check)`: при 1 с /
2,5 с / 0,5 с / `fall 2` — 6,5 с (было 8 с без `fastinter` и с 3 с;
замер `docker pause` change `replicas-lb` — 7,3–7,7 с). Пропавший
адрес (`stop` после выхода, `kill`) проверка ждёт не дольше таймаута
соединения проверки min(`timeout connect`, `inter`) = 0,5 с: худшее
2,5 с, а DNS уводит слот в обслуживание за 1–2 с. Замер по режимам —
профиль `failover` (`bench.md`), в `REPORT.md` — формула и замер;
- `timeout connect` × (`retries` + 1) < 2 с: таймаут клиента в
`tests/resilience.py` — 2 с, и повтор на живую реплику должен успеть
раньше. Поэтому `timeout connect` 500 мс, а не 1 с, и `redispatch 1`;
- `timeout server` > `[database] request_timeout_seconds` + запас на
KDF входа, иначе LB рвал бы ответ, который API ещё отдаст;
- таймаут проверки внутри `/health/ready` < `timeout check` HAProxy
(`infra.md`);
- таймаут проверки внутри `/health/ready` (2 с) < `timeout check`
HAProxy (2,5 с, `infra.md`): медленный PostgreSQL даёт 503 от реплики,
а не таймаут проверки. Уменьшать таймаут готовности ради быстрого
обнаружения нельзя: проверка берёт соединение из общего пула, и заминка
PostgreSQL вывела бы из LB все реплики разом;
- простаивающее соединение LB → реплика закрывает LB, а не реплика.
`http-reuse never`: соединение с репликой не уходит в общий пул и
живёт, пока жив сеанс клиента, а простаивающий сеанс LB закрывает по
`timeout http-keep-alive` (10 с). `[app] keep_alive_seconds` (60 с,
`timeout_keep_alive` uvicorn) больше. Иначе LB может отправить запрос
в соединение, которое реплика в этот момент закрывает, и клиент
получит 502 (`empty-response` LB не повторяет). С пулом (`http-reuse
safe`, по умолчанию) LB держал последнее простаивающее соединение,
пока его не закрывала реплика. Проверка — `driver.py idle-conns`;
- `[database] idle_in_transaction_timeout_ms` (10 с) >
`request_timeout_seconds` (6 с): PostgreSQL прерывает только
транзакцию замороженного процесса и снимает её блокировки, в том числе
ключа идемпотентности (`infra.md`). Проверка — `driver.py hang-key`;
- `[app] graceful_shutdown_seconds` < `stop_grace_period` (8 < 10,
`run-modes.md`).
@@ -154,6 +173,11 @@ Hook для `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
повторяет) — `driver.py --port 8080 kill-inflight` скилла
`run-mtusi-messenger`: входы по Basic в полёте и kill реплики через
этот hook.
- Отказ каждой реплики под постоянной нагрузкой (рубрика «4»: RPS,
ошибки, время восстановления) — не этот hook, а профиль `failover`
стенда `bench/` (`make bench_failover`, `bench.md`): свой проект
compose, `docker stop` / `kill` / `pause` реплики и возврат, шкала по
секундам в `evidence/failover/<метка>/`.
## Свои цели Makefile
+70 -13
View File
@@ -36,13 +36,14 @@ paths:
остановка реплик, посекундные RPS и ошибки) и `rollout` (та же
нагрузка во время `scripts/rolling-update.sh`).
Что меняется (стенд — change `graceful-failover`, нагрузка, метрики и
графики — change `scaling-bench`; до них стенд с одним API):
Что меняется (стенд и профиль `failover` — change `graceful-failover`,
сделано; нагрузка, метрики и графики трека 1 — change `scaling-bench`):
- **стенд:** тот же compose с HAProxy и N репликами `api` вместо
одного контейнера; при N = 1 профили лабы 2 работают как раньше.
Число реплик, их лимиты и лимиты HAProxy и генератора — поля
`Profile`, в паспорт;
Число реплик (`replicas`), их лимиты и лимиты HAProxy (`lb_cpus`,
`lb_memory`) — поля `Profile`, в паспорт; лимит генератора — ещё
предстоит (`scaling-bench`);
- **нагрузка:** открытая модель (`ramping-arrival-rate` ступенями до
нарушения SLO, плюс фиксированные уровни), один смешанный профиль
для всех конфигураций. Вход по Basic — до прогона, не в замере;
@@ -59,14 +60,26 @@ paths:
базовый замер снимается заново. Профили лабы 2 (`full`, `restore*`)
продолжают работать и после перехода на N реплик.
До `graceful-failover` override `bench/bench.compose.yml` держит один
API: у `api` `deploy.replicas: 1` и `container_name` (k6 ходит к нему
по имени), `haproxy` не запускается (`up -d --no-deps api`), его порт
сброшен. Лимиты `api`, `postgres` и `valkey` — в форме
`deploy.resources.limits` с теми же `BENCH_*` (основной compose задаёт
лимиты так же, и `cpus` / `mem_limit` рядом с ними compose не
принимает); `memswap_limit` — на уровне сервиса. `NanoCpus` и `Memory`
контейнеров при этом те же, метки сравнимы.
Стенд с LB (design change `graceful-failover`, решение 6):
- override `bench/bench.compose.yml`: у `api` нет `container_name`,
`deploy.replicas: ${BENCH_API_REPLICAS}`, лимиты `BENCH_APP_*` — на
каждую реплику; у `haproxy` — `container_name: mtusi-bench-haproxy`
(он один), лимиты `BENCH_LB_*`, порт сброшен, конфиг — тот же
`infra/haproxy/haproxy.cfg`. Лимиты всех — в форме
`deploy.resources.limits` (`cpus` / `mem_limit` рядом с ними compose не
принимает), `memswap_limit` — на уровне сервиса;
- k6 ходит на `http://haproxy:8080` (имя сервиса в сети `mtusi-bench`,
`lib.js`), не к реплике напрямую — и при N = 1: серии трека 1
сравнивают 1, 2 и 4 реплики на одном пути запроса;
- `run.py` находит реплики через `docker compose ps api`. Стенд готов,
когда LB видит `UP` все N реплик по их адресам (статистика LB изнутри
контейнера LB). CPU, память и RSS приложения в метриках — сумма по
репликам (`VmHWM` — максимум), при N = 1 — числа её процесса;
- healthcheck образа у реплик выключен, но реплику раз в секунду
проверяет LB (`SELECT 1` в квоте API). Вместе с LB в пути запроса это
смена методики относительно лабы 2: метки лабы 3 до этого change (их в
git нет) и метки лабы 2 с новыми не сравниваются.
Стенд — свой проект compose `mtusi-bench`: тот же `docker-compose.yml`
с override `bench/bench.compose.yml` (по образцу `make failure_checks`),
@@ -74,12 +87,13 @@ API: у `api` `deploy.replicas: 1` и `container_name` (k6 ходит к нем
хранилищ `run.py` генерирует на прогон и никуда не пишет. Каждый размер —
свежий стенд: `down -v`, Postgres и Valkey, миграции, API.
В `bench/` четыре инструмента:
Инструменты `bench/`:
| Файл | Команда | Что делает |
|---|---|---|
| `run.py`, `k6/`, `bench.compose.yml`, `bench.env` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки, CPU API и Postgres, память, снимает планы запроса истории |
| `run.py` (профили `restore`, `restore_quick`), `k6/after_backup.js`, `k6/restore_check.js` | `make bench_restore`, `make bench_restore_quick` | тот же стенд без матрицы прогонов: backup под записью, восстановление в новое хранилище, сверка, RTO и потеря, кэш до и после `FLUSHALL` |
| `run.py` (профили `failover`, `failover_quick`), `failover.py`, `k6/failover.js`, `k6/retry.js` | `make bench_failover`, `make bench_failover_quick` | две реплики с лимитами рабочего стенда, постоянная интенсивность записи с ключом и чтения, каждая реплика в каждом режиме (`stop`, `kill`, `pause`) с возвратом: посекундная шкала, время обнаружения и восстановления, сверка записей; результаты — `evidence/failover/<метка>/` |
| `compare.py` | `make bench_compare` | дельта двух меток стенда, эффект или шум |
| `ab.py` | `make bench_ab` | стенд «до» и «после» одного изменения подряд, в одной сессии хоста |
@@ -138,6 +152,49 @@ API: у `api` `deploy.replicas: 1` и `container_name` (k6 ходит к нем
перестают быть «до», базовый замер переснимается, а в `REPORT.md`
записывается, что и почему поменялось.
## Профиль отказа реплик (`failover`)
Доказательство уровня 4 «поочерёдная остановка каждой реплики: RPS,
ошибки, время восстановления» (design change `graceful-failover`,
решения 5 и 7). Матрицу лабы 2 он не снимает и с её метками не
сравнивается.
- Лимиты — как у рабочего стенда `docker-compose.yml` (API 1 CPU /
512 МБ на реплику, две реплики, PostgreSQL 2 CPU / 1 ГБ, Valkey
0,5 CPU / 128 МБ, HAProxy 1 CPU / 256 МБ): профиль отвечает, что видит
клиент `make run_docker` при отказе реплики. Читаемый чат —
1 000 сообщений, без фоновых.
- Нагрузка — k6 `constant-arrival-rate`: 100 записей с ключом
`<прогон>.<фаза>.<n>` и 100 чтений страницы истории в секунду, около
половины потолка одной реплики. Фаза — режим × реплика: окно до
действия, `docker stop --timeout 9` / `docker kill` / `docker pause`,
окно отказа, `docker start` того же контейнера или `docker unpause`,
окно после возврата. Перед фазой LB видит обе реплики `UP`.
- Все отметки — часы ВМ Docker: действие и возврат — события Docker
(`docker events`), исключение и возврат в LB — строки журнала HAProxy
(`docker logs -t`), запросы — `Date.now()` k6 при отправке. Часы хоста
с ними не сравниваются.
- Каждый запрос — строка `fo,…` в файл консоли k6 (`--console-output`),
а не в вывод `docker exec`: там в самопроверке пропали две строки из
4 601. Число строк сверяется с итерациями сценариев из итога k6,
расхождение — отказ.
- VU k6 создаются заранее с запасом под зависшую реплику
(`failover_pre_vus` 600 на сценарий: половина запросов ждёт 504 10 с).
Иначе k6 создаёт их на ходу и пропускает итерации, и интенсивность
перестаёт быть постоянной; пропуски — `dropped_iterations` и пометка
`dropped`.
- После фазы каждая неуспешная запись повторяется с тем же ключом и
телом до 201 (`k6/retry.js`), затем `psql` стенда: сообщений в чате
записи и разных текстов столько, сколько отправлено ключей. Это
доказательство «без потерь и дублей», расхождение — отказ.
- Превышение формулы обнаружения — пометка `over_bound` в
`phases.csv`, а не отказ: это результат, а не сбой стенда.
- Результаты — `evidence/failover/<метка>/` (`meta.json`, `phases.csv`,
`timeline.csv`, `summary.md`, `raw/<фаза>-k6.json`,
`raw/<фаза>-lb.log`), пробные `quick-failover-*` — в `.gitignore`.
Профиль замера для отчёта — `make bench_failover` после проверки хоста
(раздел «Результаты»), рабочий стенд на время замера остановлен.
## Как писать
- Стенд — чёрный ящик: `run.py`, `k6/` и `compare.py` не импортируют
+11
View File
@@ -41,6 +41,17 @@ paths:
(psql, стенд `bench/`) не больше `max_connections` Postgres (по
умолчанию 100). Расчёт для заявленного числа реплик — в `REPORT.md`;
граница пула — одна из гипотез трека 1 (`PLAN.md`).
- `idle_in_transaction_session_timeout` — серверная настройка соединений
приложения (`server_settings`, рядом с `statement_timeout`) из
`[database] idle_in_transaction_timeout_ms` (10 с; 0 — не задаётся).
Замороженный процесс (`docker pause`, зависание) держит открытую
транзакцию бесконечно: его TCP-соединение живо, keepalive ничего не
замечает. Без этой настройки строка ключа идемпотентности, которую он
вставил, оставалась бы заблокированной до разморозки, и повтор того же
ключа через другую реплику получал бы 503 снова и снова. Значение
больше `request_timeout_seconds` (валидатор `Database`): транзакция
живого запроса дольше не живёт, `get_db_session` закрывает соединение
по сроку (design change `graceful-failover`, решение 4).
- `command_timeout` asyncpg не использовать: на таймауте он отменяет
запрос через новое соединение и ждёт сервер без срока, и замёрзший
Postgres держит запрос до разморозки. Срок запроса ставит
+15 -2
View File
@@ -29,7 +29,8 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл
`python -m src` → `src/__main__.py` → `src.main:main()` →
`uvicorn.run("src.main:app", host=..., port=..., reload=...,
timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
timeout_graceful_shutdown=..., timeout_keep_alive=..., log_config=None,
access_log=False)`.
Хост выбирается по режиму, как в bp_proxies. `log_config=None` нужен,
чтобы uvicorn не перетёр JSON-логирование (`logging.md`).
@@ -46,7 +47,19 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
Рубрика уровня 4 требует завершения не дольше 10 с. С лабы 3 закрытый
сокет остановленной реплики HAProxy видит как отказ соединения и
перенаправляет запрос на живую; новые запросы на неё перестают идти
после проваленных проверок (`balancer.md`, цепочка таймаутов).
после проваленных проверок (`balancer.md`, цепочка таймаутов). Под
нагрузкой `docker stop` реплики ошибок от её недоступности не даёт —
замер профиля `failover` (`bench.md`).
- Keep-alive: uvicorn держит простаивающее соединение
`[app] keep_alive_seconds` (60 с, `timeout_keep_alive`), а не 5 с по
умолчанию. Тогда простаивающее соединение LB → реплика закрывает LB
раньше реплики (`balancer.md`, цепочка таймаутов). При SIGTERM uvicorn
закрывает простаивающие соединения сразу. Запрос, который LB отправил
в такое соединение в тот же миг, получает 502: под нагрузкой
200 запросов в секунду — одиночный 502 в каждой 4–8-й фазе `stop`
профиля `failover`. Клиенты с новым соединением на запрос
(`tests/resilience.py`) его не встречают. Убрать его может только
дренаж перед SIGTERM (readiness 503, затем остановка) — его нет.
- Console-режим — один процесс на `127.0.0.1` без LB, для разработки и
скилла `run-mtusi-messenger`. Проверки лабы 3 (≥2 реплики, failover,
гонка через разные реплики) — только на стенде compose через LB.
+5 -3
View File
@@ -70,9 +70,11 @@ paths:
значение, через LB каждое значение повторяется, и вторая серия не
приносит новых. Опирается на round-robin LB.
Проверки отказов реплик (остановка, kill, rolling update) — не pytest,
а `make test-failover` и сценарии `balancer.md`: им нужен стенд с LB и
действие над контейнерами.
Проверки отказов реплик (остановка, kill, зависание, rolling update) —
не pytest, а `make test-failover`, профиль `failover` стенда `bench/`
(`make bench_failover`, `bench.md`), команды драйвера `kill-inflight`,
`hang-key` и сценарии `balancer.md`: им нужен стенд с LB и действие над
контейнерами.
## Как писать
+9 -2
View File
@@ -13,8 +13,10 @@ FastAPI/uvicorn, данные в PostgreSQL из compose, карточки ча
останавливает сервер. Против стенда compose (`make run_docker`:
HAProxy на `APP_OUT_PORT` перед репликами API) работают те же команды
драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной
сессии по репликам и `kill-inflight` — kill реплики с запросами в
полёте. Только стандартная библиотека Python.
сессии по репликам, `kill-inflight` — kill реплики с запросами в
полёте, `idle-conns` — кто закрывает простаивающие соединения LB →
реплика и `hang-key` — повтор ключа после зависшей реплики. Только
стандартная библиотека Python.
Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12,
Python 3.12 из `.python-version`, Docker Desktop 29.8.
@@ -88,6 +90,8 @@ python3 $D stop
| `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); против своего процесса (есть pid-файл) — с `EXPECT_REPLICAS=1`, тесты реплик пропускаются с причиной; код 1, если каталога нет |
| `instances [--count N]` | вход одним синтетическим пользователем, N (12) × `GET /api/v1/users/me` с одним токеном: `X-Instance-Id` каждого ответа и число ответов каждой реплики; токен не печатается. Его зовёт `make instances` |
| `kill-inflight [--threads 8] [--seconds 4] [--after 1.5]` | только стенд с LB (`--port 8080`): потоки входят по Basic, через `--after` с `scripts/stop-one.sh` в режиме kill убивает реплику пробного запроса. Печатает статусы по репликам и ответы LB: оборванные входы — 502 в формате контракта без повтора, начатые после kill — 201 от другой реплики. Код 1, если оборванных нет. Реплика остаётся остановленной — `make replicas` |
| `idle-conns [--threads 20] [--requests 50] [--keep-alive 60]` | только стенд с LB: всплеск `GET /health/live` через LB с keep-alive соединениями, клиенты остаются подключены и молчат; раз в секунду — установленные соединения на порт API внутри каждой реплики (`/proc/net/tcp`) и пул LB (`idle_conn_cur` + `safe_conn_cur`). Код 0, если реплики остались без соединений раньше `--keep-alive` (`[app] keep_alive_seconds`): закрыл LB по своему `timeout http-keep-alive`, а не реплика |
| `hang-key` | только стенд с LB: временный триггер задерживает вставку пробного сообщения на 2 с, реплика с этой транзакцией замораживается `docker pause`, повторы того же `Idempotency-Key` через LB до 201 (сначала 504 от LB или 503 по ожиданию блокировки), разморозка; печатает `idle_in_transaction_session_timeout` соединения приложения и строку журнала PostgreSQL о прерывании. Код 0 — повтор получил 201, в чате одно сообщение, обе реплики снова `UP`. Триггер удаляется при любом исходе |
| `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает |
| `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` |
@@ -124,6 +128,9 @@ STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=s
# kill вместо graceful; журнал: какой TARGET_INSTANCE_ID и контейнер
TARGET_INSTANCE_ID=<x-instance-id> scripts/stop-one.sh # остановить одну реплику руками
python3 $D --port 8080 kill-inflight # kill реплики во время входов: 502 от LB без повтора
python3 $D --port 8080 idle-conns # простаивающие соединения с репликами закрывает LB (~10 с), а не реплика (60 с)
python3 $D --port 8080 hang-key # зависшая реплика держит ключ: повтор получает 201 после прерывания транзакции
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин
make replicas # вернуть остановленные реплики (те же ID), ждать healthy
make replicas API_REPLICAS=3 # разово 3 реплики; LB видит новую за 1–3 с без правки конфига
make down # удалить контейнеры, volume с данными остаётся
+441 -1
View File
@@ -27,6 +27,17 @@
режиме kill убивает реплику пробного запроса; статусы по
репликам и ответы LB. Реплика остаётся остановленной
(make replicas)
idle-conns [--threads N] [--requests M] [--keep-alive S] только
стенд с LB: всплеск запросов через LB, клиенты остаются
подключены; раз в секунду — соединения на порт API внутри
каждой реплики и пул LB; код 1, если реплики держат
соединения дольше S секунд — срока keep-alive реплики
hang-key только стенд с LB: сценарий «Повтор ключа после зависшей
реплики» — временный триггер задерживает вставку пробного
сообщения, реплика с этой транзакцией замораживается
(docker pause), повторы того же ключа через LB до 201,
разморозка, одно сообщение в чате, строка журнала PostgreSQL;
триггер удаляется при любом исходе
stop остановить свой экземпляр на порту
all start → flow → smoke → student (если есть student-tests/) → stop
@@ -41,6 +52,9 @@
import argparse
import base64
import contextlib
import csv
import http.client
import io
import json
import os
import signal
@@ -52,6 +66,7 @@ import urllib.error
import urllib.request
import uuid
from collections import Counter
from datetime import UTC, datetime
from pathlib import Path
ROOT = Path(__file__).resolve().parents[3]
@@ -97,6 +112,7 @@ def call(
extra: dict[str, str] | None = None,
body: object = None,
raw: bytes | None = None,
timeout: float = 5,
) -> tuple[int, dict[str, str], object]:
data = raw
headers = {"Accept": "application/json"}
@@ -116,7 +132,7 @@ def call(
headers=headers,
)
try:
with urllib.request.urlopen(request, timeout=5) as response:
with urllib.request.urlopen(request, timeout=timeout) as response:
status = response.status
hdrs = dict(response.headers)
payload = response.read()
@@ -704,6 +720,415 @@ def cmd_kill_inflight(
return 1 if unexpected else 0
# статистика HAProxy изнутри контейнера LB, как make lb_stats
LB_STATS = (
"exec 3<>/dev/tcp/127.0.0.1/8404 && "
'printf "GET /stats;csv HTTP/1.0\\r\\n\\r\\n" >&3 && cat <&3'
)
# psql в контейнере PostgreSQL рабочего стенда от пользователя образа
PSQL = (
'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq -v ON_ERROR_STOP=1'
)
def compose(*args: str, stdin: str | None = None) -> str:
"""docker compose рабочего стенда (проект из docker-compose.yml)."""
proc = subprocess.run(
["docker", "compose", *args],
cwd=ROOT,
input=stdin,
capture_output=True,
text=True,
check=False,
)
if proc.returncode != 0:
raise RuntimeError(f"docker compose {args[0]}: {proc.stderr[-500:]}")
return proc.stdout
def lb_slots() -> list[dict[str, str]]:
"""Занятые слоты backend `api`: адрес, состояние, соединения."""
text = compose("exec", "-T", "haproxy", "bash", "-c", LB_STATS)
lines = [ln for ln in text.splitlines() if ln.startswith(("# ", "api,"))]
if not lines:
return []
rows = csv.DictReader(io.StringIO("\n".join(lines).removeprefix("# ")))
return [
row
for row in rows
if row["svname"] not in ("BACKEND", "FRONTEND") and row.get("addr")
]
def no_lb(port: int) -> bool:
_, pid_path = paths(port)
if pid_path.exists():
print(f"port {port}: console process of the driver, no LB to test")
return True
return False
def replica_connections(container: str, port: int) -> int:
"""Установленные TCP-соединения на порт API внутри контейнера
реплики (`/proc/net/tcp`): то, что реплика держит открытым."""
out = subprocess.run(
[
"docker",
"exec",
container,
"cat",
"/proc/net/tcp",
"/proc/net/tcp6",
],
capture_output=True,
text=True,
check=False,
).stdout
suffix = f":{port:04X}"
return sum(
1
for parts in (line.split() for line in out.splitlines())
if len(parts) > 3
and parts[0] != "sl"
and parts[1].endswith(suffix)
and parts[3] == "01"
)
def cmd_idle_conns(
port: int,
*,
threads: int,
requests: int,
keep_alive: float,
) -> int:
"""Простаивающие соединения LB → реплика (решение 3 design change
`graceful-failover`): их должен закрыть LB раньше, чем реплика по
своему сроку keep-alive.
Клиенты после всплеска остаются подключены и молчат, как браузер
между запросами. Каждую секунду — соединения на порт API внутри
каждой реплики и пул LB. Реплика закрыла бы их через `keep_alive`
секунд, LB — через свой `timeout http-keep-alive` (10 с): по тому,
когда они исчезли, видно, кто закрыл.
"""
if no_lb(port):
return 1
statuses: Counter[int] = Counter()
lock = threading.Lock()
clients: list[http.client.HTTPConnection] = []
def burst() -> None:
# одно keep-alive соединение клиента на поток, после всплеска
# остаётся открытым
conn = http.client.HTTPConnection("127.0.0.1", port, timeout=5)
with lock:
clients.append(conn)
for _ in range(requests):
conn.request("GET", "/health/live")
response = conn.getresponse()
response.read()
with lock:
statuses[response.status] += 1
replicas = {}
for container in compose("ps", "-q", "api").split():
address = subprocess.run(
[
"docker",
"inspect",
"-f",
"{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}",
container,
],
capture_output=True,
text=True,
check=False,
).stdout.strip()
replicas[container] = address
slots = {row["addr"].rsplit(":", 1)[0]: row for row in lb_slots()}
api_port = int(next(iter(slots.values()))["addr"].rsplit(":", 1)[1])
workers = [threading.Thread(target=burst) for _ in range(threads)]
for worker in workers:
worker.start()
for worker in workers:
worker.join()
last = time.monotonic()
print(
f"burst: {threads} keep-alive clients × {requests} GET /health/live "
f"through LB: {dict(statuses)}; clients stay connected and idle",
)
print("t, s replica: connections on its API port | LB pool idle+safe")
zero_since: float | None = None
try:
while True:
elapsed = time.monotonic() - last
held = {
container: replica_connections(container, api_port)
for container in replicas
}
pools = {
container: sum(
int(slots_now.get(field) or 0)
for field in ("idle_conn_cur", "safe_conn_cur")
)
for container, address in replicas.items()
for slots_now in [
{
row["addr"].rsplit(":", 1)[0]: row
for row in lb_slots()
}.get(address, {}),
]
}
print(
f"{elapsed:5.1f} "
+ " ".join(
f"{container[:12]}: {held[container]} | {pools[container]}"
for container in replicas
),
flush=True,
)
# проверка LB открывает соединение на миг: ноль — дважды подряд
if any(held.values()):
zero_since = None
elif zero_since is None:
zero_since = elapsed
else:
print(
f"replicas hold no connections {zero_since:.1f} s after "
f"the last request (replica keep-alive {keep_alive:g} "
"s): closed by LB",
)
return 0 if zero_since < keep_alive else 1
if elapsed > keep_alive + 10:
print(f"replicas still hold connections after {elapsed:.0f} s")
return 1
time.sleep(max(0.0, last + elapsed + 1 - time.monotonic()))
finally:
for conn in clients:
conn.close()
def cmd_hang_key(port: int) -> int:
"""Сценарий «Повтор ключа после зависшей реплики» (спек
`load-balancing`, решение 4 design change `graceful-failover`).
Пробный текст уникален: триггер задерживает вставку только этого
сообщения (`pg_sleep`), другие запросы стенда он не трогает и
удаляется в `finally`. Пароль, токен и ключ не печатаются.
"""
if no_lb(port):
return 1
tag = uuid.uuid4().hex[:8]
username, password = f"hang_{tag}", f"Pw-hang-{uuid.uuid4().hex}"
status, _, user = call(
port,
"POST",
USERS,
body={
"username": username,
"display_name": "Hang demo",
"password": password,
},
)
if status != 201 or not isinstance(user, dict):
print(f"register: {status}")
return 1
status, _, session = call(
port,
"POST",
SESSIONS,
authorization=basic(username, password),
)
if status != 201 or not isinstance(session, dict):
print(f"login: {status}")
return 1
token = session["token"]
status, _, chat = call(
port,
"POST",
CHATS,
token=token,
body={"title": "Hang demo", "member_ids": [user["id"]]},
)
if status != 201 or not isinstance(chat, dict):
print(f"create chat: {status}")
return 1
text = f"hang-probe-{tag}"
path = f"{CHATS}/{chat['id']}/messages"
key = key_header()
trigger = (
"CREATE OR REPLACE FUNCTION hang_probe() RETURNS trigger "
"LANGUAGE plpgsql AS $$ BEGIN PERFORM pg_sleep(2); RETURN NEW; "
"END $$;\n"
"CREATE TRIGGER hang_probe BEFORE INSERT ON messages FOR EACH ROW "
f"WHEN (NEW.text = '{text}') EXECUTE FUNCTION hang_probe();\n"
)
cleanup = (
"DROP TRIGGER IF EXISTS hang_probe ON messages;\n"
"DROP FUNCTION IF EXISTS hang_probe();\n"
)
started = time.time()
t0 = time.monotonic()
paused: str | None = None
first: list[tuple[int, str, float]] = []
def send(timeout: float) -> tuple[int, str]:
try:
status, hdrs, _ = call(
port,
"POST",
path,
token=token,
extra=key,
body={"text": text},
timeout=timeout,
)
except OSError as error:
return 0, type(error).__name__
return status, hdrs.get("x-instance-id", "LB")
def original() -> None:
status, instance = send(30)
first.append((status, instance, time.monotonic() - t0))
try:
compose("exec", "-T", "postgres", "sh", "-c", PSQL, stdin=trigger)
print("trigger: INSERT of the probe message sleeps 2 s")
sender = threading.Thread(target=original)
sender.start()
address = ""
deadline = time.monotonic() + 3
while not address and time.monotonic() < deadline:
address = compose(
"exec",
"-T",
"postgres",
"sh",
"-c",
PSQL,
stdin="SELECT host(client_addr) FROM pg_stat_activity "
"WHERE wait_event = 'PgSleep' "
"AND application_name = 'mtusi-messenger';\n",
).strip()
ids = compose("ps", "-q", "api").split()
for container in ids:
ip = subprocess.run(
[
"docker",
"inspect",
"-f",
"{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}",
container,
],
capture_output=True,
text=True,
check=False,
).stdout.strip()
if address and ip == address.splitlines()[0]:
paused = container
if paused is None:
print(f"replica of the probe INSERT not found ({address!r})")
return 1
timeout_setting = subprocess.run(
[
"docker",
"exec",
paused,
"python",
"-c",
"import asyncio\n"
"from sqlalchemy import text\n"
"from src.infra.db.session import engine\n"
"async def main():\n"
" async with engine.connect() as c:\n"
" r = await c.execute(text("
"'SHOW idle_in_transaction_session_timeout'))\n"
" print(r.scalar())\n"
" await engine.dispose()\n"
"asyncio.run(main())\n",
],
capture_output=True,
text=True,
check=False,
).stdout.strip()
subprocess.run(
["docker", "pause", paused],
check=True,
capture_output=True,
)
mark = time.monotonic() - t0
print(
f"{mark:5.2f} s paused replica {paused[:12]} inside the "
"transaction with the key (INSERT of the probe message); its "
f"connections: idle_in_transaction_session_timeout = "
f"{timeout_setting or '?'}",
)
done = False
while not done and time.monotonic() - t0 < 60:
start = time.monotonic() - t0
status, instance = send(15)
spent = time.monotonic() - t0 - start
print(
f"{start:5.2f} s retry with the same key: {status} via "
f"{instance} in {spent:.2f} s",
flush=True,
)
done = status == 201
if not done:
time.sleep(0.5)
sender.join()
for status, instance, at in first:
print(
f"{at:5.2f} s original request answered: {status} via {instance}",
)
logs = compose(
"logs",
"--no-log-prefix",
"--since",
f"{started:.0f}",
"postgres",
)
terminated = [
ln for ln in logs.splitlines() if "idle-in-transaction" in ln
]
for line in terminated:
# отметка журнала PostgreSQL — часы ВМ, близкие к часам хоста
stamp = datetime.strptime(line[:23], "%Y-%m-%d %H:%M:%S.%f")
at = stamp.replace(tzinfo=UTC).timestamp() - started
print(f"{at:5.2f} s postgres: {line.strip()}")
subprocess.run(
["docker", "unpause", paused],
check=True,
capture_output=True,
)
print(f"{time.monotonic() - t0:5.2f} s unpaused {paused[:12]}")
paused = None
deadline = time.monotonic() + 15
up = False
while not up and time.monotonic() < deadline:
up = all(row["status"] == "UP" for row in lb_slots())
if not up:
time.sleep(0.5)
status, _, page = call(port, "GET", f"{path}?limit=100", token=token)
items = page.get("items", []) if isinstance(page, dict) else []
count = sum(1 for item in items if item.get("text") == text)
print(
f"chat history: {status}, {count} message(s) with the probe text; "
f"all replicas UP in LB: {up}",
)
return 0 if done and count == 1 and terminated and up else 1
finally:
if paused is not None:
subprocess.run(
["docker", "unpause", paused],
check=False,
capture_output=True,
)
compose("exec", "-T", "postgres", "sh", "-c", PSQL, stdin=cleanup)
print("trigger removed")
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--port", type=int, default=DEFAULT_PORT)
@@ -716,6 +1141,12 @@ def main() -> int:
inflight.add_argument("--threads", type=int, default=8)
inflight.add_argument("--seconds", type=float, default=4)
inflight.add_argument("--after", type=float, default=1.5)
idle = sub.add_parser("idle-conns")
idle.add_argument("--threads", type=int, default=20)
idle.add_argument("--requests", type=int, default=50)
# [app] keep_alive_seconds реплики
idle.add_argument("--keep-alive", type=float, default=60)
sub.add_parser("hang-key")
req = sub.add_parser("req")
req.add_argument("method")
req.add_argument("path")
@@ -756,6 +1187,15 @@ def main() -> int:
seconds=args.seconds,
after=args.after,
)
if args.cmd == "idle-conns":
return cmd_idle_conns(
port,
threads=args.threads,
requests=args.requests,
keep_alive=args.keep_alive,
)
if args.cmd == "hang-key":
return cmd_hang_key(port)
handlers = {
"start": cmd_start,
"stop": cmd_stop,
+2
View File
@@ -32,6 +32,8 @@ coverage/
graphify-out/
# make bench_quick: самопроверка стенда, не результат
evidence/bench/quick-*/
# make bench_failover_quick: то же для профиля отказа реплик
evidence/failover/quick-*/
# сравнения пробных меток
evidence/compare/*quick-*
# Keep small, sanitized evidence summaries in evidence/ under version control.
+24 -18
View File
@@ -11,8 +11,10 @@ commit `c6ad34d`): PostgreSQL как источник истины, вход п
Bearer-сессия, Valkey — кэш карточек чатов, трек 2 лабы 2 (план запроса
и восстановление) в `bench/`. Change `instance-id-idempotency` добавил
`X-Instance-Id` и `Idempotency-Key`, `replicas-lb` — HAProxy перед
двумя репликами API, лимиты, `scripts/stop-one.sh`; дальше — changes
из `PLAN.md`. Переход на lab2 завершён changes OpenSpec, они в
двумя репликами API, лимиты, `scripts/stop-one.sh`,
`graceful-failover` — обоснованная и замеренная цепочка таймаутов,
стенд `bench/` на HAProxy + N реплик и профиль `failover`; дальше —
changes из `PLAN.md`. Переход на lab2 завершён changes OpenSpec, они в
`openspec/changes/archive/`. Стек:
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
(JSON в stdout), redis-py (клиент Valkey).
@@ -104,14 +106,14 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
(change `replicas-lb`); `make test`, `make test-persistence` и `make
test-failover` проходят через LB.
- `bench/` — стенд с одним API без LB; переход на HAProxy + N реплик,
профиль `failover` и замер времени обнаружения отказа — change
`graceful-failover`. Цепочка таймаутов задана; замерено только
обнаружение зависшей реплики (`docker pause`, 7,7 с при формуле 8 с,
`evidence/replicas/lb-errors.md`).
- `scripts/rolling-update.sh` нет (change `rolling-update`).
- `REPORT.md` заполнен для идемпотентности, `X-Instance-Id` и реплик за
LB; трек «5» и уровень «4» по failover и rolling update — впереди.
- `scripts/rolling-update.sh` нет (change `rolling-update`); профиль
`rollout` стенда `bench/` — там же.
- Стенд `bench/` уже на HAProxy + N реплик, но нагрузка трека 1
(открытая модель, серии A/B, метрики LB и PostgreSQL по репликам) —
change `scaling-bench`.
- `REPORT.md` заполнен для идемпотентности, `X-Instance-Id`, реплик за
LB и отказа реплик под нагрузкой; трек «5» и уровень «4» по rolling
update — впереди.
Закрытый пункт убрать отсюда, закрытый переход — удалить раздел.
@@ -276,10 +278,12 @@ test-failover` проходят через LB.
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе (`student-tests.md`) |
| `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` |
| `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 |
| `make bench_failover [FAILOVER_LABEL=...]` | уровень 4, отказ реплик под нагрузкой (~7 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах `stop`, `kill`, `pause` с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом — `evidence/failover/<метка>/`. Перед запуском — проверка хоста (`bench.md`) |
| `make bench_failover_quick` | то же короче, режимы `stop` и `kill` (~2 мин), метка `quick-failover-<время>`, в git не идёт |
| `make bench_ab BEFORE=... AFTER=... REAPPLY=<commit>` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита |
| `make bench_compare BEFORE=... AFTER=... [AA=...]` | дельта двух меток `make bench` по ячейкам матрицы; метки с разной методикой не сравнивает; с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` |
@@ -299,7 +303,7 @@ test-failover` проходят через LB.
src/
__main__.py # python -m src → main.main()
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname), [idempotency] ttl_seconds
config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] idle_in_transaction_timeout_ms, [idempotency] ttl_seconds
api/
routers/health.py # /health/live, /health/ready: вне версии, без идентификации
routers/v1/<domain>.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py)
@@ -343,17 +347,18 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, уборка (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB)
bench/ # нагрузочный стенд на API + Postgres + Valkey: make bench / make bench_quick
run.py # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, метрики, runs.csv / summary.md / meta.json
bench.compose.yml # override стенда mtusi-bench: имена, одна реплика api без LB, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover, метрики (сумма по репликам), runs.csv / phases.csv / summary.md / meta.json
failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md
bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей)
k6/ # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления); lib.js — Bearer, messageHeaders (новый Idempotency-Key на отправку) и хелперы
k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
infra/ # конфигурации сервисов стенда; README.md — skeleton
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
haproxy/haproxy.cfg # LB: реплики через DNS Docker (8 слотов), проверки /health/ready, цепочка таймаутов, повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404
haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey
scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
scripts/rolling-update.sh # (лаба 3) поочерёдная замена реплик новым образом
@@ -368,7 +373,8 @@ evidence/cache/ # попадания в кэш, отказ Valkey,
evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md
evidence/idempotency/ # повтор, 409, гонка, таблица ключей, X-Instance-Id
evidence/replicas/ # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ
evidence/failover/<метка>/ # результаты make bench_failover: паспорт, phases.csv, посекундная timeline.csv, summary.md, итоги k6 и журнал LB по фазам
evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
+16
View File
@@ -222,6 +222,22 @@ bench_restore:
bench_restore_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile restore_quick --label quick-restore-$(shell date -u +%Y%m%dT%H%M%SZ)
FAILOVER_LABEL ?= baseline
# уровень 4: отказ реплик под нагрузкой на стенде mtusi-bench (HAProxy, две
# реплики с лимитами рабочего стенда): 100 записей с ключом и 100 чтений в
# секунду, каждая реплика в режимах stop, kill и pause с возвратом,
# посекундная шкала, время обнаружения и восстановления, сверка записей;
# ~10 мин; результат — evidence/failover/$(FAILOVER_LABEL)/
.PHONY: bench_failover
bench_failover:
$(KEEP_AWAKE) uv run python bench/run.py --profile failover --label $(FAILOVER_LABEL)
# то же короче, режимы stop и kill (самопроверка), ~3 мин; в git не идёт
.PHONY: bench_failover_quick
bench_failover_quick:
$(KEEP_AWAKE) uv run python bench/run.py --profile failover_quick --label quick-failover-$(shell date -u +%Y%m%dT%H%M%SZ)
# дельта двух меток по ячейкам матрицы: BEFORE и AFTER обязательны, AA —
# метка того же кода, что BEFORE, для уровня шума; результат —
# evidence/compare/$(BEFORE)__$(AFTER).md
+25 -15
View File
@@ -1,14 +1,14 @@
# Override стенда make bench (bench/run.py): тот же docker-compose.yml под
# проектом mtusi-bench, со своими volume, сетью и лимитами. Пины, healthcheck
# хранилищ, valkey.conf и миграции — из основного файла. Подстановки — из
# bench/bench.env, а не из .env рабочего стенда; пароли и BENCH_* передаёт
# run.py (поля Profile), без них стенд не поднимается. Решения 1, 2, 5 design
# change bench-postgres; что не меняется между метками — .claude/rules/bench.md.
# До change graceful-failover стенд — один API без балансировщика: сервис
# haproxy не запускается (run.py поднимает api с --no-deps), у api одна
# реплика. Лимиты — в форме deploy.resources.limits, как в основном файле:
# compose не принимает cpus/mem_limit рядом с deploy-лимитами; значения
# (NanoCpus, Memory) у контейнеров те же, что раньше.
# хранилищ, valkey.conf, haproxy.cfg и миграции — из основного файла.
# Подстановки — из bench/bench.env, а не из .env рабочего стенда; пароли и
# BENCH_* передаёт run.py (поля Profile), без них стенд не поднимается.
# Решения 1, 2, 5 design change bench-postgres и 6 design change
# graceful-failover; что не меняется между метками — .claude/rules/bench.md.
# Стенд — HAProxy перед BENCH_API_REPLICAS репликами api, как рабочий; k6
# ходит через LB по имени сервиса haproxy. Лимиты — в форме
# deploy.resources.limits, как в основном файле: compose не принимает
# cpus/mem_limit рядом с deploy-лимитами.
services:
postgres:
container_name: mtusi-bench-postgres
@@ -42,13 +42,13 @@ services:
volumes: !reset []
api:
# один контейнер: k6 обращается к нему по имени (container_name вместе
# с deploy.replicas > 1 compose не принимает)
container_name: mtusi-bench-api
# реплики без постоянного имени (оно мешало бы масштабированию):
# оркестратор находит их через docker compose ps, k6 ходит через LB
image: mtusi-messenger:bench
restart: "no"
volumes: !reset []
# проверка раз в несколько секунд — лишний CPU внутри лимита API
# healthcheck образа — лишний CPU внутри лимита API; готовность реплик
# проверяет HAProxy (раз в секунду /health/ready)
healthcheck:
disable: true
environment:
@@ -56,16 +56,26 @@ services:
# 3600 с по умолчанию мог бы истечь посреди прогона и дать 401
AUTH__SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL_SECONDS:?run make bench}
deploy:
replicas: 1
replicas: ${BENCH_API_REPLICAS:?run make bench}
resources:
limits:
# на каждую реплику
cpus: ${BENCH_APP_CPUS:?run make bench}
memory: ${BENCH_APP_MEMORY:?run make bench}
memswap_limit: ${BENCH_APP_MEMORY:?run make bench}
haproxy:
# не запускается, но порт рабочего стенда не занимает и по ошибке
# один экземпляр: имя нужно оркестратору (статистика, журнал)
container_name: mtusi-bench-haproxy
restart: "no"
# порт рабочего стенда не занимает: k6 в сети стенда
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_LB_CPUS:?run make bench}
memory: ${BENCH_LB_MEMORY:?run make bench}
memswap_limit: ${BENCH_LB_MEMORY:?run make bench}
networks:
default:
+583
View File
@@ -0,0 +1,583 @@
"""Профиль отказа реплик: разбор и расчёт без docker.
Оркестрирует фазы `run.py` (профили `failover`, `failover_quick`), здесь —
чистые функции на stdlib: строки k6 о каждом запросе, статистика и
журнал HAProxy, события Docker, посекундная шкала, величины фазы и
`summary.md`. Определения величин — решение 5 design change
`graceful-failover`. Все отметки времени — часы ВМ Docker: `Date.now()` в
k6, отметки `docker logs -t` и `TimeNano` событий Docker.
"""
import csv
import io
import math
import re
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Any
# худшее время обнаружения по проверкам LB, с (infra/haproxy/haproxy.cfg:
# inter 1s, fastinter 500ms, fall 2, timeout check 2500ms, timeout connect
# 500ms): адрес пропал — inter + 0,5 + fastinter + 0,5; зависшая —
# inter + timeout check + fastinter + timeout check
BOUNDS = {"stop": 2.5, "kill": 2.5, "pause": 6.5}
# действие и возврат фазы — события Docker
ACTIONS = {"stop": "kill", "kill": "kill", "pause": "pause"}
RESTORES = {"stop": "start", "kill": "start", "pause": "unpause"}
PHASE_FIELDS = [
"phase",
"mode",
"replica",
"instance",
"slot",
"action_at",
"signal",
"lb_out_s",
"lb_out_state",
"lb_out_reason",
"bound_s",
"first_write_ok_s",
"first_read_ok_s",
"last_error_s",
"requests",
"errors_before",
"errors_down",
"codes_down",
"errors_after",
"codes_after",
"min_success",
"recovery_s",
"ok_rps_before",
"ok_rps_down_min",
"p95_before_ms",
"p95_down_max_ms",
"restore_at",
"lb_up_s",
"slot_back",
"instance_back_s",
"writes",
"writes_failed",
"retried_ok",
"write_chat_messages",
"distinct_texts",
"pg_idle_tx_terminated",
"dropped_iterations",
"flags",
]
TIMELINE_FIELDS = [
"phase",
"mode",
"replica",
"second",
"writes_ok",
"writes_failed",
"reads_ok",
"reads_failed",
"codes",
"success",
"p50_ms",
"p95_ms",
"instances",
]
# без привязки к началу и концу строки: две строки, склеенные без перевода
# строки, всё равно разбираются; число строк run.py сверяет с итогом k6
LINE_RE = re.compile(
r"fo,(?P<kind>[wr]),(?P<n>\d+),(?P<start>\d{13}),(?P<dur>-?\d+),"
r"(?P<status>-?\d+),(?P<instance>[A-Za-z0-9._-]*),(?P<ok>[01])",
)
def unparsed(text: str) -> list[str]:
"""Строки с `fo,`, которые разбор не взял: в сообщение об отказе."""
return [
line
for line in text.splitlines()
if "fo," in line and not LINE_RE.search(line)
]
LB_RE = re.compile(
r"^(?P<stamp>\S+) .*?Server api/(?P<slot>api-\d+) (?P<rest>.*)$",
)
IDLE_TX = "terminating connection due to idle-in-transaction timeout"
@dataclass(frozen=True)
class Request:
"""Один запрос фазы: строка `fo,…` вывода k6."""
kind: str
n: int
start: float
duration_ms: int
status: int
instance: str
ok: bool
@dataclass(frozen=True)
class LbEvent:
"""Смена состояния слота в журнале HAProxy."""
time: float
slot: str
state: str
reason: str
@dataclass(frozen=True)
class DockerEvent:
time: float
action: str
signal: str
def parse_requests(text: str) -> list[Request]:
return [
Request(
kind=match["kind"],
n=int(match["n"]),
start=int(match["start"]) / 1000,
duration_ms=max(0, int(match["dur"])),
status=int(match["status"]),
instance=match["instance"],
ok=match["ok"] == "1",
)
for match in LINE_RE.finditer(text)
]
def parse_stamp(stamp: str) -> float:
"""Отметка `docker logs -t` (RFC 3339, наносекунды) → секунды эпохи."""
head, _, frac = stamp.rstrip("Z").partition(".")
seconds = datetime.fromisoformat(head).replace(tzinfo=UTC).timestamp()
return seconds + (float(f"0.{frac}") if frac else 0.0)
def iso(seconds: float) -> str:
return datetime.fromtimestamp(seconds, UTC).isoformat(
timespec="milliseconds",
)
def parse_lb_stats(text: str) -> list[dict[str, str]]:
"""CSV статистики HAProxy → занятые слоты backend `api`."""
lines = [
line for line in text.splitlines() if line.startswith(("# ", "api,"))
]
if not lines:
return []
reader = csv.DictReader(io.StringIO("\n".join(lines).removeprefix("# ")))
return [
{
"slot": row["svname"],
"addr": row.get("addr") or "",
"status": row["status"],
"check_status": row.get("check_status") or "",
}
for row in reader
if row["pxname"] == "api"
and row["svname"] not in ("BACKEND", "FRONTEND")
and row.get("addr")
]
def parse_lb_log(text: str) -> list[LbEvent]:
"""Строки смены состояния слотов из журнала LB (`docker logs -t`).
HAProxy пишет каждое событие дважды (в журнал и предупреждением):
повтор с тем же слотом и состоянием в пределах миллисекунды
отбрасывается.
"""
events: list[LbEvent] = []
for line in text.splitlines():
match = LB_RE.match(line)
if not match:
continue
rest = match["rest"]
if "maintenance" in rest:
state = "MAINT"
elif rest.startswith("is DOWN,") or rest == "is DOWN.":
state = "DOWN"
elif rest.startswith("is UP"):
state = "UP"
else:
continue
reason = re.search(r"reason: ([^,]+)", rest)
info = re.search(r"maintenance \(([^)]*)\)", rest)
event = LbEvent(
time=parse_stamp(match["stamp"]),
slot=match["slot"],
state=state,
reason=(
reason.group(1)
if reason
else (info.group(1).strip() if info else "")
),
)
if any(
e.slot == event.slot
and e.state == event.state
and abs(e.time - event.time) < 0.001
for e in events
):
continue
events.append(event)
return sorted(events, key=lambda e: e.time)
def lb_lines(text: str) -> str:
"""Строки журнала LB о состоянии слотов — для `raw/<фаза>-lb.log`."""
return "\n".join(
line
for line in text.splitlines()
if "Server api/" in line and "[WARNING]" not in line
)
def parse_events(text: str) -> list[DockerEvent]:
events = []
for line in text.splitlines():
parts = line.split()
if len(parts) < 2 or not parts[0].isdigit():
continue
signal = parts[2] if len(parts) > 2 and parts[2].isdigit() else ""
events.append(DockerEvent(int(parts[0]) / 1e9, parts[1], signal))
return sorted(events, key=lambda e: e.time)
def count_idle_terminations(text: str) -> int:
"""Сколько соединений PostgreSQL прервал по простою в транзакции."""
return text.count(IDLE_TX)
def percentile(values: list[int], share: float) -> int | None:
"""Ближайший ранг: p95 из 100 значений — 95-е по возрастанию."""
if not values:
return None
ordered = sorted(values)
return ordered[max(0, math.ceil(share * len(ordered)) - 1)]
def code(request: Request) -> str:
"""Код ошибки: статус, 0 — ошибка соединения или таймаут клиента,
`200-short` — чтение без полной страницы."""
if request.status == 200 and not request.ok:
return "200-short"
return str(request.status)
def codes(requests: list[Request]) -> str:
counts: dict[str, int] = {}
for request in requests:
if not request.ok:
counts[code(request)] = counts.get(code(request), 0) + 1
return " ".join(f"{key}:{value}" for key, value in sorted(counts.items()))
def build_timeline(
requests: list[Request],
t0: float,
*,
phase: str,
mode: str,
replica: int,
) -> list[dict[str, Any]]:
"""Посекундная шкала от действия: секунда запроса — по отправке."""
buckets: dict[int, list[Request]] = {}
for request in requests:
buckets.setdefault(math.floor(request.start - t0), []).append(request)
rows = []
for second in range(min(buckets, default=0), max(buckets, default=-1) + 1):
group = buckets.get(second, [])
ok = [r for r in group if r.ok]
instances: dict[str, int] = {}
for request in ok:
instances[request.instance] = (
instances.get(request.instance, 0) + 1
)
durations = [r.duration_ms for r in ok]
rows.append(
{
"phase": phase,
"mode": mode,
"replica": replica,
"second": second,
"writes_ok": sum(1 for r in ok if r.kind == "w"),
"writes_failed": sum(
1 for r in group if r.kind == "w" and not r.ok
),
"reads_ok": sum(1 for r in ok if r.kind == "r"),
"reads_failed": sum(
1 for r in group if r.kind == "r" and not r.ok
),
"codes": codes(group),
"success": round(len(ok) / len(group), 4) if group else None,
"p50_ms": percentile(durations, 0.5),
"p95_ms": percentile(durations, 0.95),
"instances": " ".join(
f"{key}:{value}"
for key, value in sorted(instances.items())
),
},
)
return rows
def first_after(
events: list[LbEvent],
slot: str | None,
states: tuple[str, ...],
since: float,
) -> LbEvent | None:
return next(
(
e
for e in events
if e.slot == slot and e.state in states and e.time >= since
),
None,
)
def rounded(value: float | None, digits: int = 2) -> float | None:
return None if value is None else round(value, digits)
def analyze(
requests: list[Request],
timeline: list[dict[str, Any]],
lb_events: list[LbEvent],
*,
mode: str,
instance: str,
t0: float,
restore: float,
slot: str | None,
slot_back: str | None,
threshold: float,
) -> dict[str, Any]:
"""Величины фазы (решение 5): секунды от действия и от возврата.
До действия — запросы, завершённые до него. Запрос в полёте в момент
действия (на замороженной или убитой реплике) относится к окну
отказа, хотя в шкале он — в секунде отправки.
"""
def ended(request: Request) -> float:
return request.start + request.duration_ms / 1000
before = [r for r in requests if ended(r) < t0]
down = [r for r in requests if ended(r) >= t0 and r.start < restore]
after = [r for r in requests if r.start >= restore]
window = math.ceil(restore - t0)
down_rows = [row for row in timeline if 0 <= row["second"] < window]
before_rows = [row for row in timeline if row["second"] < 0][2:]
bad = [
row["second"]
for row in down_rows
if row["success"] is not None and row["success"] < threshold
]
out = first_after(lb_events, slot, ("DOWN", "MAINT"), t0)
up = first_after(lb_events, slot_back, ("UP",), restore)
back = next(
(
r
for r in sorted(after, key=lambda r: r.start)
if r.ok and r.instance == instance
),
None,
)
def first_ok(kind: str) -> float | None:
starts = [
r.start for r in down if r.kind == kind and r.ok and r.start >= t0
]
return rounded(min(starts) - t0) if starts else None
failed_down = [r for r in down if not r.ok]
p95_down = [
row["p95_ms"] for row in down_rows if row["p95_ms"] is not None
]
lb_out_s = rounded(out.time - t0) if out else None
flags = []
if out is None:
flags.append("no_lb_out")
elif lb_out_s is not None and lb_out_s > BOUNDS[mode]:
flags.append("over_bound")
if up is None:
flags.append("no_lb_up")
if [r for r in before if not r.ok]:
flags.append("errors_before")
return {
"lb_out_s": lb_out_s,
"lb_out_state": out.state if out else None,
"lb_out_reason": out.reason if out else None,
"bound_s": BOUNDS[mode],
"first_write_ok_s": first_ok("w"),
"first_read_ok_s": first_ok("r"),
"last_error_s": (
rounded(max(r.start for r in failed_down) - t0)
if failed_down
else None
),
"requests": len(requests),
"errors_before": sum(1 for r in before if not r.ok),
"errors_down": len(failed_down),
"codes_down": codes(down),
"errors_after": sum(1 for r in after if not r.ok),
"codes_after": codes(after),
"min_success": min(
(
row["success"]
for row in down_rows
if row["success"] is not None
),
default=None,
),
"recovery_s": max(bad) + 1 if bad else 0,
"ok_rps_before": (
round(
sum(row["writes_ok"] + row["reads_ok"] for row in before_rows)
/ len(before_rows),
1,
)
if before_rows
else None
),
"ok_rps_down_min": min(
(row["writes_ok"] + row["reads_ok"] for row in down_rows),
default=None,
),
"p95_before_ms": percentile(
[r.duration_ms for r in before if r.ok],
0.95,
),
"p95_down_max_ms": max(p95_down, default=None),
"lb_up_s": rounded(up.time - restore) if up else None,
"instance_back_s": rounded(back.start - restore) if back else None,
"writes": sum(1 for r in requests if r.kind == "w"),
"writes_failed": sum(
1 for r in requests if r.kind == "w" and not r.ok
),
"flags": " ".join(flags),
}
def fmt(value: Any) -> str:
if value is None or value == "":
return "—"
if isinstance(value, float):
return f"{value:g}"
return str(value)
def render_summary(
meta: dict[str, Any],
phases: list[dict[str, Any]],
timeline: list[dict[str, Any]],
) -> str:
"""`summary.md` профиля отказа: условия, таблица фаз, шкалы вокруг
действия и возврата."""
profile = meta["profile"]
lines = [
f"# Отказ реплик под нагрузкой: метка `{meta['label']}`",
"",
f"- Статус: **{meta['status']}**"
+ (f" ({meta['reason']})" if meta.get("reason") else ""),
f"- Commit: `{meta['git']['commit']}`"
+ (" + незакоммиченные изменения" if meta["git"]["dirty"] else ""),
f"- Профиль `{profile['name']}`: {profile['replicas']} реплики за "
f"HAProxy; {profile['failover_write_rate']} записей с ключом и "
f"{profile['failover_read_rate']} чтений страницы истории в "
"секунду (k6, постоянная интенсивность); режимы "
f"{', '.join(profile['failover_modes'])}; окна фазы: "
f"{profile['failover_before_s']} с до действия, "
f"{profile['failover_down_s']} с до возврата, "
f"{profile['failover_after_s']} с после; порог восстановления "
f"{profile['failover_success']:.0%}",
f"- Лимиты без swap: API {profile['cpus']} CPU / "
f"{profile['memory']} на реплику, HAProxy {profile['lb_cpus']} CPU / "
f"{profile['lb_memory']}, PostgreSQL {profile['db_cpus']} CPU / "
f"{profile['db_memory']}, Valkey {profile['cache_cpus']} CPU / "
f"{profile['cache_memory']}",
"- Посторонние контейнеры в VM во время замера: "
+ (", ".join(meta.get("other_containers") or []) or "нет"),
"",
"Время — секунды на часах ВМ Docker. Действие — событие Docker "
"(`kill` с сигналом 15 у `docker stop`, 9 у `docker kill`, "
"`pause`), исключение и возврат — строки журнала HAProxy, ответы — "
"отметки k6 при отправке. Граница — худший случай формулы проверок "
"LB для режима. Восстановление — конец последней секунды окна "
"отказа с долей успешных ниже порога (0 — таких секунд нет). "
"Сверка — после повтора неуспешных записей с тем же ключом: "
"сообщений в чате записи и разных текстов столько, сколько "
"отправлено разных ключей.",
"",
"| Фаза | Реплика | Исключение LB, с (граница) | Причина | "
"Первая запись / чтение, с | Ошибки в окне отказа | Мин. доля "
"успешных | Восстановление, с | Возврат в LB, с | Ошибки после "
"возврата | Повтор записей | Сообщений = ключей | PG: прервано "
"простоев | Пометки |",
"|---|---|---|---|---|---|---|---|---|---|---|---|---|---|",
]
for row in phases:
lines.append(
f"| {row['phase']} | {row['instance']} ({row['slot']}) | "
f"{fmt(row['lb_out_s'])} ({fmt(row['bound_s'])}) | "
f"{fmt(row['lb_out_state'])}: {fmt(row['lb_out_reason'])} | "
f"{fmt(row['first_write_ok_s'])} / {fmt(row['first_read_ok_s'])} "
f"| {row['errors_down']} {fmt(row['codes_down'])} | "
f"{fmt(row['min_success'])} | {row['recovery_s']} | "
f"{fmt(row['lb_up_s'])} | {row['errors_after']} | "
f"{row['writes_failed']} → {fmt(row['retried_ok'])} | "
f"{fmt(row['write_chat_messages'])} = "
f"{fmt(row['distinct_texts'])} | "
f"{fmt(row['pg_idle_tx_terminated'])} | {fmt(row['flags'])} |",
)
lines.append("")
for row in phases:
rows = [r for r in timeline if r["phase"] == row["phase"]]
reach = max(
row["recovery_s"] or 0,
math.ceil(row["lb_out_s"] or 0),
)
down_s = profile["failover_down_s"]
shown = [
r
for r in rows
if -2 <= r["second"] <= reach + 2
or down_s - 1 <= r["second"] <= down_s + 3
]
lines += [
f"## Фаза {row['phase']}",
"",
f"Действие {row['action_at']} над `{row['instance']}` (слот "
f"{row['slot']}), возврат {row['restore_at']}; ответов "
f"{row['requests']}, до действия {fmt(row['ok_rps_before'])} "
f"успешных/с, p95 {fmt(row['p95_before_ms'])} мс. Полная шкала "
"— `timeline.csv`.",
"",
"| с от действия | Записи ok / ош | Чтения ok / ош | Коды ошибок "
"| Доля успешных | p50 / p95, мс | Ответы реплик |",
"|---|---|---|---|---|---|---|",
]
previous = None
for r in shown:
if previous is not None and r["second"] != previous + 1:
lines.append("| … | | | | | | |")
previous = r["second"]
lines.append(
f"| {r['second']} | {r['writes_ok']} / {r['writes_failed']} | "
f"{r['reads_ok']} / {r['reads_failed']} | {fmt(r['codes'])} | "
f"{fmt(r['success'])} | {fmt(r['p50_ms'])} / "
f"{fmt(r['p95_ms'])} | {fmt(r['instances'])} |",
)
lines.append("")
if meta.get("host_warnings"):
lines += ["## Предупреждения о хосте", ""]
lines += [f"- {w}" for w in meta["host_warnings"]]
lines.append("")
return "\n".join(lines)
+128
View File
@@ -0,0 +1,128 @@
// Профиль отказа реплик: постоянная интенсивность записи с ключом и чтения
// страницы истории через LB, пока оркестратор останавливает и возвращает
// реплику (решение 7 design change graceful-failover). Каждый запрос —
// строка «fo,<w|r>,<n>,<отправка мс>,<длительность мс>,<статус>,
// <X-Instance-Id>,<успех>» в вывод k6: из них run.py строит посекундную
// шкалу. Время — Date.now() часов ВМ Docker, те же часы, что у журнала LB и
// событий Docker.
import exec from "k6/execution";
import http from "k6/http";
import { SharedArray } from "k6/data";
import {
API,
PAGE_LIMIT,
SUMMARY_THRESHOLDS,
SUMMARY_TREND_STATS,
WORK_DIR,
authHeaders,
messageHeaders,
mulberry32,
summaryFiles,
syntheticText,
} from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const cursors = new SharedArray(
"cursors",
() => JSON.parse(open(`${WORK_DIR}/cursors.json`)).cursors,
);
// ключ записи — <RUN>.<PHASE>.<n>: повтор (retry.js) строит тот же
const RUN = __ENV.RUN;
const PHASE = Number(__ENV.PHASE);
const SEED = Number(__ENV.SEED || 0);
// VU сценария: заранее созданные и предел (Profile.failover_pre_vus,
// failover_max_vus). Создание VU на ходу пропускает итерации
const PRE_VUS = Number(__ENV.PRE_VUS || 600);
const MAX_VUS = Number(__ENV.MAX_VUS || 1500);
// больше timeout server LB (10 с): клиент видит ответ LB, а не свой таймаут
const TIMEOUT = __ENV.TIMEOUT || "15s";
const WRITE_URL = `${API}/chats/${fixture.writeChatId}/messages`;
const READ_URL = `${API}/chats/${fixture.readChatId}/messages`;
const READ_HEADERS = authHeaders(fixture.tokens[fixture.readerId]);
function scenario(fn, rate) {
return {
executor: "constant-arrival-rate",
exec: fn,
rate,
timeUnit: "1s",
duration: __ENV.DURATION,
// зависшая реплика держит запрос до timeout server: VU с запасом
preAllocatedVUs: PRE_VUS,
maxVUs: MAX_VUS,
gracefulStop: "20s",
};
}
export const options = {
scenarios: {
write: scenario("write", Number(__ENV.WRITE_RATE)),
read: scenario("read", Number(__ENV.READ_RATE)),
},
summaryTrendStats: SUMMARY_TREND_STATS,
// пороги всегда выполняются: подметрики итераций по сценариям попадают
// в итог, и run.py сверяет с ними число строк о запросах
thresholds: {
...SUMMARY_THRESHOLDS,
"iterations{scenario:write}": ["count>=0"],
"iterations{scenario:read}": ["count>=0"],
},
};
// длительность — по монотонным таймингам k6, а не разность Date.now():
// часы ВМ подводятся, и при шаге назад разность выходила отрицательной.
// Ответа нет (status 0) — тайминги пусты, тогда разность часов
function report(kind, n, start, res, ok) {
const instance = res.headers["X-Instance-Id"] || "-";
const t = res.timings;
const measured = t.blocked + t.connecting + t.tls_handshaking + t.duration;
const duration = Math.max(
0,
Math.round(res.status === 0 ? Date.now() - start : measured),
);
console.log(
`fo,${kind},${n},${start},${duration},${res.status},${instance},${ok ? 1 : 0}`,
);
}
export function write() {
const n = exec.scenario.iterationInTest;
const sender = fixture.memberIds[n % fixture.memberIds.length];
const start = Date.now();
const res = http.post(
WRITE_URL,
JSON.stringify({ text: syntheticText(`f${PHASE}`, n) }),
{
headers: messageHeaders(fixture.tokens[sender], `${RUN}.${PHASE}.${n}`),
responseType: "none",
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(201),
},
);
report("w", n, start, res, res.status === 201);
}
let random = null;
export function read() {
if (random === null) {
random = mulberry32(SEED + exec.vu.idInTest);
}
const n = exec.scenario.iterationInTest;
const cursor = encodeURIComponent(
cursors[Math.floor(random() * cursors.length)],
);
const start = Date.now();
const res = http.get(`${READ_URL}?limit=${PAGE_LIMIT}&cursor=${cursor}`, {
headers: READ_HEADERS,
timeout: TIMEOUT,
responseCallback: http.expectedStatuses(200),
});
const full = res.status === 200 && res.json("items.#") === PAGE_LIMIT;
report("r", n, start, res, full);
}
export function handleSummary(data) {
return summaryFiles(data);
}
+10 -6
View File
@@ -4,7 +4,10 @@ import encoding from "k6/encoding";
import http from "k6/http";
import { check, fail } from "k6";
export const BASE_URL = __ENV.BASE_URL || "http://mtusi-bench-api:8080";
// через балансировщик стенда: имя сервиса haproxy — алиас в сети
// mtusi-bench, за ним Profile.replicas реплик (решение 6 design change
// graceful-failover)
export const BASE_URL = __ENV.BASE_URL || "http://haproxy:8080";
export const API = `${BASE_URL}/api/v1`;
// каталог метки (сырые итоги) и рабочий каталог (фикстура, курсоры)
export const OUT_DIR = __ENV.OUT_DIR || "/out";
@@ -31,11 +34,12 @@ export function authHeaders(token) {
// заголовки отправки сообщения: с лабы 3 обязателен Idempotency-Key. Новый
// ключ на каждую отправку (UUID v4 WebCrypto — допустимый алфавит
// контракта); стенд отправку не повторяет
export function messageHeaders(token) {
// контракта); стенд отправку не повторяет. Профиль отказа задаёт ключ сам:
// повтор неподтверждённой записи строит тот же ключ по номеру
export function messageHeaders(token, key = crypto.randomUUID()) {
return {
...authHeaders(token),
"Idempotency-Key": crypto.randomUUID(),
"Idempotency-Key": key,
};
}
@@ -96,12 +100,12 @@ export function createChat(ownerToken, title, memberIds) {
return res.json("id");
}
export function sendMessage(chatId, senderToken, text) {
export function sendMessage(chatId, senderToken, text, key = undefined) {
const res = http.post(
`${API}/chats/${chatId}/messages`,
JSON.stringify({ text }),
{
headers: messageHeaders(senderToken),
headers: messageHeaders(senderToken, key),
responseCallback: http.expectedStatuses(201),
},
);
+55
View File
@@ -0,0 +1,55 @@
// Повтор неподтверждённых записей фазы отказа с тем же ключом и тем же
// телом до 201 (решение 7 design change graceful-failover). Номера — в
// retry.json рабочего каталога; итог — retry-result.json: сколько
// получили 201 и какие нет. Ключ и текст строятся так же, как в
// failover.js, поэтому повтор после неопределённого исхода (kill, 504)
// возвращает сохранённое сообщение или пишет его впервые — без дубля.
import { sleep } from "k6";
import { WORK_DIR, sendMessage, syntheticText } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const items = JSON.parse(open(`${WORK_DIR}/retry.json`)).items;
const RUN = __ENV.RUN;
const PHASE = Number(__ENV.PHASE);
const ATTEMPTS = 5;
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "5m",
};
export function setup() {
let ok = 0;
const failed = [];
for (const n of items) {
const sender = fixture.memberIds[n % fixture.memberIds.length];
let status = 0;
for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
const res = sendMessage(
fixture.writeChatId,
fixture.tokens[sender],
syntheticText(`f${PHASE}`, n),
`${RUN}.${PHASE}.${n}`,
);
status = res.status;
if (status === 201) {
break;
}
sleep(1);
}
if (status === 201) {
ok += 1;
} else {
failed.push({ n, status });
}
}
return { ok, failed };
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/retry-result.json`]: JSON.stringify(data.setup_data) };
}
+735 -110
View File
File diff suppressed because it is too large Load Diff
+9
View File
@@ -9,6 +9,11 @@
log_level = "INFO"
# сколько секунд uvicorn ждёт текущие запросы после SIGTERM
graceful_shutdown_seconds = 8
# сколько секунд uvicorn держит простаивающее keep-alive соединение;
# больше, чем HAProxy держит простаивающее соединение с репликой (timeout
# http-keep-alive 10 с, http-reuse never в infra/haproxy/haproxy.cfg):
# простаивающее соединение закрывает LB
keep_alive_seconds = 60
# instance_id (X-Instance-Id) здесь не задавать: config.toml общий у всех
# реплик, а значение должно различаться. Без него берётся hostname
# процесса (в compose — короткий ID контейнера); в консоли его можно
@@ -27,6 +32,10 @@ connect_timeout_seconds = 3
statement_timeout_ms = 5000
# секунды на всю работу запроса с БД: зависший сервер, обрыв сети
request_timeout_seconds = 6
# миллисекунды, серверный idle_in_transaction_session_timeout: транзакцию
# замороженной реплики PostgreSQL прерывает и снимает её блокировки.
# 0 — без ограничения, иначе больше request_timeout_seconds
idle_in_transaction_timeout_ms = 10000
[auth]
# секунды жизни сессии с момента входа (контрактное имя
+35 -10
View File
@@ -1,7 +1,8 @@
# Балансировщик стенда лабы 3: единственная точка входа перед репликами
# сервиса api. Правила — .claude/rules/balancer.md, решения — design
# change replicas-lb (решения 1–5). Порт приходит переменной окружения
# API_PORT (= APP__PORT из .env); секретов LB не получает.
# change replicas-lb (решения 1–5) и graceful-failover (цепочка таймаутов,
# решения 1–3). Порт приходит переменной окружения API_PORT (= APP__PORT
# из .env); секретов LB не получает. Тот же файл использует стенд bench/.
global
# журнал — в stdout контейнера (docker compose logs haproxy)
@@ -49,12 +50,13 @@ defaults
timeout server 10s
timeout client 30s
timeout http-request 10s
# простаивающий сеанс клиента, а с ним и соединение с репликой
# (http-reuse never): меньше [app] keep_alive_seconds реплики (60 с)
timeout http-keep-alive 10s
# больше таймаута проверки внутри /health/ready (2 с). Следующая
# проверка — через inter после конца предыдущей, поэтому худшее
# обнаружение зависшей реплики ≈ fall × (inter + timeout check) =
# 2 × (1 + 3) = 8 с ≤ 10 с; остановленную проверка не ждёт
timeout check 3s
# больше таймаута проверки внутри /health/ready (2 с) на 0,5 с:
# медленный PostgreSQL даёт 503 от реплики (L7STS), а не таймаут
# проверки. Худшее обнаружение — в комментарии backend api
timeout check 2500ms
# request_id ответов, которые создаёт сам LB
unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid
# ответы самого LB — в формате ошибки контракта; в перечислении кодов
@@ -72,18 +74,41 @@ frontend entry
backend api
# по очереди, без cookie и stick-table: sticky session запрещён
balance roundrobin
# соединение с репликой не переходит в общий пул и не отдаётся другому
# клиенту: оно живёт, пока жив сеанс клиента, а простаивающий сеанс LB
# закрывает по timeout http-keep-alive (10 с). uvicorn держит
# простаивающее соединение [app] keep_alive_seconds = 60 с, дольше —
# значит, закрывает LB, и запрос не уходит в соединение, которое
# реплика в этот момент закрывает (ответа не было бы, а empty-response
# LB не повторяет). С пулом (http-reuse safe) последнее простаивающее
# соединение LB держал, пока его не закрывала реплика. Гонку при
# SIGTERM (uvicorn сразу закрывает простаивающие соединения) не убирает
# ни один режим: одиночный 502 в 2 из 8 фаз stop с never и в 1 из 9 с
# safe (design change graceful-failover, решение 3)
http-reuse never
# активная проверка готовности: /health/live для LB не годится,
# живой процесс без PostgreSQL запросы не обслуживает
option httpchk
http-check send meth GET uri /health/ready
http-check expect status 200
# реплика исключается после 2 неудачных проверок подряд и
# возвращается после 2 успешных; проверка раз в секунду. init-state
# down: слот, получивший адрес из DNS (старт LB, новая или
# возвращается после 2 успешных; проверка раз в секунду (inter, у
# исключённой — downinter = inter), а после первой неудачи и до
# возврата — через fastinter. Следующая проверка начинается через
# интервал после конца предыдущей, поэтому худшее обнаружение:
# зависшая (соединение есть, ответа нет): inter + timeout check +
# (fall − 1) × (fastinter + timeout check) = 1 + 2,5 + 0,5 + 2,5
# = 6,5 с ≤ 10 с;
# адрес пропал (stop после выхода, kill): таймаут соединения
# проверки min(timeout connect, inter) = 0,5 с: 1 + 0,5 + 0,5 +
# 0,5 = 2,5 с; DNS уводит слот в обслуживание за 1–2 с;
# сокет закрыт, адрес жив (окно graceful): 1 + 0,5 = 1,5 с.
# Возврат: ≤ downinter + fastinter = 1,5 с после готовности.
# init-state down: слот, получивший адрес из DNS (старт LB, новая или
# вернувшаяся реплика), начинает DOWN и получает запросы только после
# rise проверок, а не сразу — иначе запросы шли бы на процесс, который
# ещё не слушает порт
default-server check inter 1s fall 2 rise 2 resolvers docker init-addr none init-state down resolve-prefer ipv4
default-server check inter 1s fastinter 500ms fall 2 rise 2 resolvers docker init-addr none init-state down resolve-prefer ipv4
# 8 слотов — максимум реплик в сериях трека 1; лишние слоты в MAINT,
# девятую реплику LB не увидит
server-template api- 8 "api:${API_PORT}"
+107 -53
View File
@@ -87,7 +87,8 @@
|---|---|---|---|
| Клиент `tests/resilience.py` | 2 с | — | задан skeleton; всё, что LB делает до ответа при отказе соединения, должно уложиться |
| Клиент k6 профиля `failover` | — | 15 с | > `timeout server`: клиент видит ответ LB (504), а не свой таймаут |
| HAProxy `timeout client` / `http-request` / `http-keep-alive` | 30 / 10 / 10 с | — | соединения клиентов; на отказ реплики не влияют |
| HAProxy `timeout client` / `http-request` | 30 / 10 с | — | соединения клиентов; на отказ реплики не влияют |
| HAProxy `timeout http-keep-alive` | 10 с | — | простаивающий сеанс клиента, а с `http-reuse never` — и его соединения с репликами; < `keep_alive_seconds` реплики |
| HAProxy `timeout connect` | 500 мс | — | × (`retries` 2 + 1) = 1,5 с < 2 с клиента. Живая реплика в сети Docker принимает соединение за доли миллисекунды; 500 мс ограничивают ожидание пропавшего адреса (разведка: всплеск задержки до 0,5 с на ~1,6 с) |
| HAProxy `retries`, `redispatch 1`, `retry-on conn-failure` | 2, да | — | повтор только недошедшего запроса, каждый — на другую реплику (`replicas-lb`, решение 4) |
| HAProxy `timeout server` | 10 с | — | > `request_timeout_seconds` 6 с + KDF входа под лимитом 1 CPU (до 1,6 с при 4 входах сразу) |
@@ -97,8 +98,8 @@
| HAProxy `timeout check` | 3 с | 2,5 с | > `READINESS_DB_TIMEOUT_SECONDS` 2 с на 0,5 с: медленный PostgreSQL даёт 503 от реплики, а не таймаут проверки (решение 2) |
| Таймаут соединения проверки | min(`timeout connect`, `inter`) = 0,5 с | — | правило HAProxy; ограничивает проверку пропавшего адреса |
| `resolvers docker` `hold` | 1 с | — | пропавший адрес уходит из слота за 1–2 с, новый появляется так же |
| HAProxy `pool-purge-delay` | 5 с (по умолчанию) | 5 с явно | период уборки простаивающих соединений к репликам (решение 3) |
| uvicorn `timeout_keep_alive` | 5 с (по умолчанию) | 60 с, `[app] keep_alive_seconds` | > времени, за которое LB сам убирает простаивающее соединение: закрывает LB, а не реплика (решение 3) |
| HAProxy `http-reuse` | `safe` (по умолчанию) | `never` | соединение с репликой живёт не дольше сеанса клиента, а простаивающий сеанс LB закрывает по `timeout http-keep-alive` 10 с (решение 3) |
| uvicorn `timeout_keep_alive` | 5 с (по умолчанию) | 60 с, `[app] keep_alive_seconds` | > `timeout http-keep-alive` LB (10 с): простаивающее соединение закрывает LB, а не реплика (решение 3) |
| `/health/ready`: `SELECT 1` | 2 с | — | < `timeout check` |
| Пул: `pool_timeout` / `connect_timeout` | 5 / 3 с | — | ожидание соединения пула и подключение; оба < `request_timeout_seconds` |
| PostgreSQL `statement_timeout` | 5 с | — | < `request_timeout_seconds`: сервер сам прерывает долгую команду раньше, чем приложение рвёт соединение |
@@ -160,52 +161,80 @@
### 3. Простаивающие соединения LB → реплика: закрывает LB
HAProxy держит пул простаивающих соединений к каждой реплике (`http-reuse
safe`). Каждые `pool-purge-delay` (5 с) он закрывает половину
соединений сверх оценки нужного числа. Без запросов оценка падает
вдвое за период, и пул пустеет за несколько периодов. uvicorn закрывает
простаивающее соединение через `timeout_keep_alive`. Разведка: это
5 с, и закрывает реплика. Если LB отправит запрос в соединение в
момент его закрытия, ответа не будет. `empty-response` LB не
повторяет намеренно, поэтому клиент получит 502.
uvicorn закрывает простаивающее соединение через `timeout_keep_alive`
(5 с по умолчанию). Если LB отправит запрос в соединение в момент его
закрытия, ответа не будет. `empty-response` LB не повторяет намеренно,
поэтому клиент получит 502. Значит, простаивающее соединение должен
закрывать LB, а реплика держать его дольше.
Решение:
Решение (окончательное — после проверки в apply, см. ниже):
- `[app] keep_alive_seconds` = 60 → `uvicorn.run(...,
timeout_keep_alive=...)`. Это заметно дольше, чем LB убирает пул
(≈ 6 периодов по 5 с для 20 соединений). Простаивающее соединение
закрывает LB, и запрос в закрывающееся соединение не уходит.
- `pool-purge-delay 5s` в `haproxy.cfg` явно: это вторая половина
соотношения.
- Проверка в apply — команда драйвера `idle-conns` (решение 8):
всплеск через LB, затем статистика LB раз в секунду. Число
простаивающих соединений убывает ступенями и обнуляется раньше 60 с.
Иначе — увеличить срок или уменьшить `pool-purge-delay`.
timeout_keep_alive=...)`.
- `http-reuse never` в `backend api`. Соединение с репликой не уходит в
общий пул и не отдаётся другому клиенту: оно живёт, пока жив сеанс
клиента. Простаивающий сеанс LB закрывает по `timeout http-keep-alive`
(10 с), вместе с его соединениями к репликам. 10 с < 60 с:
простаивающее соединение всегда закрывает LB.
- Проверка — команда драйвера `idle-conns` (решение 8). Клиенты после
всплеска остаются подключены и молчат. Раз в секунду — установленные
соединения на порт API внутри каждой реплики (`/proc/net/tcp`).
Цена: реплика держит лишние дескрипторы до 60 с. Простаивающее
соединение uvicorn ничего не стоит, кроме дескриптора.
Как пришли к решению (apply, рабочий стенд, 2026-10-10):
| Конфигурация | Когда реплики остались без соединений | Кто закрыл |
|---|---|---|
| `http-reuse safe`, keep-alive 5 с (было) | ~5 с после всплеска, весь пул LB разом (разведка, «Context») | реплика |
| `http-reuse safe`, keep-alive 60 с, `pool-purge-delay 5s` (первый вариант design) | пул LB уменьшался вдвое каждые 5 с (15 → 10 → 6 → 3 → 1), но последнее соединение LB держал до 60,3 с | реплика |
| `http-reuse never`, keep-alive 60 с | 10,1 с, когда LB закрыл молчащих клиентов | LB |
Первый вариант design опирался на то, что уборка пула HAProxy закроет
и последнее соединение. Проверка это опровергла: HAProxy оставляет одно
простаивающее соединение к реплике сколь угодно долго. Длинный
keep-alive делал гонку реже, но не убирал её.
Цена `http-reuse never`:
- соединения с репликами не делятся между клиентами, их число — до
числа клиентских соединений на реплику. Для uvicorn это только
дескрипторы;
- новых TCP-соединений на запрос не прибавляется. Клиент с keep-alive
ходит в реплику по своему соединению. Клиент с новым соединением на
запрос (`tests/resilience.py`, urllib) и в режиме `safe` получал новое
соединение с репликой: в `safe` первый запрос сеанса никогда не идёт в
чужое простаивающее соединение.
Альтернативы:
- **Пул (`http-reuse safe`) и длинный keep-alive реплики** — первый
вариант, опровергнут проверкой (таблица выше).
- **`option http-server-close`.** LB закрывает соединение с репликой
после каждого ответа, и гонки нет совсем. Но каждый запрос — новое
TCP-соединение и новый объект протокола uvicorn: десятки
микросекунд CPU реплики на запрос. В треке 1 это заметно на потолке
RPS. Отвергнуто.
TCP-соединение и новый объект протокола uvicorn: десятки микросекунд
CPU реплики на запрос. В треке 1 это заметно на потолке RPS.
Отвергнуто.
- **`retry-on empty-response`.** LB повторил бы и запрос, который
реплика выполнила, а ответ потеряла. Для `POST /users` и `POST /chats`
это второй объект (`replicas-lb`, решение 4). Отвергнуто.
- **`http-reuse never`.** Соединение не делится между клиентами, но
остаётся за keep-alive соединением своего клиента. Гонку по сроку
простоя не убирает. Отвергнуто.
Остаётся гонка при SIGTERM: uvicorn сразу закрывает простаивающие
соединения. Окно — между закрытием и тем, как LB обработает FIN, то
есть доли миллисекунды. В режиме `safe` первый запрос клиентского
соединения никогда не идёт в чужое простаивающее соединение. Поэтому
клиенты с новым соединением на запрос, как `tests/resilience.py`, этой
гонки не встречают. Профиль `failover` (k6 держит keep-alive) её
измеряет: 502 в фазах `stop`. Если они появятся — Risks.
есть доли миллисекунды. Клиенты с новым соединением на запрос, как
`tests/resilience.py`, этой гонки не встречают: их запрос всегда идёт
по новому соединению с репликой. Профиль `failover` (k6 держит
keep-alive) её измерил в apply, фазы `stop` быстрого профиля:
| Режим LB | Фаз `stop` | Фаз с ошибкой | Ошибки |
|---|---|---|---|
| `http-reuse never` | 8 | 2 | по одному 502 через 0,07 с после SIGTERM |
| `http-reuse safe` | 9 | 1 | один 502 |
Разница в пределах случайности (одиночные события на ~4 600 запросов
фазы), а `never` ещё и убирает гонку по сроку простоя. Поэтому
`never`. Доля успешных в каждой секунде остаётся выше 99 %, время
восстановления — 0 с; дельта спека `graceful-shutdown` называет это
исключение прямо. Убрать гонку совсем может только дренаж перед
SIGTERM (readiness 503, затем остановка) — Risks.
### 4. `idle_in_transaction_session_timeout` 10 с
@@ -279,6 +308,7 @@ LB перед действием: слот получает адрес из DNS,
|---|---|
| обнаружение | первая строка исключения слота в журнале LB |
| первая запись / первое чтение | первый 201 / 200 среди запросов, отправленных после действия. При round-robin — почти сразу: вторая реплика обслуживает всё время. Это доказательство «новые чтения и записи продолжаются» |
| окно отказа | запросы, завершённые после действия и отправленные до возврата. Запрос в полёте в момент действия (на убитой или замороженной реплике) относится к окну отказа, а не к «до действия», хотя в шкале он — в секунде отправки (добавлено в apply: самопроверка `pause` пометила такие запросы как ошибки до действия) |
| последняя ошибка | отправка последнего неуспешного запроса окна отказа |
| восстановление | конец последней секунды с долей успеха < 99 %, 0 — если таких секунд нет. Секунда запроса — по моменту отправки: запрос, отправленный на зависшую реплику и получивший 504 через 10 с, относится к секунде отправки |
| возврат в LB | строка `is UP` от события возврата |
@@ -364,19 +394,40 @@ LB перед действием: слот получает адрес из DNS,
обеих реплик в LB (до 30 с);
6. сверка записей.
- **`k6/failover.js`.** Два сценария `constant-arrival-rate` —
запись и чтение, `maxVUs` с запасом под зависшую реплику: 100
запросов в секунду × 10 с ожидания 504.
запись и чтение. VU — с запасом под зависшую реплику: половина из 100
запросов в секунду сценария ждёт 504 10 с, то есть до 500 VU на
сценарий. Поэтому `failover_pre_vus` 600 создаются заранее, предел
`failover_max_vus` 1 500. Добавлено в apply: с 50 заранее созданными
k6 создавал VU на ходу и пропустил 352 итерации из 2 000 за окно
`pause`, интенсивность переставала быть постоянной. Пропуски
(`dropped_iterations`) пишутся в таблицу фаз и помечаются `dropped`.
Память k6 при 1 200 VU — около 400 МиБ.
- Запись — в чат записи, отправитель по кругу, текст
`syntheticText("f<фаза>", n)`. Ключ — `<прогон>.<фаза>.<n>`:
повтор строит тот же ключ без журнала ключей.
- Чтение — страница истории читаемого чата с курсором из пула, зерно
профиля, проверка полной страницы.
- Каждый запрос — строка `fo,<w|r>,<n>,<отправка мс>,<длительность
мс>,<статус>,<X-Instance-Id>` в вывод k6. Вывод пишется в файл
`.work/`, а не в трубу: 11 тысяч строк за фазу переполнили бы
буфер трубы, пока оркестратор ждёт момента действия.
мс>,<статус>,<X-Instance-Id>,<успех>`. Её пишет сам k6 в файл
`.work/` (`--console-output`), а не в вывод `docker exec`:
- 11 тысяч строк за фазу переполнили бы буфер трубы, пока
оркестратор ждёт момента действия;
- в первой самопроверке две строки из 4 601 пропали, и сверка
записей разошлась на одну.
Причина пропажи нашлась позже: строку с отрицательной длительностью
разбор не брал. Длительность считалась разностью `Date.now()`, а
часы ВМ подводятся и иногда шагают назад. Теперь длительность — по
монотонным таймингам k6 (`blocked + connecting + tls + duration`),
разность часов — только когда ответа нет. Разбор принимает знак и
не привязан к началу строки. Число строк каждого вида сверяется с
итерациями сценария из итога k6 (подметрики `iterations{scenario:…}`):
расхождение — отказ, неразобранные строки — в сообщении.
- **`lib.js`.** `messageHeaders(token, key)` и `sendMessage(..., key)`:
ключ можно задать. Без него — новый UUID, как раньше.
- **Отладка.** `run.py --modes stop,kill,pause` переопределяет режимы
профиля отказа (пишется в `overrides`, как прочие переопределения):
так режим `pause` проверяется без полного профиля.
- **Сверка (`k6/retry.js`).** Каждая неуспешная запись фазы
повторяется с тем же ключом и телом до 201, не больше 5 попыток. Затем
`psql` стенда:
@@ -422,11 +473,14 @@ LB перед действием: слот получает адрес из DNS,
`run-mtusi-messenger`. Только против стенда с LB:
- **`idle-conns [--keep-alive 60]`:**
1. всплеск запросов через LB с keep-alive соединениями;
2. статистика LB раз в секунду: `idle_conn_cur` и `safe_conn_cur` по
слотам;
3. итог — через сколько секунд пул пуст. Код 1, если пул не опустел
за срок keep-alive.
1. всплеск запросов через LB с keep-alive соединениями; клиенты
остаются подключены и молчат;
2. раз в секунду — установленные соединения на порт API внутри каждой
реплики (`/proc/net/tcp`) и пул LB (`idle_conn_cur` +
`safe_conn_cur`);
3. итог — через сколько секунд у реплик не осталось соединений. Код
1, если они держались дольше срока keep-alive реплики, то есть
закрывала реплика.
- **`hang-key`** — сценарий «Повтор ключа после зависшей реплики»:
1. синтетический пользователь и чат;
2. временный триггер задерживает вставку сообщения с одним пробным
@@ -447,7 +501,7 @@ LB перед действием: слот получает адрес из DNS,
|---|---|
| `evidence/failover/<метка>/` | полный профиль `failover`: 6 фаз, шкалы, таблица фаз; паспорт и состояние хоста (питание, память, `Swapouts` до и после) |
| `evidence/failover/detection.md` | замер обнаружения по фазам метки в сравнении с формулой решения 1; журнал LB вокруг действия |
| `evidence/failover/keep-alive.md` | `driver.py idle-conns`: пул LB пустеет раньше 60 с; до change — за ~5 с, закрывала реплика (разведка) |
| `evidence/failover/keep-alive.md` | `driver.py idle-conns`: соединения с репликами закрывает LB через ~10 с, раньше 60 с keep-alive реплики; до change и в первом варианте design закрывала реплика (таблица решения 3) |
| `evidence/failover/hung-key.md` | `driver.py hang-key`: повтор ключа после зависшей реплики; проверка настроек (`SHOW` на соединении приложения, отказ запуска при неверном сроке) |
| `evidence/tests/graceful-failover-checks.md` | регрессия на итоговом commit: `make test`, `student_test` через LB, `test_isolated`, `failure_checks`, `test-persistence`, `test-failover` (`stop` и `kill`), `bench_quick`, `bench_restore_quick`, `bench_failover_quick` |
@@ -470,14 +524,14 @@ LB перед действием: слот получает адрес из DNS,
## Risks / Trade-offs
- **[Гонка keep-alive при SIGTERM остаётся]** → окно — доли
миллисекунды. Клиенты с новым соединением на запрос её не встречают
(режим `safe`). Профиль `failover` её измеряет. Go-клиент (k6) сам
повторяет запрос на закрытом повторно используемом соединении, если
запрос повторяемый: `GET` или с заголовком `Idempotency-Key`. Тогда
она видна только как задержка. Если 502 появятся под нагрузкой, это
результат в отчёте и повод для дренажа перед SIGTERM (readiness 503,
затем остановка) — следующим change, со сменой спека
`graceful-shutdown`.
миллисекунды, под нагрузкой 200 запросов в секунду — одиночный 502 в
каждой 4–8-й фазе `stop` (решение 3). Клиенты с новым соединением на
запрос её не встречают. Отправку сообщения клиент повторяет с тем же
ключом. Убрать гонку совсем может дренаж перед SIGTERM: readiness 503,
LB выводит реплику за 1,5 с, затем остановка. Это меняет спек
`graceful-shutdown` (новые запросы после SIGTERM ещё принимаются) и
срок остановки (1,5 с + 8 с > 9 с hook), поэтому не в этом change.
Ограничение — в `REPORT.md`.
- **[`/health/ready` через общий пул]** → под перегрузкой проверка ждёт
пул, и реплика может выйти из LB. Таймаут 2 с — длиннее любого
ожидания в пределах SLO трека 1 (p95 200 мс), поэтому на сериях не
@@ -38,8 +38,9 @@ change `replicas-lb` ещё нет:
Худшее обнаружение зависшей реплики — 6,5 с вместо 8 с, вернувшаяся
реплика включается быстрее;
- uvicorn: `timeout_keep_alive` из новой настройки
`[app] keep_alive_seconds` (60 с) вместо неявных 5 с. Простаивающее
соединение LB → реплика закрывает LB, а не реплика;
`[app] keep_alive_seconds` (60 с) вместо неявных 5 с, HAProxy:
`http-reuse never`. Простаивающее соединение LB → реплика живёт не
дольше сеанса клиента (10 с) и закрывает его LB, а не реплика;
- PostgreSQL: `idle_in_transaction_session_timeout` на соединениях
приложения из новой настройки `[database]
idle_in_transaction_timeout_ms` (10 с). Транзакция замороженной
@@ -9,28 +9,45 @@
(требования выше). Новое соединение с ней LB SHALL получать как отказ
соединения и передавать такой запрос другой реплике. Поэтому штатная
остановка одной реплики из двух (`docker stop`) под постоянной
нагрузкой через LB MUST NOT давать клиенту ошибок: ни ответов 5xx, ни
обрывов. На время обнаружения отказа допустим только рост задержки.
нагрузкой через LB MUST NOT давать клиенту ошибок от недоступности
реплики. На время обнаружения отказа допустим рост задержки.
Единственное исключение — запрос, который LB отправил в простаивающее
keep-alive соединение в тот момент, когда реплика закрывает его при
остановке. Ответа на него нет, LB отвечает 502 и не повторяет его. Такие
ошибки SHALL учитываться. Доля успешных ответов в каждой секунде фазы
MUST NOT опускаться ниже 99 %.
#### Scenario: docker stop под нагрузкой
- **WHEN** через LB с постоянной интенсивностью идут запись с ключом и
чтение истории, и одна из двух реплик остановлена `docker stop`
- **THEN** все ответы фазы — 201 и 200, и это так для остановки каждой
из реплик по очереди
- **THEN** доля успешных ответов в каждой секунде фазы не ниже 99 %,
время восстановления 0 с, а неуспешные ответы, если есть, — одиночные
502 в момент SIGTERM; так для остановки каждой из реплик по очереди
#### Scenario: Клиент с новым соединением на запрос
- **WHEN** клиент открывает новое соединение на каждый запрос, как
публичная проверка `make test-failover`, и реплика остановлена
`docker stop`
- **THEN** клиент не получает ни одной ошибки: его запрос не идёт в
простаивающее соединение с репликой
### Requirement: Простаивающие соединения закрывает балансировщик
Реплика SHALL держать простаивающее keep-alive соединение дольше, чем
LB держит такое соединение в своём пуле. Тогда простаивающее
LB держит простаивающее соединение с ней. Тогда простаивающее
соединение LB → реплика закрывает LB, и он не отправляет запрос в
соединение, которое реплика в этот момент закрывает. Срок простоя на
стороне реплики SHALL задаваться настройкой `[app]
keep_alive_seconds`.
keep_alive_seconds`. LB MUST NOT держать простаивающие соединения с
репликой дольше своего срока простоя клиентского соединения.
#### Scenario: Пул балансировщика после всплеска
#### Scenario: Клиенты молчат после всплеска
- **WHEN** через LB прошёл всплеск запросов, а затем запросов нет
- **THEN** число простаивающих соединений LB к каждой реплике в
статистике LB становится нулевым раньше `keep_alive_seconds` с
момента последнего запроса
- **WHEN** через LB прошёл всплеск запросов от клиентов с keep-alive, а
затем клиенты остаются подключены и молчат
- **THEN** соединения на порт API внутри каждой реплики закрываются
раньше `keep_alive_seconds` с момента последнего запроса, по сроку
простоя LB
+9 -7
View File
@@ -12,7 +12,7 @@ evidence, потом коммит evidence и отчёта. Замеры для
## 1. Приложение: сроки простоя соединений
- [ ] 1.1 `src/config/settings.py` и `config_example.toml` по решениям
- [x] 1.1 `src/config/settings.py` и `config_example.toml` по решениям
3 и 4:
- `[app] keep_alive_seconds` (int, ≥ 1, по умолчанию 60);
- `[database] idle_in_transaction_timeout_ms` (int, ≥ 0, по умолчанию
@@ -23,7 +23,7 @@ evidence, потом коммит evidence и отчёта. Замеры для
Проверка: `uv run python -c` печатает поля по умолчанию; запуск с
`APP__KEEP_ALIVE_SECONDS=0`, `DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=abc`
и `=5000` — код 1, ошибка называет поле.
- [ ] 1.2 `src/main.py`: `timeout_keep_alive` у `uvicorn.run`.
- [x] 1.2 `src/main.py`: `timeout_keep_alive` у `uvicorn.run`.
`src/infra/db/engine.py`: `idle_in_transaction_session_timeout` в
`server_settings`, если значение не 0. Проверка: `SHOW
idle_in_transaction_session_timeout` на соединении engine приложения
@@ -31,10 +31,12 @@ evidence, потом коммит evidence и отчёта. Замеры для
## 2. Балансировщик
- [ ] 2.1 `infra/haproxy/haproxy.cfg` по решениям 1–3:
- [x] 2.1 `infra/haproxy/haproxy.cfg` по решениям 1–3:
- `fastinter 500ms` в `default-server`;
- `timeout check 2500ms`;
- `pool-purge-delay 5s` в `backend api`;
- `http-reuse never` в `backend api` (вместо `pool-purge-delay 5s`
первого варианта: проверка `idle-conns` его опровергла, design,
решение 3);
- комментарии к числам — формулы обнаружения по режимам из таблицы
решения 1 и соотношение с `keep_alive_seconds`.
@@ -73,8 +75,8 @@ evidence, потом коммит evidence и отчёта. Замеры для
- [ ] 4.1 `.claude/skills/run-mtusi-messenger/driver.py` и `SKILL.md`
по решению 8: `idle-conns`, `hang-key`. Проверка на рабочем стенде
после пересоздания с новым кодом:
- `driver.py --port 8080 idle-conns` — пул LB пуст раньше 60 с, код
0;
- `driver.py --port 8080 idle-conns` — у реплик не осталось
соединений раньше 60 с (их закрыл LB), код 0;
- `driver.py --port 8080 hang-key` — повтор ключа получает 201 после
прерывания транзакции, одно сообщение, в журнале PostgreSQL —
«idle-in-transaction timeout»; триггера после команды нет.
@@ -83,7 +85,7 @@ evidence, потом коммит evidence и отчёта. Замеры для
- [ ] 5.1 Правила и инструкции под решения:
- `balancer.md` — цепочка (`fastinter`, `timeout check`,
`pool-purge-delay` и keep-alive, обнаружение по режимам);
`http-reuse never` и keep-alive, обнаружение по режимам);
- `bench.md` — стенд с LB и N репликами, профиль `failover`, его
результаты, методика лабы 3;
- `run-modes.md` — `timeout_keep_alive`;
+29
View File
@@ -8,6 +8,7 @@ from pydantic import (
BeforeValidator,
Field,
SecretStr,
ValidationInfo,
field_validator,
)
from pydantic_settings import (
@@ -40,6 +41,12 @@ class App(BaseModel):
# секунды, которые uvicorn ждёт текущие запросы после SIGTERM;
# docker шлёт SIGKILL через 10 с, поэтому не больше 9
graceful_shutdown_seconds: int = Field(default=8, ge=1, le=9)
# секунды, которые uvicorn держит простаивающее keep-alive соединение.
# Больше, чем HAProxy держит простаивающий сеанс клиента, а с ним и
# соединение с репликой (timeout http-keep-alive 10 с и http-reuse
# never в infra/haproxy/haproxy.cfg): закрывает LB, а не реплика, и
# запрос не уходит в закрывающееся соединение
keep_alive_seconds: int = Field(default=60, ge=1)
# X-Instance-Id и поле instance_id журнала. Пусто — hostname процесса
# (в compose — короткий ID контейнера). В config.toml, .env и compose
# не задавать: эти источники общие у реплик, а значение должно
@@ -88,6 +95,28 @@ class Database(BaseModel):
# секунды на всю работу запроса с БД (asyncio): зависший сервер или
# обрыв сети, где серверный таймаут не сработает
request_timeout_seconds: float = Field(default=6, gt=0)
# миллисекунды, серверный idle_in_transaction_session_timeout: открытую
# транзакцию замороженной реплики PostgreSQL прерывает и снимает её
# блокировки (ключ идемпотентности); 0 — без ограничения
idle_in_transaction_timeout_ms: int = Field(default=10000, ge=0)
@field_validator("idle_in_transaction_timeout_ms")
@classmethod
def idle_longer_than_request(cls, value: int, info: ValidationInfo) -> int:
"""Срок простоя транзакции больше срока работы запроса с БД.
Транзакция живого запроса дольше `request_timeout_seconds` не
живёт: прерывать её PostgreSQL не должен. Проверка на поле, а не
на секции: в ошибке валидатора секции было бы всё её значение,
вместе с паролем.
"""
request = info.data.get("request_timeout_seconds")
if value and request is not None and value <= request * 1000:
raise ValueError(
"must be 0 or greater than request_timeout_seconds in "
"milliseconds",
)
return value
@property
def url(self) -> URL:
+12 -4
View File
@@ -37,6 +37,17 @@ class BoundedCloseConnection(asyncpg.Connection):
def create_engine(database: Database) -> AsyncEngine:
"""Engine с ограниченным пулом и таймаутами из `[database]`."""
server_settings = {
"application_name": DB_APPLICATION_NAME,
"statement_timeout": str(database.statement_timeout_ms),
}
if database.idle_in_transaction_timeout_ms:
# транзакцию замороженного процесса (docker pause) PostgreSQL
# прерывает сам: TCP-соединение живо, и иначе её блокировки, в
# том числе ключа идемпотентности, держались бы до разморозки
server_settings["idle_in_transaction_session_timeout"] = str(
database.idle_in_transaction_timeout_ms,
)
return create_async_engine(
database.url,
pool_size=database.pool_size,
@@ -55,10 +66,7 @@ def create_engine(database: Database) -> AsyncEngine:
connect_args={
"timeout": database.connect_timeout_seconds,
"connection_class": BoundedCloseConnection,
"server_settings": {
"application_name": DB_APPLICATION_NAME,
"statement_timeout": str(database.statement_timeout_ms),
},
"server_settings": server_settings,
},
)
+3
View File
@@ -74,6 +74,9 @@ def main() -> None:
# процесс
workers=1,
timeout_graceful_shutdown=settings.app.graceful_shutdown_seconds,
# простаивающее соединение закрывает HAProxy раньше реплики
# (design change graceful-failover, решение 3)
timeout_keep_alive=settings.app.keep_alive_seconds,
# логи uvicorn идут через наш JSON-форматтер (src/infra/logger.py)
log_config=None,
access_log=False,