clickstream-ch-kafka-superset-demo/README.md

Учебный стенд DWH кликстрима

Живой стек для работы с кликстримом: Kafka, ClickHouse, Airflow, Superset и мониторинг (Prometheus с Grafana) поднимаются в Docker одной командой. На этом стенде можно учиться по курсу или просто поднять его у себя и поэкспериментировать с потоковой загрузкой и витринами.

Поток данных коротко:

• стартовая история: generator backfill → Kafka → ClickHouse (STG) → batch STG → ODS → DDS → DM → Superset.
• живое продолжение: generator live → Kafka → ClickHouse (STG) → batch ETL → Superset.

Файлы data/*.jsonl больше не основной источник аналитики. Пока они остаются архивной кладовкой значений для генератора: браузеры, страны, устройства и UTM.

Куда дальше

• Хочешь учиться — открой курс «Кликстрим на ClickHouse». Это продвинутый курс «со звёздочкой»: основные приёмы инженерии данных проходишь прямо на этом стенде.
• Хочешь поднять и попробовать — следуй быстрому старту ниже.
• Хочешь разобраться в устройстве — смотри архитектуру слоёв, запуск и эксплуатацию и карту репозитория.

Быстрый старт

Перед первой командой нужны Docker с docker compose, make, bash, curl, git и uv. uv нужен для локальных Python-проверок и команд разработки.

Для ручной работы поднимите стенд и создайте стартовую историю через Airflow:

make up
make ddl
docker compose ps

Откройте Airflow: http://localhost:8080 (admin/admin). Запустите generator_control с операцией backfill: DAG создаст стартовую историю, запустит ETL и выполнит check. make up не запускает live-генератор; live включается отдельно командой make generator-continue.

После обновления репозитория снова выполните make up: команда пересобирает Airflow-образ и подтягивает новые зависимости и DAG-и. Superset-дэшборд собирается позже, когда DM уже готов: через make generated-history-analytics или make superset-init.

Для полностью автоматического чистого прогона из консоли остаётся команда:

make generated-history-analytics

По умолчанию это быстрый профиль ci: 6 часов модельного времени. Историю на 2 суток с суточной волной можно прогнать одной командой. В live-продолжении daily-wave идёт с ×60: модельные сутки проходят примерно за 24 настенные минуты.

PROFILE=daily-wave make generated-history-analytics

Разовую длительность можно задать без ручного расчёта правой границы:

GEN_HISTORY_DURATION=2d make generated-history-analytics

Повторить техническую проверку после такого прогона только стартовой истории:

CHECK_LIVE_SEAM=0 make generated-history-check

Стык backfill/live проверяйте отдельным коротким сценарием:

make generated-history-runtime-check

Сохранить стартовую историю в файл и восстановить её без новой генерации можно по runbook стартовой истории.

Проверить, что данные дошли до витрин:

docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 \
  --query "SELECT count() FROM dm.v_events_enriched"

Подробный сценарий запуска, параметры DAG-ов и разбор частых проблем — в OPERATIONS.

Сервисы и доступы

Сервис	Адрес	Назначение	Логин/пароль
Airflow	http://localhost:8080	оркестрация ETL	admin/admin
ClickHouse	http://localhost:9123/play	SQL-запросы	default/123456
Kafka UI	http://localhost:8082	просмотр топиков	—
Superset	http://localhost:8088	дашборды	admin/admin
Prometheus	http://localhost:9090	метрики	—
Grafana	http://localhost:3000	графики метрик	admin/admin

Готовый дашборд в Superset: http://localhost:8088/superset/dashboard/ecommerce-analytics/ — он создаётся во время make generated-history-analytics. Состав и настройка дашборда описаны в SUPERSET_DASHBOARD.

Как устроен поток данных

flowchart LR
    subgraph GEN["Generator"]
        BF["backfill"]
        LIVE["live"]
    end

    subgraph Kafka["Kafka"]
        Topics[4 топика]
    end

    subgraph CH["ClickHouse"]
        STG["STG: сырые данные"]
        ODS["ODS: типизация + DQ"]
        DDS["DDS: сущности"]
        DM["DM: витрины VIEW"]
    end

    BF -->|стартовая история| Kafka
    LIVE -->|продолжение| Kafka
    Kafka -->|Kafka MV| STG
    STG -->|batch| ODS -->|batch| DDS -->|VIEW| DM

    DDL["DDL"] -.-> CH

«Грязные» записи не роняют пайплайн: ошибки разбора складываются в ods.*_errors и в поле parse_errors, а обработка продолжается.

Подробное описание слоёв STG/ODS/DDS/DM, диаграммы и обоснование решений — в ARCHITECTURE.

Документация

• Архитектура и слои — устройство STG/ODS/DDS/DM, диаграммы, обоснование решений.
• Запуск и эксплуатация — сценарий запуска, параметры DAG-ов, мониторинг, частые проблемы.
• Runbook стартовой истории — экспорт, импорт и live-продолжение из готового артефакта.
• Карта репозитория — где какие файлы и что менять.
• Курс «Кликстрим на ClickHouse» — учебная программа на этом стенде.
• DE-task.md — задание, из которого вырос стенд.