ddadmin
3c38465d89
- Зачем: - чистый стенд должен восстанавливать стартовую историю без повторной генерации. - Что: - добавлены export/import артефакта через Kafka и compact-топики. - добавлена manifest-aware сверка ClickHouse и защита от смешения state. - добавлен runbook использования стартовой истории. - Проверка: - uv run --with-requirements generator/requirements.txt pytest generator/tests -q. - bash -n scripts/check_startup_history_manifest.sh scripts/export_startup_history_artifact.sh scripts/import_startup_history_artifact.sh. - git diff --check.
92 lines
4.2 KiB
Markdown
92 lines
4.2 KiB
Markdown
# Runbook: стартовая история стенда
|
||
|
||
Этот runbook нужен, чтобы один раз создать стартовую историю генератора, сохранить
|
||
её в файл и быстро восстановить на чистом стенде.
|
||
|
||
За устройством генератора см. [`generator/README.md`](../../generator/README.md)
|
||
и [спеку модельного времени](../specs/2026-06-14-generator-model-time-and-startup-history.md).
|
||
|
||
## Что дёшево
|
||
|
||
- Перезапуск без очистки volumes: Kafka хранит `generator_state` и manifest.
|
||
- Live-продолжение после импорта: генератор стартует с `T_end`, если настройки
|
||
совпадают.
|
||
- Восстановление чистого стенда из готового файла: события повторно пишутся в
|
||
Kafka, ClickHouse наполняется штатным путём.
|
||
|
||
## Что требует нового артефакта
|
||
|
||
- Другая длительность истории (`GEN_MODEL_T_END`).
|
||
- Другой `GEN_SEED`, `GEN_MODEL_T0`, часовой пояс, скорость или настройки
|
||
генерации.
|
||
- Осознанный новый мир после несовместимого state: сначала сбросьте state через
|
||
`GEN_STATE_RESET=true` или чистые volumes.
|
||
|
||
## Экспорт
|
||
|
||
По умолчанию создаётся быстрый 6-часовой артефакт:
|
||
|
||
```bash
|
||
make startup-history-export
|
||
```
|
||
|
||
Файл по умолчанию: `/tmp/clickstream-startup-history.json`.
|
||
|
||
Суточная история:
|
||
|
||
```bash
|
||
ARTIFACT=/tmp/clickstream-startup-history-1d.json \
|
||
GEN_MODEL_T_END=2026-01-02T00:00:00+00:00 \
|
||
make startup-history-export
|
||
```
|
||
|
||
Команда делает чистый backfill и пишет в файл один связный набор: события Kafka,
|
||
state и manifest.
|
||
|
||
## Импорт на чистый стенд
|
||
|
||
```bash
|
||
make clean
|
||
docker compose up -d clickhouse kafka
|
||
make ddl
|
||
|
||
ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-import
|
||
|
||
sleep 10
|
||
make transform
|
||
ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-check
|
||
make generated-history-check
|
||
```
|
||
|
||
Импорт не пишет напрямую в ClickHouse. Он воспроизводит события и служебные
|
||
compact-топики в Kafka. ClickHouse читает данные через свои Kafka-таблицы и
|
||
Materialized View, затем batch строит ODS, DDS и DM.
|
||
|
||
`make startup-history-check` сверяет контрольные числа DM-витрины с manifest
|
||
артефакта: события, визиты, пользователей и диапазон `event_timestamp`. Если
|
||
data-топики Kafka уже непустые, импорт остановится до публикации событий.
|
||
|
||
В текущем стеке `kafka-python` не даёт транзакционный producer для нескольких
|
||
топиков. Поэтому импорт остаётся clean-stand операцией: при ошибке записи он
|
||
удаляет import-топики Kafka, чтобы повторный импорт не дописал дубли. Если
|
||
ClickHouse уже успел прочитать частичные сообщения, очистите стенд через
|
||
`make clean` и повторите импорт.
|
||
|
||
## Live-продолжение
|
||
|
||
После импорта запускайте live с теми же настройками, что были в артефакте:
|
||
|
||
```bash
|
||
GEN_STATE_RESET=false \
|
||
GEN_SEED=4242 \
|
||
GEN_MODEL_T0=2026-01-01T00:00:00+00:00 \
|
||
GEN_MODEL_T_END=2026-01-01T06:00:00+00:00 \
|
||
GEN_MODEL_TIMEZONE=UTC \
|
||
GEN_MODEL_TIME_SPEED=1 \
|
||
docker compose up -d generator
|
||
```
|
||
|
||
Если читаемый state есть, но настройки не совпадают, генератор падает с перечнем
|
||
полей. Это защита от смешения разных миров. Для намеренного нового мира
|
||
используйте `GEN_STATE_RESET=true` или `make clean`.
|