Files
mtusi2026lab5/experiments/docs/RUNBOOK.md
T

7.5 KiB
Raw Blame History

Запуск

Окружение

Требования: WSL Ubuntu, Linux Docker Engine с интеграцией Docker Desktop, Docker Compose с поддержкой config --format json, Python 3.9+ и Git. При первой сборке нужен доступ к реестрам образов и пакетов.

python3 -m unittest discover -s experiments/tests -v

Порты 18085 и 18900 должны быть свободны. Для стенда рекомендуется выделить около 6 GiB памяти Docker и несколько GiB диска. Первая сборка и основная серия могут занять более часа. Параллельные сборки, нагрузочные тесты и другие серии меняют условия выполнения и должны быть остановлены на время измерений.

До прогрева runner ожидает готовности приложения RabbitMQ и доступности списка очередей. На запуск стенда и эту проверку отводится общий интервал 300 секунд. Попытки записываются в broker-startup.jsonl, успешная проверка — в broker-readiness-r*.json. Во время сценариев ошибка чтения очереди завершает проверку и сохраняется в журнале команд.

Эксперимент использует отдельный Compose project. Учебный highload-lab5 не перезапускается. При нехватке ресурсов его можно остановить отдельно, сохранив тома.

Снимок исходников

experiment_seal=$(python3 experiments/run.py seal)
printf '%s\n' "$experiment_seal"

Команда создаёт каталог evidence/idempotency/seals/... с manifest.json и source.zip. В manifest записаны SHA-256 файлов и протокола, Git HEAD и признак незакоммиченных изменений. Контейнеры при этом не запускаются.

Значение experiment_seal используется в следующих командах. В новом терминале оно задаётся сохранённым путём:

experiment_seal=evidence/idempotency/seals/ИМЯ_СНИМКА

Runner проверяет контрольные суммы перед серией и каждым повтором. После изменения исходников требуется новый снимок; после изменения методики — также новая версия протокола. Существующие данные серий сохраняются.

Пилот

python3 experiments/run.py run --phase pilot --seal "$experiment_seal"

Пилот выполняет девять сценариев для rgb_small в одном повторе. В конце выводится путь публичного архива. Условия перехода к основной серии в summary.json:

complete: true
completed: 9
violations: 0
invalid: 0
missing_artifacts: []
outcome: pilot_only_not_confirmation

При ошибке пилота основная серия откладывается до диагностики. Данные пилота хранятся отдельно и не включаются в основную выборку.

Основная серия

python3 experiments/run.py run --phase main --seal "$experiment_seal"

Runner выполняет 135 случаев. Каждый из пяти повторов получает новые тома, сети и учётные данные. Порядок случаев и seed записываются в результаты. После каждого повтора docker compose down удаляет его контейнеры и сети. Именованные тома с данными сохраняются; параметр --volumes не используется.

Изменение кода во время серии или повторный запуск только неудачных случаев нарушают сопоставимость данных. Исправленная реализация проверяется отдельной серией с новым снимком исходников.

Результаты

Все файлы размещаются в evidence/idempotency/:

Путь внутри серии Содержимое
docs/, protocol.json, seal/ Методика, параметры и исходники
fixtures/ Исходные PNG и контрольные суммы
cases.jsonl, cases/ Исходы случаев, наблюдения API, состояния БД, аудит и варианты изображений
environment-r*.json, order-r*.json Образы, ресурсы и порядок выполнения
docker-events-r*.jsonl События контейнеров, включая OOM и завершения
command-errors.jsonl Ошибки команд с маскированием учётных данных
summary.json Сводка по сценариям и профилям
.private/ Учётные данные и рабочие конфигурации стенда

Архив для анализа создаётся рядом с каталогом серии: evidence/idempotency/main-...-public.zip или pilot-...-public.zip. В него не включается .private. Для передачи результатов используется этот архив; полный каталог серии содержит пароли и строки подключения.

Публичные результаты и журналы запуска доступны Git. Корневой .gitignore исключает только .private/ и служебный .run.lock внутри evidence/. Данные evidence/ не включаются в новые снимки исходников.

Повторная агрегация без запуска стенда:

python3 experiments/run.py analyze evidence/idempotency/main-ИМЯ_СЕРИИ

Создание архива после прерванного запуска:

python3 experiments/run.py pack evidence/idempotency/main-ИМЯ_СЕРИИ

pack не перезаписывает существующий архив. Значения итогового поля outcome описаны в HYPOTHESIS.md.

Прерывание и остановка

При Ctrl+C сохраняются собранные данные и признак прерванной серии. После kill -9 или сбоя host автоматическая остановка может не выполниться. Имена созданных project находятся в manifest.json. Остановка выбранного повтора:

docker compose --project-name ИМЯ_ИЗ_MANIFEST \
  -f evidence/idempotency/ИМЯ_СЕРИИ/.private/r1/compose.json down

Тома сохраняются до завершения анализа. Глобальные команды docker stop и docker prune для управления экспериментом не используются.