ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 4f8f992363 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

5.1 KiB

Raw Blame History

Runbook: стартовая история стенда

Этот runbook нужен, чтобы один раз создать стартовую историю генератора, сохранить её в файл и быстро восстановить на чистом стенде.

За устройством генератора см. generator/README.md и спеку модельного времени.

Что дёшево

Перезапуск без очистки volumes: Kafka хранит generator_state и manifest.
Live-продолжение после импорта: генератор стартует с T_end, если настройки совпадают.
Восстановление чистого стенда из готового файла: события повторно пишутся в Kafka, ClickHouse наполняется штатным путём.

Что требует нового артефакта

Другая длительность истории или другой профиль запуска.
Другой 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-часовой артефакт:

make startup-history-export

Файл по умолчанию: /tmp/clickstream-startup-history.json.

История на 2 суток с суточной волной:

ARTIFACT=/tmp/clickstream-startup-history-2d.json \
PROFILE=daily-wave \
make startup-history-export

Команда делает чистый backfill и пишет в файл один связный набор: события Kafka, state и manifest.

Импорт на чистый стенд

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.

Если артефакт создан не профилем ci, импорт запускайте с тем же профилем:

PROFILE=daily-wave ARTIFACT=/tmp/clickstream-startup-history-2d.json \
make startup-history-import

make startup-history-check сверяет контрольные числа DM-витрины с manifest артефакта: события, визиты, пользователей и диапазон event_timestamp. Если data-топики Kafka уже непустые, импорт остановится до публикации событий.

В текущем стеке kafka-python не даёт транзакционный producer для нескольких топиков. Поэтому импорт остаётся clean-stand операцией: при ошибке записи он удаляет import-топики Kafka, чтобы повторный импорт не дописал дубли. Если ClickHouse уже успел прочитать частичные сообщения, очистите стенд через make clean и повторите импорт.

Live-продолжение

После импорта запускайте live с тем же профилем, что был в артефакте:

PROFILE=ci make generator-continue

Если читаемый state есть, но настройки не совпадают, генератор падает с перечнем полей. Это защита от смешения разных миров. Для намеренного нового мира используйте make generator-reset или make clean.

Старые переменные GEN_RUN_MODE, GEN_STATE_RESET и GEN_MODEL_T_END остаются низкоуровневым способом для отладки и прямого docker compose run.

5.1 KiB Raw Blame History Unescape Escape