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.
2026-07-04 18:51:10 +03:00
parent d2899e9ee3
commit 4f8f992363
19 changed files with 547 additions and 101 deletions
@@ -118,6 +118,7 @@ make generator-logs
 | `GEN_MODEL_TIMEZONE` | Часовой пояс модельных часов для дневного коэффициента | `UTC` |
 | `GEN_MODEL_TIME_SPEED` | Сколько модельных секунд проходит за одну настенную секунду | `1` |
 | `GEN_RUN_MODE` | Режим генератора | `live` |
+| `GEN_LAUNCH_PROFILE` | Имя профиля запуска для логов | `ci` |
 | `GEN_STARTUP_HISTORY_ARTIFACT` | JSON-файл для экспорта стартовой истории в режиме `backfill` | пусто |
 | `GEN_STATE_ENABLED` | Сохранять state v2 между рестартами | `true` |
 | `GEN_STATE_RESET` | Сбросить state при старте | `false` |
@@ -141,20 +142,25 @@ make generated-history-analytics
 ```

 Она выполняет полный сброс volumes, поднимает ClickHouse и Kafka, применяет DDL,
-запускает `GEN_RUN_MODE=backfill`, прогоняет batch STG -> ODS -> DDS -> DM,
-инициализирует Superset и запускает техническую проверку. Для координатора или CI
-короткая повторная проверка после уже готового стенда:
+выполняет глагол `backfill`, прогоняет batch STG -> ODS -> DDS -> DM,
+инициализирует Superset и запускает техническую проверку. Для координатора или
+CI короткая повторная проверка после уже готового стенда:

 ```bash
 make generated-history-check
 ```

-По умолчанию команда использует быстрый проверочный профиль: 6 часов модельного
-времени (`GEN_MODEL_T_END=2026-01-01T06:00:00+00:00`). Суточную историю можно
-прогнать отдельно, явно задав правую границу:
+По умолчанию команда использует быстрый профиль `ci`: 6 часов модельного
+времени. Историю на 2 суток с суточной волной можно получить одной командой:

 ```bash
-GEN_MODEL_T_END=2026-01-02T00:00:00+00:00 make generated-history-analytics
+PROFILE=daily-wave make generated-history-analytics
+```
+
+Разовую длительность можно задать без ручного расчёта `GEN_MODEL_T_END`:
+
+```bash
+GEN_HISTORY_DURATION=2d make generated-history-analytics
 ```

 `GEN_RUN_MODE=backfill` быстро проматывает модельное прошлое от `GEN_MODEL_T0`
@@ -171,30 +177,16 @@ GEN_MODEL_T_END=2026-01-02T00:00:00+00:00 make generated-history-analytics
 Kafka-топики данных, state и manifest генератора. `make generated-history-analytics`
 делает это по умолчанию (`CLEAN_START=1`).

+Ручной backfill без всего аналитического контура:
+
 ```bash
-make clean
-docker compose up -d clickhouse kafka
-make ddl
-
-GEN_RUN_MODE=backfill \
-GEN_STATE_RESET=true \
-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 \
-GEN_TICK_SECONDS=60 \
-GEN_LAMBDA_BASE_PER_MIN=60 \
-GEN_JITTER_PCT=0 \
-docker compose run --rm --no-deps generator
-
-# Materialized View слоя STG читает Kafka сама; даём ей коротко догнать.
-sleep 10
-bash scripts/run_batch.sh
+PROFILE=daily-wave make generator-backfill
 ```

-Ручной сценарий выше нужен для отладки. В обычной проверке используйте
-`make generated-history-analytics`, чтобы не забыть Superset и итоговый check.
+Старый способ через `GEN_RUN_MODE`, `GEN_STATE_RESET` и `GEN_MODEL_T_END`
+остаётся низкоуровневым путём для отладки прямого `docker compose run`. В обычной
+проверке используйте `make generated-history-analytics`, чтобы не забыть
+Superset и итоговый check.

 Manifest можно посмотреть так:

@@ -207,27 +199,14 @@ docker compose exec -T kafka /opt/kafka/bin/kafka-console-consumer.sh \
  --timeout-ms 5000
 ```

-Live-продолжение стартует с этого state. Используйте те же `GEN_SEED`, `T0`,
-`T_end`, часовой пояс и настройки генерации. `GEN_STATE_RESET=false` важен: иначе
-слепок стартовой истории будет проигнорирован.
+Live-продолжение стартует с этого state. Используйте тот же профиль или ту же
+длительность, что были у backfill. Команда сама выставит `GEN_STATE_RESET=false`.

 ```bash
-docker compose run -d --name startup-history-live --no-deps \
-  -e GEN_RUN_MODE=live \
-  -e GEN_STATE_RESET=false \
-  -e GEN_SEED=4242 \
-  -e GEN_MODEL_T0=2026-01-01T00:00:00+00:00 \
-  -e GEN_MODEL_T_END=2026-01-01T06:00:00+00:00 \
-  -e GEN_MODEL_TIMEZONE=UTC \
-  -e GEN_MODEL_TIME_SPEED=1 \
-  -e GEN_TICK_SECONDS=60 \
-  -e GEN_LAMBDA_BASE_PER_MIN=60 \
-  -e GEN_JITTER_PCT=0 \
-  generator
+PROFILE=daily-wave make generator-continue

 sleep 130
-docker stop startup-history-live
-docker rm startup-history-live
+make generator-down
 sleep 10
 bash scripts/run_batch.sh
 ```
@@ -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`.
@@ -90,12 +90,25 @@ ADR-0005 решил отвязать время генератора от реа
  одну настенную секунду. Формат: положительное число, по умолчанию `1`.
 - `GEN_RUN_MODE` — режим запуска: `live` или `backfill`. Значение по умолчанию —
  `live`.
+- `GEN_LAUNCH_PROFILE` — имя профиля запуска для логов. Значение по умолчанию —
+  `ci`; на поток не влияет.
 - `GEN_STARTUP_HISTORY_ARTIFACT` — путь к JSON-файлу, куда `backfill` дополнительно
  пишет портативный артефакт стартовой истории. В обычном live-запуске не нужен.
 - `GEN_SEED`, `GEN_TICK_SECONDS` и остальные настройки генерации остаются частью
  контракта повторяемости. Если они отличаются, артефакт стартовой истории
  считается другим.

+Поверх этих переменных есть пользовательский слой запуска:
+
+- `backfill` — подставляет `GEN_RUN_MODE=backfill` и `GEN_STATE_RESET=true`;
+- `continue` — подставляет `GEN_RUN_MODE=live` и `GEN_STATE_RESET=false`;
+- `reset` — подставляет `GEN_RUN_MODE=live` и `GEN_STATE_RESET=true`.
+
+Профиль `ci` даёт быстрый 6-часовой прогон. Профиль `daily-wave` даёт 2 суток,
+чтобы была видна суточная волна. `GEN_HISTORY_DURATION` задаёт длительность
+вида `6h` или `2d`; `GEN_MODEL_T_END` считается от `GEN_MODEL_T0` внутри слоя
+запуска. Старые переменные остаются низкоуровневым механизмом.
+
 #### Ход часов

 В живом режиме модельное время идёт фиксированным шагом. На чистом старте оно