Files
mtusi2026lab5/experiments/docs/RUNBOOK.md
T

137 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Запуск
## Окружение
Требования: WSL Ubuntu, Linux Docker Engine с интеграцией Docker Desktop,
Docker Compose с поддержкой `config --format json`, Python 3.9+ и Git.
При первой сборке нужен доступ к реестрам образов и пакетов.
```sh
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` не
перезапускается. При нехватке ресурсов его можно остановить отдельно, сохранив тома.
## Снимок исходников
```sh
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` используется в следующих командах. В новом терминале
оно задаётся сохранённым путём:
```sh
experiment_seal=evidence/idempotency/seals/ИМЯ_СНИМКА
```
Runner проверяет контрольные суммы перед серией и каждым повтором. После изменения
исходников требуется новый снимок; после изменения методики — также новая версия
протокола. Существующие данные серий сохраняются.
## Пилот
```sh
python3 experiments/run.py run --phase pilot --seal "$experiment_seal"
```
Пилот выполняет девять сценариев для `rgb_small` в одном повторе. В конце выводится
путь публичного архива. Условия перехода к основной серии в `summary.json`:
```text
complete: true
completed: 9
violations: 0
invalid: 0
missing_artifacts: []
outcome: pilot_only_not_confirmation
```
При ошибке пилота основная серия откладывается до диагностики. Данные пилота
хранятся отдельно и не включаются в основную выборку.
## Основная серия
```sh
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/` не включаются в новые снимки исходников.
Повторная агрегация без запуска стенда:
```sh
python3 experiments/run.py analyze evidence/idempotency/main-ИМЯ_СЕРИИ
```
Создание архива после прерванного запуска:
```sh
python3 experiments/run.py pack evidence/idempotency/main-ИМЯ_СЕРИИ
```
`pack` не перезаписывает существующий архив. Значения итогового поля `outcome`
описаны в [HYPOTHESIS.md](HYPOTHESIS.md).
## Прерывание и остановка
При Ctrl+C сохраняются собранные данные и признак прерванной серии.
После kill -9 или сбоя host автоматическая остановка может не выполниться.
Имена созданных project находятся в `manifest.json`. Остановка выбранного повтора:
```sh
docker compose --project-name ИМЯ_ИЗ_MANIFEST \
-f evidence/idempotency/ИМЯ_СЕРИИ/.private/r1/compose.json down
```
Тома сохраняются до завершения анализа. Глобальные команды `docker stop` и
`docker prune` для управления экспериментом не используются.