clickstream-ch-kafka-superset-demo/docs/SUPERSET_DASHBOARD.md

Дашборд Superset для E-commerce Analytics

Документация по настройке и использованию Superset дашборда для анализа кликстрима.

---

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

1. Запуск инфраструктуры

# Чистый прогон: стартовая история генератора -> DM -> Superset
make generated-history-analytics

Команда очищает volumes, генерирует стартовую историю, прогоняет batch STG -> ODS -> DDS -> DM и создаёт metadata Superset. Если данные уже подготовлены и нужно только пересобрать Superset:

# Автоматическая инициализация (создание подключения и датасетов)
make superset-init

# Создание дашборда с чартами; при необходимости обновляет metadata колонок датасетов
make superset-dashboard

Повторный make superset-dashboard синхронизирует чарты этого учебного дашборда с CHARTS_CONFIG: обновляет параметры, переименовывает старые имена и может удалить лишний чарт-дубль. Удаление ограничено dashboard ecommerce-analytics, поэтому одноимённые чарты менти в других dashboard не трогаются.

2. Доступ к UI

Откройте в браузере: http://localhost:8088

Логин: admin
Пароль: admin

---

Структура дашборда

Витрины данных (Datasets)

Витрина	Таблица ClickHouse	Описание
Events Enriched	dm.v_events_enriched	Полная обогащённая витрина событий
Daily Traffic	dm.v_daily_traffic	Агрегаты по дням
UTM Effectiveness	dm.v_utm_effectiveness	Эффективность маркетинговых каналов
Top Pages	dm.v_top_pages_daily	Популярность страниц
Session Overview	dm.v_session_overview	Анализ сессий
DQ Summary	dm.dq_summary	Метрики по слоям (строки, ошибки, сироты)

Чарты (Charts)

KPI-блок (верх дашборда)

• 📊 Total Events — общее количество событий
• 👤 Unique Users — уникальные пользователи
• 📈 Avg Events/Visit — среднее количество событий на визит (click_id)
• 🎯 Conversion to /confirmation — доля просмотров /confirmation от просмотров /home

KPI разложены в одну строку по 12-колоночной сетке Superset: четыре блока по 3 колонки. Unique Sessions не вынесен отдельной KPI-плиткой: в текущем дашборде важнее развести события, пользователей и среднюю глубину визита. Генератор создаёт повторные визиты, поэтому user_domain_id и click_id уже не идут 1:1.

Динамика трафика

• 📅 Events over Time — линейный график событий с 5-минутными бакетами (быстрый проверочный профиль покрывает 6 часов модельного времени, поэтому 5-минутные бакеты дают видимую динамику без лишнего шума)
• 📱 Traffic by Device — pie chart распределения по устройствам

География

• 🌍 Top Countries by Events — top-15 стран по количеству событий (COUNT(*), единицы — события, штуки). Столбцы заменили прежнюю геовизуализацию: на текущем разреженном распределении так видны страна, значение, порядок и tooltip. Перекос стран приходит из гео-фактуры статического сида geo_by_click_id; своя генерация гео описана как отдельный будущий шаг в ADR-0006 и не лечится настройкой чарта.

Что проверили по Superset. Через MCP Context7 проверили /apache/superset: прежний геоплагин описан как legacy-плагин, а ECharts bar chart имеет штатные параметры show_legend, rich_tooltip, подписи осей и формат чисел. Поэтому для разреженной географии выбран top-N bar chart (viz_type: echarts_timeseries_bar), а не донастройка прежней геовизуализации.

Маркетинг

• 🔗 UTM Effectiveness Table — таблица эффективности UTM-меток
• 🪜 Page Funnel — funnel chart по просмотрам страниц, от /home к /confirmation

Что проверили по Superset 4.1.2. Через MCP Context7 проверили официальную библиотеку /apache/superset; документация не дала точной строки viz_type. В установленном Superset 4.1.2 дополнительно проверили bundled example Featured Charts/Funnel.yaml и frontend assets: для воронки используется viz_type: funnel, поэтому dashboard создаёт именно funnel chart.

Прохождение строк по слоям

• 🧱 Rows by Layer (event) — dist_bar по dm.dq_summary: сколько строк одного event-зерна в каждом слое конвейера STG → ODS → DDS → DM.

Почему именно одно зерно, а не сумма по слою. Чарт берёт по одной канонической таблице на слой (browser_raw → browser_event → event → v_events_enriched). Если суммировать total_rows по всем таблицам слоя, в один столбец складываются таблицы разного зерна: события, визиты и error-таблицы. Получается ложная «воронка потерь», которой нет. На одном зерне видно прохождение event-строк по слоям, а не сумму несравнимых таблиц.

Настоящие сигналы качества (rows_with_errors в ODS, orphan_events в DDS) на чистых демо-данных равны нулю и живут в dm.dq_summary отдельными check_name — их разбирают уроки 3–4, а не этот чарт.

Порядок столбцов. В groupby подпись слоя получает числовой префикс (1 · stg, 2 · ods, …), а order_bars сортирует бары по подписи — иначе dist_bar ставит их по убыванию значения, а не по порядку конвейера.

Фильтры (Native Filters)

Фильтр	Поле	Тип	Применение
📅 Date Range	event_date	Time Range	Charts с event_date; по умолчанию No filter, чтобы стартовая история не скрывалась фильтром даты
🌍 Country	geo_country	Multi-select	Charts на dm.v_events_enriched
📱 Device Type	device_type	Multi-select	Charts на dm.v_events_enriched
🌐 Browser	browser_name	Multi-select	Charts на dm.v_events_enriched

Фильтры работают через левую панель Superset. Click-to-filter между виджетами не включен: клик по сектору pie chart, столбцу Top Countries, строке таблицы или funnel не меняет остальные charts.

Фильтр применяется только к charts, где есть нужное поле. Агрегированные витрины dm.v_utm_effectiveness и dm.v_top_pages_daily содержат event_date, но не содержат geo_country, device_type и browser_name. dm.dq_summary использует check_date; бизнес-фильтры на него не рассчитаны.

---

Команды Makefile

# Основные
make up          # Запуск всех сервисов
make down        # Остановка сервисов
make clean      # Остановка с удалением volumes
make logs service=superset  # Логи сервиса

# ETL
make generated-history-analytics # Чистый прогон генерации до Superset
CHECK_LIVE_SEAM=0 make generated-history-check # Проверка DM и Superset после backfill
make ddl         # Применение DDL в ClickHouse
make data        # Архивная загрузка data/*.jsonl в Kafka
make transform   # Запуск batch-процесса

# Superset
make superset-init      # Инициализация (подключение + датасеты)
make superset-dashboard # Создание дашборда
make superset-ui        # Показать URL и логин
make superset-restart   # Перезапуск сервиса

---

Ручная настройка (если автоматика не сработала)

Создание подключения к ClickHouse

1. Откройте Settings → Database Connections
2. Нажмите + Database
3. Выберите ClickHouse
4. Введите SQLAlchemy URI:

   clickhousedb://default:123456@clickhouse:8123/default
   

5. Установите:
   • Expose in SQL Lab: ✅
   • Allow DDL: ❌
6. Нажмите Connect

Импорт датасетов

# Внутри контейнера
docker compose exec superset bash
python /app/superset_init/init_superset.py

Создание чартов вручную

1. Перейдите в Charts → + Chart
2. Выберите датасет (например, dm.v_events_enriched)
3. Настройте визуализацию:
   • Viz Type: Big Number / Line Chart / Pie Chart / ECharts Bar / Table
   • Metrics: COUNT(*), COUNT(DISTINCT ...)
   • Dimensions: группировки
   • Filters: фильтры
4. Нажмите Create Chart

Создание дашборда

1. Dashboards → + Dashboard
2. Назовите: "E-commerce Analytics Dashboard"
3. Добавьте чарты из списка
4. Настройте layout (drag-and-drop)
5. Добавьте Native Filters (фильтры вверху)
6. Сохраните

---

Импорт дашборда

Основной способ собрать дашборд — make superset-dashboard (скрипт create_dashboard.py). Готовый экспорт дашборда лежит в репозитории на случай ручного импорта: superset/dashboards/ecommerce_analytics.zip.json (внутри контейнера — /app/superset_init/dashboards/ecommerce_analytics.zip.json).

# Импорт через CLI
docker compose exec superset superset import-dashboards -p /app/superset_init/dashboards/ecommerce_analytics.zip.json

# Или через UI: Settings → Import Dashboards

---

Расширение дашборда

Добавление нового чарта

1. Отредактируйте superset/create_dashboard.py
2. Добавьте конфигурацию в CHARTS_CONFIG
3. Запустите: make superset-dashboard

Пример нового чарта:

{
    "slice_name": "📊 My New Chart",
    "viz_type": "echarts_bar",
    "dataset_name": "v_events_enriched",
    "params": {
        "x_axis": "event_type",
        "metrics": [{"sqlExpression": "COUNT(*)", "label": "Count"}],
        "time_range": "No filter"
    }
}

---

Troubleshooting

Superset не стартует

# Проверить логи
make logs service=superset

# Перезапуск
make superset-restart

# Полная переинициализация
docker compose down -v
make generated-history-analytics

Нет данных в чартах

# Проверить данные в ClickHouse
docker compose exec clickhouse clickhouse-client -q "SELECT count() FROM dm.v_events_enriched"

# Перезапустить ETL
make transform

Ошибка подключения к ClickHouse

# Проверить доступность ClickHouse
docker compose exec superset bash -c "ping clickhouse"

# Проверить порт
docker compose exec superset bash -c "curl clickhouse:8123"

---

Порты сервисов

Сервис	URL	Логин/Пароль
Superset	http://localhost:8088	admin / admin
ClickHouse HTTP	http://localhost:9123	default / 123456
Airflow	http://localhost:8080	admin / admin
Grafana	http://localhost:3000	admin / admin
Prometheus	http://localhost:9090	-
Kafka UI	http://localhost:8082	-

---

Дополнительные ресурсы

• Superset Documentation
• ClickHouse SQL Reference
• ARCHITECTURE.md — архитектура хранилища