docs: archive profile-resources and sync its specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-12 19:28:03 +03:00
co-authored by Claude Opus 5.5
parent 2514ff177d
commit 3416ca16b9
8 changed files with 223 additions and 19 deletions
+7 -8
View File
@@ -21,15 +21,14 @@ API HAProxy (`make rolling_update`), expand-миграция и профиль
насыщение пула и PostgreSQL управляемыми опытами) и ответ 503 на отказ
PostgreSQL «too many clients», `scaling-improvement` — пул PostgreSQL
10 + 0 без переполнения (улучшение трека 1: профиль `SERIES=db4`,
«до/после» с A/A, засчитано с оговоркой). Лаба 3 закрыта: все шесть
«до/после» с A/A, засчитано с оговоркой), `profile-resources` — CPU и
память каждого компонента по окнам профилей `failover` и `rollout`
(сэмплер `scan`, `bench/resources.py`, метки `resources`; добавлен после
закрытия лабы, код приложения не трогает). Лаба 3 закрыта: все семь
changes лабы 3, как и changes перехода на lab2, — в
`openspec/changes/archive/`, `REPORT.md` заполнен, чистый clone
проверен (`evidence/tests/clean-clone-final.md`). После закрытия —
седьмой change `profile-resources`: CPU и память каждого компонента
по окнам профилей `failover` и `rollout` (сэмплер `scan`,
`bench/resources.py`, метки `resources`); код приложения он не трогает,
до archive — в `openspec/changes/`. Дальше — перенос в
лабу 4 (раздел «Переход в следующую лабу»). Рабочий план лабы
`openspec/changes/archive/`, активных changes нет, `REPORT.md` заполнен,
чистый clone проверен (`evidence/tests/clean-clone-final.md`). Дальше —
перенос в лабу 4 (раздел «Переход в следующую лабу»). Рабочий план лабы
(`PLAN.md`) удалён, его решения — в `REPORT.md` и design архивных
changes; последняя версия — `git show 063eedb:PLAN.md`. Стек:
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
+5 -4
View File
@@ -2442,10 +2442,11 @@ structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn
`.claude/rules/logging.md`).
**Использование ИИ.** Инструмент — Claude Code, модель Claude Opus 5.5.
Работа велась по changes OpenSpec (`openspec/changes/archive/`, шесть
changes лабы 3, и седьмой — `profile-resources`, CPU и память профилей
уровня «4», после закрытия лабы). Каждый change проходил этапы propose → apply → verify →
правки по verify и archive. Каждый этап выполнял отдельный субагент,
Работа велась по changes OpenSpec (`openspec/changes/archive/`: семь
changes лабы 3, седьмой — `profile-resources`, CPU и память профилей
уровня «4», добавлен после закрытия лабы; все в архиве, спеки
синхронизированы). Каждый change проходил этапы propose → apply →
verify → правки по verify и archive. Каждый этап выполнял отдельный субагент,
основная сессия координировала: передавала этапы, проверяла итоги,
присылала автору прогресс. Все commit после skeleton помечены
`Co-Authored-By: Claude Opus 5.5`, кроме четырёх, которые сделал скрипт
+211 -7
View File
@@ -1059,6 +1059,16 @@ git не идёт. Результаты SHALL сохраняться в `evidenc
- время восстановления до доли успешных ≥ 99 % (`load-balancing`);
- время до возврата реплики в LB.
Для каждой фазы SHALL сохраняться ресурсы стенда по требованию «Ресурсы
профилей отказа и замены». Окна:
- до действия — от конца разгона генератора;
- окно отказа — от действия до возврата;
- после возврата — до последнего запроса фазы.
Компоненты — каждая реплика отдельно, с её `X-Instance-Id` и пометкой,
над какой выполнено действие, сумма по репликам, PostgreSQL, LB, Valkey,
генератор и ВМ.
После каждой фазы каждая неподтверждённая запись SHALL повторяться с
тем же ключом и тем же телом до ответа 201. Число сообщений чата записи
SHALL совпадать с числом разных ключей, отправленных за прогон, а
@@ -1069,14 +1079,15 @@ SHALL совпадать с числом разных ключей, отправ
- **WHEN** выполнен `make bench_failover`
- **THEN** в `evidence/failover/<метка>/` есть шесть фаз (две реплики ×
три режима) с посекундными шкалами, таблица фаз и сводка, код выхода
0
три режима) с посекундными шкалами, таблица фаз, ресурсы по окнам
фаз и сводка, код выхода 0
#### Scenario: Быстрый профиль
- **WHEN** выполнен `make bench_failover_quick`
- **THEN** за несколько минут проходят четыре фазы (две реплики ×
`stop` и `kill`), код выхода 0, каталог метки в git не попадает
`stop` и `kill`) с ресурсами по окнам, код выхода 0, каталог метки в
git не попадает
#### Scenario: Время обнаружения в результатах
@@ -1099,6 +1110,25 @@ SHALL совпадать с числом разных ключей, отправ
- **THEN** команда завершается с ненулевым кодом, называет контейнер, а
стенд удаляется
#### Scenario: Ресурсы фазы
- **WHEN** фаза завершена
- **THEN** в таблице ресурсов для каждого из трёх окон есть CPU (среднее
и посекундный максимум) и пик памяти реплики, над которой выполнено
действие, и второй реплики с их `X-Instance-Id`, а также суммы по
репликам, PostgreSQL, LB, Valkey, генератора и занятые ядра ВМ
- **AND** посекундная таблица содержит те же компоненты в секундах от
момента действия, на тех же часах, что шкала фазы
#### Scenario: Реплика остановлена или заморожена
- **WHEN** реплика остановлена `stop`, убита `kill` или заморожена
`pause`, а затем возвращена
- **THEN** её CPU в окне отказа учтён только до остановки, у
замороженной — без прироста, после возврата счёт продолжается от
запуска или разморозки, а значения второй реплики и остальных
компонентов есть во всех окнах
### Requirement: Профиль поочерёдной замены
Команда `make bench_rollout` (метка `ROLLOUT_LABEL`) SHALL на свежем
@@ -1139,6 +1169,18 @@ SHALL сохраняться посекундная шкала от начала
- минимальная доля успешных в секунде;
- контейнеры, их образы и ревизия схемы до и после.
Ресурсы стенда SHALL сохраняться по требованию «Ресурсы профилей отказа
и замены». Окна:
- до запуска скрипта — от конца разгона генератора;
- подготовка — от первого обращения скрипта к стенду до начала замены:
проверки и сборка образа;
- замена — от начала замены до удаления последней старой реплики;
- после замены — до последнего запроса.
Компоненты — каждая старая и каждая новая реплика отдельно, с её
`X-Instance-Id`, сумма по репликам с пиком их общей памяти, контейнер
миграции, PostgreSQL, LB, Valkey, генератор и ВМ.
После прогона каждая неподтверждённая запись SHALL повторяться с тем
же ключом и телом до 201. Число сообщений чата записи SHALL совпадать
с числом отправленных ключей, одинаковых текстов MUST NOT быть.
@@ -1159,14 +1201,14 @@ SHALL сохраняться посекундная шкала от начала
- **WHEN** выполнен `make bench_rollout`
- **THEN** в `evidence/rollout/<метка>/` есть посекундная шкала, таблица
шагов по каждой заменённой реплике, сводка, контейнеры и образы до и
после, код выхода 0
шагов по каждой заменённой реплике, ресурсы по окнам, сводка,
контейнеры и образы до и после, код выхода 0
#### Scenario: Быстрый профиль
- **WHEN** выполнен `make bench_rollout_quick`
- **THEN** за несколько минут проходит замена всех реплик, код выхода 0,
каталог метки в git не попадает
- **THEN** за несколько минут проходит замена всех реплик с ресурсами
по окнам, код выхода 0, каталог метки в git не попадает
#### Scenario: Версии в ответах
@@ -1188,6 +1230,168 @@ SHALL сохраняться посекундная шкала от начала
- **THEN** команда завершается с ненулевым кодом, называет шаг из
журнала скрипта, сохраняет частичные результаты и удаляет стенд
#### Scenario: Ресурсы замены
- **WHEN** замена завершена
- **THEN** в таблице ресурсов для окон до, подготовки, замены и после
есть CPU и пик памяти каждой старой и каждой новой реплики с их
`X-Instance-Id`, контейнера миграции, суммы по репликам с пиком их
общей памяти, PostgreSQL, LB, Valkey, генератора и занятые ядра ВМ
- **AND** CPU на успешный запрос указан для окон до и после замены
#### Scenario: Новая реплика с первых секунд
- **WHEN** скрипт запускает новую реплику посреди нагрузки
- **THEN** её CPU и память есть в посекундной таблице с первого отсчёта
после её запуска, а CPU от запуска до этого отсчёта входит в окно, где
она запущена
### Requirement: Ресурсы профилей отказа и замены
Профили отказа реплик и поочерёдной замены, полные и быстрые, SHALL всё
время нагрузки снимать не реже раза в секунду, на часах ВМ Docker:
- CPU, троттлинг CFS и память каждого контейнера стенда — каждой
реплики приложения, PostgreSQL, LB, Valkey и контейнера миграции;
- те же величины генератора нагрузки и самого наблюдателя;
- загрузку CPU ВМ.
Контейнер, созданный во время прогона, SHALL учитываться с первого
отсчёта после его запуска, без перезапуска наблюдения. CPU от запуска
контейнера до первого отсчёта MUST NOT теряться. Остановленный,
убитый, замороженный, пересозданный или удалённый контейнер MUST NOT
ломать расчёт:
- пока контейнера нет, он не потребляет CPU и не даёт отсчётов памяти;
- у замороженного CPU не прирастает, память остаётся;
- у запущенного снова счёт идёт с нуля от момента запуска.
Отсчёты контейнеров вне стенда MUST NOT попадать в результаты.
Для каждого окна прогона (требования профилей) и каждого компонента
SHALL сохраняться:
- среднее CPU за окно — CPU-секунды, делённые на длину окна;
- наибольшее посекундное CPU;
- пик памяти;
- доля периодов CFS с троттлингом;
- сколько секунд окна контейнер работал;
- у реплик ещё сумма по всем репликам с пиком их общей памяти;
- у ВМ — среднее и наибольшее посекундное число занятых ядер.
CPU на один успешный запрос SHALL указываться только в установившихся
окнах: до действия у профиля отказа, до и после замены у профиля
замены. В остальных окнах его MUST NOT указывать: там CPU уходит на
ошибки и ожидание, на остановку и запуск процессов, на миграцию и
сборку, а не пропорционально успешным ответам. Сводка SHALL называть эту
причину.
Посекундные значения SHALL сохраняться таблицей: фаза, окно, секунды от
опорного момента (действие над репликой или начало замены), компонент,
CPU, троттлинг, ожидание CPU и память. Значения по окнам SHALL
сохраняться второй таблицей. Сводка метки SHALL показывать их по
компонентам и окнам.
Наблюдение MUST NOT менять методику профиля: нагрузку, фазы, окна,
лимиты стенда и пороги. Генератор остаётся без лимита. Наблюдатель:
- SHALL работать в своём контейнере со своим лимитом CPU и памяти без
swap; лимит читается у запущенного контейнера и пишется в паспорт;
- SHALL брать отсчёты только из счётчиков cgroup контейнеров и ВМ;
- MUST NOT запускать процессы в контейнерах стенда и MUST NOT
обращаться к приложению, хранилищам и LB.
Сумма лимитов CPU стенда на пике прогона и наблюдателя MUST NOT
превышать число CPU ВМ. На пике профиля замены работает `API_REPLICAS`
+ 1 реплик. Иначе команда завершается с ненулевым кодом до запуска
стенда. Паспорт SHALL содержать сумму лимитов CPU и памяти, а также CPU
и память ВМ.
Если в окне нагрузки отсчётов нет дольше трёх секунд или наблюдатель
остановился, команда SHALL завершаться с ненулевым кодом и называть
фазу.
#### Scenario: Ресурсы в результатах
- **WHEN** выполнен `make bench_failover` или `make bench_rollout`
- **THEN** в каталоге метки есть посекундная таблица и таблица по
окнам, сводка показывает CPU и память каждого компонента по окнам, а
паспорт — лимит наблюдателя и бюджет ВМ
#### Scenario: Контейнер вне стенда
- **WHEN** во время прогона в ВМ работает контейнер другого проекта
- **THEN** его отсчётов нет ни в посекундной таблице, ни в таблице по
окнам
#### Scenario: Бюджет ВМ
- **WHEN** сумма лимитов CPU стенда на пике и наблюдателя больше числа
CPU ВМ
- **THEN** команда завершается с ненулевым кодом до запуска стенда и
называет сумму и число CPU ВМ
#### Scenario: Наблюдение не меняет методику
- **WHEN** проверяющий сравнивает паспорт новой метки профиля с
паспортом прежней метки того же профиля
- **THEN** нагрузка, окна, лимиты стенда и пороги совпадают, генератор
без лимита в обеих, а новые поля относятся только к наблюдению
#### Scenario: CPU на запрос только в установившихся окнах
- **WHEN** окно содержит действие над репликой, её возврат, миграцию
или замену реплик
- **THEN** CPU на успешный запрос для этого окна не указан, а сводка
называет причину
#### Scenario: Наблюдатель остановился
- **WHEN** во время нагрузки отсчётов нет дольше трёх секунд
- **THEN** команда завершается с ненулевым кодом и называет фазу, а
стенд удаляется
#### Scenario: Наблюдатель не нагружает стенд
- **WHEN** идёт нагрузка профиля отказа или замены
- **THEN** у PostgreSQL нет соединений наблюдателя, в контейнерах стенда
нет его процессов, а его собственные CPU и память видны в таблицах
отдельным компонентом
### Requirement: Ресурсы профилей отказа и замены в отчёте
Метки профилей отказа и замены с ресурсами SHALL сохраняться в
`evidence/failover/` и `evidence/rollout/`. Их снимают с закоммиченного
кода на хосте, состояние которого записано в паспорт. `REPORT.md` SHALL
показывать для обоих профилей:
- CPU и память по компонентам и окнам;
- CPU на запрос в установившихся окнах;
- занятые ядра ВМ;
- лимиты и бюджет ВМ;
- накладные расходы наблюдения: его собственные CPU и память;
- ограничения замера.
Числа SHALL переноситься из файлов меток, со ссылками на них.
Результаты новых меток по доступности SHALL стоять рядом с прежними
метками тех же профилей, с названными различиями условий: commit и
хост. Для профиля отказа это исключение из LB, ошибки, восстановление,
возврат в LB и сверка записей. Для профиля замены — ошибки,
длительность и шаги замены, ответы старых реплик после дренажа и
сверка записей. Если результаты расходятся, отчёт SHALL это говорить и
называть причину, а если она не установлена — говорить и это.
#### Scenario: Проверяющий ищет CPU и память при отказе
- **WHEN** проверяющий открывает в `REPORT.md` раздел отказа реплик или
поочерёдной замены
- **THEN** он находит CPU и память каждой реплики, PostgreSQL, LB,
Valkey, генератора и ВМ по окнам, CPU на запрос в установившихся
окнах, накладные расходы наблюдения и пути к файлам меток
#### Scenario: Новая метка расходится с прежней
- **WHEN** в новой метке число ошибок, время исключения, восстановления
или шаги замены отличаются от прежней метки сверх её разброса
- **THEN** отчёт приводит оба значения, называет различия условий и
причину расхождения или пишет, что она не установлена
### Requirement: Серии трека 1
Команда `make bench_scaling SERIES=<серия>` SHALL снимать серию трека 1