ddadmin
9b0b063fed
- Зачем: - коммит-гейт не запускал корневые контрактные тесты, а часть подтверждённых обходов могла снова смешать разные миры генератора. - Что: - добавлены цели make test, make lint и contract-test с тихим pytest-выводом через Docker. - закрыты обходы через generator-reset, неизвестную версию state и fail-open проверку DM-витрин. - усилены поведенческие контракты CHECK_LIVE_SEAM, профиля manifest и pause-check etl_pipeline; обновлены документы и issue 19. - Проверка: - make test; make lint; git diff --check.
304 lines
14 KiB
Markdown
304 lines
14 KiB
Markdown
# Дашборд Superset для E-commerce Analytics
|
||
|
||
Документация по настройке и использованию Superset дашборда для анализа кликстрима.
|
||
|
||
---
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Запуск инфраструктуры
|
||
|
||
```bash
|
||
# Чистый прогон: стартовая история генератора -> DM -> Superset
|
||
make generated-history-analytics
|
||
```
|
||
|
||
Команда очищает volumes, генерирует стартовую историю, прогоняет batch
|
||
STG -> ODS -> DDS -> DM и создаёт metadata Superset. Если данные уже
|
||
подготовлены и нужно только пересобрать Superset:
|
||
|
||
```bash
|
||
# Автоматическая инициализация (создание подключения и датасетов)
|
||
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
|
||
|
||
```bash
|
||
# Основные
|
||
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**
|
||
|
||
### Импорт датасетов
|
||
|
||
```bash
|
||
# Внутри контейнера
|
||
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`).
|
||
|
||
```bash
|
||
# Импорт через 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`
|
||
|
||
Пример нового чарта:
|
||
```python
|
||
{
|
||
"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 не стартует
|
||
|
||
```bash
|
||
# Проверить логи
|
||
make logs service=superset
|
||
|
||
# Перезапуск
|
||
make superset-restart
|
||
|
||
# Полная переинициализация
|
||
docker compose down -v
|
||
make generated-history-analytics
|
||
```
|
||
|
||
### Нет данных в чартах
|
||
|
||
```bash
|
||
# Проверить данные в ClickHouse
|
||
docker compose exec clickhouse clickhouse-client -q "SELECT count() FROM dm.v_events_enriched"
|
||
|
||
# Перезапустить ETL
|
||
make transform
|
||
```
|
||
|
||
### Ошибка подключения к ClickHouse
|
||
|
||
```bash
|
||
# Проверить доступность 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](https://superset.apache.org/docs/intro)
|
||
- [ClickHouse SQL Reference](https://clickhouse.com/docs/en/sql-reference)
|
||
- [ARCHITECTURE.md](./ARCHITECTURE.md) — архитектура хранилища
|