ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadminandClaude Fable 5 ac7a973504 feat(airflow): пульт стал world_init, добавлен DAG world_next_day (#4 )

- Зачем:
  - список DAG'ов должен читаться лесенкой ddl_init → world_init →
    world_next_day, а путь менти — проходиться пустыми формами
    (issue #4, спека редизайна пути менти, решения 2–3).
- Что:
  - generator_control переименован в world_init, дефолт операции —
    import; next-day ушёл из выпадашки в отдельный DAG;
  - новый беспараметрный world_next_day: расписание */30 * * * *,
    создаётся на паузе, catchup=False, max_active_runs=1; общие
    задачи вынесены в airflow/dags/utils/startup_history_tasks.py;
  - доки и контрактные тесты обновлены синхронно; быстрый старт
    README — без make ddl, схему создаёт DAG ddl_init.
- Проверка:
  - make test (210 + 31) и make lint зелёные;
  - живая приёмка на чистом стенде: world_init пустой формой
    импортировал эталонный мир за 217 с (3 дня, 280 437 событий),
    world_next_day после снятия с паузы добавляет ровно один день
    за прогон, дашборд Superset собирается.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-22 21:45:02 +03:00

7.0 KiB

Raw Permalink Blame History

Repo Map

Карта ключевых артефактов репозитория.

Исполняемые файлы

Airflow (ручной и учебный путь запуска)

airflow/dags/ddl_init_dag.py — инициализация схемы ClickHouse
airflow/dags/world_init_dag.py — импорт или служебная сборка стартового мира и проверка витрин
airflow/dags/world_next_day_dag.py — беспараметрное добавление одного модельного дня
airflow/dags/utils/startup_history_tasks.py — общие задачи DAG для роста и проверки мира
airflow/dags/kafka_load_dag.py — архивная загрузка в Kafka из JSONL; не основной источник аналитики
airflow/dags/etl_pipeline_dag.py — ETL процесс STG -> ODS -> DDS -> DM
airflow/dags/utils/kafka_helpers.py — helper-функции для Kafka
airflow/dags/utils/sql_helpers.py — чтение и подготовка SQL-файлов для DAG
airflow/dags/utils/airflow_params.py — разбор и валидация параметров DAG
airflow/requirements.txt — зависимости Airflow/ClickHouse plugin

Generator

generator/src/clickstream_generator/ — исходники генератора кликстрима (модельное время, состояние мира, запись в Kafka)
generator/tests/ — тесты генератора
generator/Dockerfile — образ generator-service

SQL

DDL (форма таблиц):

sql/ddl/00_databases.sql — создание БД stg/ods/dds/dm
sql/ddl/stg/10_stg.sql — STG (Kafka Engine + MV)
sql/ddl/ods/20_ods.sql — ODS: типизированные таблицы и *_errors (наполняются batch, не MV)
sql/ddl/dds/30_dds.sql — DDS (таблицы для batch-загрузки)
sql/ddl/dm/40_dm.sql — DM (витрины VIEW)

Трансформации (наполнение, шаги etl_pipeline):

sql/ods/20_stg_to_ods.sql — STG -> ODS: типизация + DQ-split (валидный ключ → ods.*, любая ошибка → ods.*_errors)
sql/dds/30_ods_to_dds.sql — ODS -> DDS (argMax + LEFT JOIN)
sql/dm/40_dds_to_dm.sql — DDS -> DM: пересборка dm.dq_summary (TRUNCATE+INSERT) по всем слоям; сами витрины dm.v_* — это VIEW из DDL

Superset

superset/init_superset.py — подключение к ClickHouse + создание датасетов
superset/create_dashboard.py — сборка дашборда с чартами

Скрипты

Shell-скрипты scripts/* и Makefile-обёртки дают повторяемый локальный запуск. Основной чистый путь аналитики — make generated-history-analytics.

scripts/apply_clickhouse_ddl.sh — применение DDL
scripts/load_kafka_data.sh — архивная загрузка data/*.jsonl в Kafka
scripts/run_batch.sh — batch-процесс
scripts/run_generated_history_analytics.sh — чистый прогон стартовой истории до DM и Superset
scripts/check_generated_analytics.sh — проверка DM-витрин и Superset metadata на данных генерации
scripts/run_generator.sh — запуск генератора через понятные глаголы (backfill/continue/reset) поверх старых env-переменных
scripts/assert_stand_clean.sh — проверка, что новый мир генератора не смешается со старым
scripts/export_startup_history_artifact.sh — экспорт стартовой истории в портативный JSON-артефакт
scripts/import_startup_history_artifact.sh — импорт портативного артефакта стартовой истории в Kafka
scripts/check_startup_history_manifest.sh — сверка DM-витрины ClickHouse с manifest портативной стартовой истории
scripts/check_generated_history_chain.sh — проверка завершённых стыков между порциями модельной истории
scripts/run_generated_history_runtime_check.sh — runtime-проверка, что daily-wave доходит до manifest/check, а live-продолжение пишет стык backfill/live

Данные и конфиги

data/*.jsonl — архивная фактура для генератора; не основной источник аналитики
configs/ — конфиги ClickHouse, Prometheus, Grafana
configs/prometheus.yml — конфигурация Prometheus (scrape targets для ClickHouse, Kafka, Airflow)
configs/statsd_mapping.yml — маппинг StatsD → Prometheus метрик для Airflow
configs/default_user.xml — пользователь ClickHouse (default/123456)
configs/prometheus_ch.xml — встроенный Prometheus endpoint ClickHouse
configs/grafana/provisioning/alerting/clickhouse-alert-rules.yml — правила алертинга Grafana для ClickHouse
configs/grafana/provisioning/alerting/kafka-alert-rules.yml — правила алертинга Grafana для Kafka
configs/grafana/provisioning/alerting/airflow-alert-rules.yml — правила алертинга Grafana для Airflow
configs/grafana/provisioning/dashboards/clickhouse-overview.json — дашборд ClickHouse
configs/grafana/provisioning/dashboards/kafka-overview.json — дашборд Kafka
configs/grafana/provisioning/dashboards/airflow-overview.json — дашборд Airflow

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

README.md — быстрый старт и обзор проекта
docs/ARCHITECTURE.md — техническая архитектура
docs/OPERATIONS.md — запуск, проверки, troubleshooting
docs/SUPERSET_DASHBOARD.md — настройка и использование дашборда Superset
docs/DE-task.md — исходное задание
docs/COMMIT_RULES.md — правила коммитов
docs/course/ — продвинутый учебный курс на базе стенда (PRD, план, уроки)
docs/adr/ — архитектурные решения (ADR)
docs/agents/ — контракты для агентских скиллов (issue-tracker, triage, domain)

Legacy-планы

plans/clickhouse_ddl.md — исходный план (inline DDL)
plans/runbook.md — ранний runbook
plans/kafka_ingest_plan.md — ранний план Kafka ingest
plans/monitoring_airflow_plan.md — план подключения Airflow мониторинга
plans/monitoring_kafka_plan.md — план подключения Kafka мониторинга

7.0 KiB Raw Permalink Blame History Unescape Escape