Files
mtusi2026lab5/experiments/docs/METHODOLOGY.md
T

116 lines
9.7 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.
# Методика
## Система и конфигурация
API сохраняет оригинал в S3 и задание в PostgreSQL. Dispatcher публикует задания
в RabbitMQ с publisher confirms. Worker подтверждает сообщение после фиксации
результата или следующей попытки в PostgreSQL.
Версии обработки различаются параметрами кодирования:
| Параметр | v1 | v2 |
| --- | --- | --- |
| Качество JPEG для thumbnail и crop | 85 | 75 |
| Качество WebP | 80 | 65 |
| Thumbnail | Вписывание в 256×256 без увеличения | То же |
| Crop | Центрированный квадрат 128×128 | То же |
| Optimized | Вписывание в 1280×1280 без увеличения | То же |
Оригинал сохраняется без изменений. Ключи производных имеют вид
`variants/{attachment_id}/v{version}/{variant}`. В PostgreSQL хранятся запрошенная
и опубликованная версии. Обновление версии выполняется административной командой
и сопровождается аудитом. Публикация результата проверяет версию и lease token.
| Компонент | Количество | CPU на экземпляр | Память на экземпляр |
| --- | --- | --- | --- |
| API | 2 | 0.5 | 512 MiB |
| Worker | 2 | 1 | 512 MiB |
Prefetch — 1; пул БД — 10 соединений на процесс; timeout обработки изображения —
10 секунд; срок lease — 30 секунд; максимум попыток — 5. Временные файлы worker
размещаются в tmpfs объёмом 64 MiB. Лимиты PostgreSQL, Redis, RabbitMQ и S3 берутся
из основного Compose. Фактические image ID и ресурсы записываются для каждого повтора.
## План серии
Независимые переменные: сценарий отказа или доставки, профиль изображения,
запрошенная версия обработки. Контроль — обработка v1 без введённого отказа.
| Профиль | Размер | Прозрачность |
| --- | --- | --- |
| `rgb_small` | 320×200 | Нет |
| `rgba_medium` | 640×360 | Есть |
| `rgb_large` | 1600×1000 | Нет |
PNG генерируются детерминированно с seed 2303. Файлы и их SHA-256 сохраняются.
Все изображения укладываются в ограничения worker.
Основная серия включает пять повторов. В каждом выполняются 27 сочетаний
«профиль × сценарий». Их порядок перемешивается с seed `2303 + номер повтора`.
Итого — 135 случаев. Запросы управляющего клиента выполняются последовательно;
одновременно работают не более двух целевых попыток.
Каждый повтор использует новый Compose project, учётные данные, сети и тома.
Перед блоком выполняется одна загрузка для прогрева. Каждый случай получает
собственных пользователей, чат, вложение и задания. Перед началом случая очередь
пуста, заданий в `queued` и `processing` нет.
Пилот содержит девять сценариев для `rgb_small` и один повтор. Его данные
хранятся отдельно от основной серии.
## Сценарии
| Сценарий | Последовательность событий | Проверка |
| --- | --- | --- |
| `control` | Обработка v1 без отказа | Один готовый комплект вариантов |
| `duplicates` | Пять дублей до запуска worker и пять после `ready` | Число попыток и публикаций не увеличивается из-за терминальных дублей |
| `reorder` | Запрошена v2; при остановленном dispatcher в очередь передаются v2, затем v1 | Публикуется v2, задание v1 остаётся как `superseded` |
| `commit_publish_gap` | Dispatcher завершается после COMMIT загрузки, до publish | Сохранённое задание восстанавливается после запуска процесса |
| `crash_before_effect` | Worker завершается после захвата задания, до записи объектов | По истечении lease другая попытка завершает задание |
| `crash_after_effect` | Worker завершается после записи объектов, до COMMIT результата | Повтор использует те же ключи; результат публикуется один раз |
| `crash_before_ack` | Worker завершается после COMMIT результата, до ACK | Повторная доставка не запускает обработку заново |
| `old_after_v2` | Опубликованы v1 и v2; затем доставляется старая v1 | Контрольные суммы и опубликованная версия v2 сохраняются |
| `stale_lease` | Попытка v1 приостановлена после захвата; другой worker завершает v2; попытка v1 продолжена | Старый lease token отвергается до выполнения записи |
Завершение процесса вызывается через `os.Exit(86)` в выбранной точке. Одноразовый
файл-маркер переименовывается в `.hit`. Управляемая пауза снимается release-файлом
или истечением timeout. Для `stale_lease` дополнительно регистрируется прохождение
ветки отказа по устаревшему token.
В сценариях `old_after_v2` и `stale_lease` готовность v2 проверяется до доставки
старого сообщения или снятия паузы. Отсутствие нужного маркера делает случай
невалидным. На завершение задания отводится 180 секунд после восстановления
процессов или снятия паузы; сборка и запуск стенда в этот интервал не входят.
## Сбор данных
Для каждой серии сохраняются:
- SHA-256 протокола и исходников, архив исходников, Git HEAD и признак изменений;
- версии Docker, Compose, Python и сведения о host;
- image ID, лимиты ресурсов, seed, порядок случаев и исходные изображения;
- события контроллера с UTC и монотонным временем;
- ответы API, состояния заданий, аудит попыток и журнал публикаций PostgreSQL;
- содержимое вариантов и контрольные суммы S3 до и после воздействия;
- события Docker `start`, `die`, `restart`, `oom` и другие события жизненного цикла.
Каждая проверка вариантов записывается в отдельный каталог `objects/verify-...`.
Снимки до и после воздействия сохраняются раздельно. В журналы не включаются
сессионные токены, пароли, переменные окружения контейнеров и аргументы `docker exec`.
Источники проверки — API, PostgreSQL и S3. Интервал опроса — 0.2 секунды;
разрывы более 2 секунд отмечаются как `observation gap`.
## Обработка ошибок и сводка
Случай с ошибкой сохраняется. Продолжение серии допускается после снятия пауз,
восстановления процессов и проверки пустой очереди и отсутствия незавершённых
заданий. Если восстановить это состояние не удалось, серия останавливается.
Повреждение артефактов или потеря потока событий также делают серию неполной.
Для каждой пары «сценарий × профиль» рассчитываются число выполненных, нарушенных
и невалидных случаев, количество попыток и публикаций, версии и исходы заданий.
Времена выполнения представлены минимумом, медианой и максимумом по повторам.
В сводку включаются все случаи, ошибки и пропуски данных. Правила классификации
результата приведены в [HYPOTHESIS.md](HYPOTHESIS.md).