feat(generator): добавлены профили запуска

- Зачем:
  - запуск генератора должен быть понятным перед будущим DAG-пультом.
- Что:
  - добавлены глаголы запуска backfill, continue и reset.
  - добавлены профили ci и daily-wave с расчётом длительности истории.
  - обновлены runbook и документы запуска под профильный интерфейс.
- Проверка:
  - uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
  - bash -n scripts/run_generator.sh scripts/export_startup_history_artifact.sh scripts/import_startup_history_artifact.sh scripts/run_generated_history_analytics.sh.
  - PROFILE=daily-wave COMPOSE_BIN=true bash scripts/run_generator.sh backfill.
This commit is contained in:
2026-07-04 18:51:10 +03:00
parent d2899e9ee3
commit 4f8f992363
19 changed files with 547 additions and 101 deletions
+29 -13
View File
@@ -16,12 +16,24 @@
## Что требует нового артефакта
- Другая длительность истории (`GEN_MODEL_T_END`).
- Другая длительность истории или другой профиль запуска.
- Другой `GEN_SEED`, `GEN_MODEL_T0`, часовой пояс, скорость или настройки
генерации.
- Осознанный новый мир после несовместимого state: сначала сбросьте state через
`GEN_STATE_RESET=true` или чистые volumes.
## Профили запуска
Основной способ — глагол плюс профиль:
| Профиль | Для чего | Длительность |
|---------|----------|--------------|
| `ci` | Быстрая проверка и CI | `6h` |
| `daily-wave` | История с видимой суточной волной | `2d` |
Длительность можно переопределить через `GEN_HISTORY_DURATION`, например `2d`.
Команда сама считает `GEN_MODEL_T_END` от `GEN_MODEL_T0`.
## Экспорт
По умолчанию создаётся быстрый 6-часовой артефакт:
@@ -32,11 +44,11 @@ make startup-history-export
Файл по умолчанию: `/tmp/clickstream-startup-history.json`.
Суточная история:
История на 2 суток с суточной волной:
```bash
ARTIFACT=/tmp/clickstream-startup-history-1d.json \
GEN_MODEL_T_END=2026-01-02T00:00:00+00:00 \
ARTIFACT=/tmp/clickstream-startup-history-2d.json \
PROFILE=daily-wave \
make startup-history-export
```
@@ -62,6 +74,13 @@ make generated-history-check
compact-топики в Kafka. ClickHouse читает данные через свои Kafka-таблицы и
Materialized View, затем batch строит ODS, DDS и DM.
Если артефакт создан не профилем `ci`, импорт запускайте с тем же профилем:
```bash
PROFILE=daily-wave ARTIFACT=/tmp/clickstream-startup-history-2d.json \
make startup-history-import
```
`make startup-history-check` сверяет контрольные числа DM-витрины с manifest
артефакта: события, визиты, пользователей и диапазон `event_timestamp`. Если
data-топики Kafka уже непустые, импорт остановится до публикации событий.
@@ -74,18 +93,15 @@ ClickHouse уже успел прочитать частичные сообще
## Live-продолжение
После импорта запускайте 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
PROFILE=ci make generator-continue
```
Если читаемый state есть, но настройки не совпадают, генератор падает с перечнем
полей. Это защита от смешения разных миров. Для намеренного нового мира
используйте `GEN_STATE_RESET=true` или `make clean`.
используйте `make generator-reset` или `make clean`.
Старые переменные `GEN_RUN_MODE`, `GEN_STATE_RESET` и `GEN_MODEL_T_END` остаются
низкоуровневым способом для отладки и прямого `docker compose run`.