ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 3c38465d89 feat(generator): добавлен артефакт стартовой истории

- Зачем:
  - чистый стенд должен восстанавливать стартовую историю без повторной генерации.
- Что:
  - добавлены 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.

2026-07-04 18:23:54 +03:00

4.2 KiB

Raw Blame History

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

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

За устройством генератора см. generator/README.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-часовой артефакт:

make startup-history-export

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

Суточная история:

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.

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

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 с теми же настройками, что были в артефакте:

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.

4.2 KiB Raw Blame History Unescape Escape