- Зачем:
- артефакты браузерной автоматизации не должны попадать в индекс.
- Что:
- добавлены .playwright-cli и .playwright-mcp в .gitignore.
- Проверка:
- git status не показывает .playwright-cli/ после прогона playwright-cli.
- Зачем:
- дашборд рендерился одной колонкой во всю ширину, а KPI показывали
значение последнего часового бакета (1/1/1) вместо итогов по срезу.
- Что:
- чарты разложены по строкам-контейнерам ROW (Superset layout v2):
KPI-полоса 4-в-ряд + аналитические блоки парами вместо плоского
списка CHART под GRID с игнорируемыми x/y.
- KPI переведены с big_number на big_number_total без granularity_sqla;
sync_query_context чистит granularity/time_grain для тотала.
- Проверка:
- make superset-dashboard; GET /api/v1/dashboard/1/datasets → 200;
position_json содержит 4 ROW; KPI показывают 50/26/26/1.92.
- Зачем:
- Superset dashboard открывался с ошибками datasources и неудобным layout, а курс не содержал готового урока по BI-витрине.
- Что:
- добавлен урок 6 про Superset поверх ClickHouse DM-витрин.
- исправлена раскладка dashboard и дефолтный фильтр даты для исторических демо-данных.
- добавлено восстановление metadata колонок датасетов при обновлении dashboard.
- Проверка:
- make superset-dashboard.
- /api/v1/dashboard/1/datasets и /superset/explore_json для chart 10 возвращают 200.
- python3 -m py_compile superset/create_dashboard.py; git diff --cached --check.
- Зачем:
- перечитка урока 3 свежим взглядом нашла баг в его эталонном пути: проверки
device_not_found/geo_not_found/location_not_found в DDS никогда не срабатывали,
а текст урока ошибочно утверждал, что метки ставятся
- Что:
- sql/dds/30_ods_to_dds.sql: добавлен SETTINGS join_use_nulls=1 в оба
INSERT...SELECT. Без него LEFT JOIN на несовпадении клал в assumeNotNull(click_id)
нулевой UUID (не NULL), и if(...IS NULL, ['*_not_found'], []) молча давал []
(мёртвый код). Тот же класс бага про типы/NULL, что kafka_ts в уроке 1
- docs/course/lessons/03_ods_to_dds.md: убраны ложные claim'ы про geo_not_found/
location_not_found, формулировки приведены к реальному поведению (клик без гео
остаётся с пустыми полями NULL; целостность событий — через orphan_events);
поправлена опечатка «список всех клиентов» → «всех кликов»
- Проверка:
- синтетический тест join_use_nulls=1: клик в device без geo → в ods_parse_errors
появляются geo_not_found и geo_country_missing (до фикса — пусто)
- LIMIT=50 make transform после фикса: dds.click=26, dds.event=50,
orphan_events=0, ни одной строки с непустым ods_parse_errors (вывод не изменился —
на чистом срезе несовпадений нет)
- Зачем:
- нужен завершённый урок 5, который объясняет мониторинг стенда без предположения, что менти уже знаком с Grafana.
- Что:
- добавлен урок про Prometheus targets, Grafana dashboards, exporters и alert rules.
- описан управляемый сбой через остановку airflow-scheduler и восстановление стенда.
- обновлены навигация курса, план урока и названия панелей мониторинга в operations runbook.
- Проверка:
- git diff --cached --check.
- сверка названий dashboard/panel/alert rules с provisioning-файлами Grafana.
- Зачем:
- урок 4 должен показывать не только измерение сирот в DDS, но и остановку Airflow DAG при нарушении связи dds.event -> dds.click.
- Что:
- добавлен assert_dds_integrity в etl_pipeline и документация управляемого красного сценария.
- вынесены общие helper'ы для SQL-split и boolean-параметров Airflow.
- добавлен урок 4 и обновлены навигация курса, план обучения и operations notes.
- Проверка:
- python3 -m py_compile airflow/dags/etl_pipeline_dag.py airflow/dags/ddl_init_dag.py airflow/dags/kafka_load_dag.py airflow/dags/utils/airflow_params.py airflow/dags/utils/sql_helpers.py.
- docker compose exec -T airflow-webserver airflow dags test etl_pipeline 2026-06-05T18:00:00 -c '{"full_refresh": true}'.
- Зачем:
- собрать разрозненные кусочки ODS в цельные сущности DDS и ввести понятие
целостности связей (сироты), пока без жёсткого гейта — он в уроке 4
- Что:
- добавлен docs/course/lessons/03_ods_to_dds.md: сущности dds.click/dds.event,
UNION-универсум кликов, дедуп через argMax, LEFT JOIN, понятие сироты,
управляемая правка (вставка сироты), recap STG→ODS→DDS, заметка про DM
- §3.1: «поток данных» в шапку sql/dds/30_ods_to_dds.sql
- демоут DM: убран закомментированный пример материализации в
sql/dm/40_dds_to_dm.sql, добавлены «поток данных» и заметка «VIEW сейчас,
материализуем если затормозит» со ссылкой на docs/ARCHITECTURE.md
- sql/ddl/dm/40_dm.sql: пояснён seed 1919 в groupArraySample, поправлен
неверный комментарий «последние» (groupArraySample берёт случайную выборку)
- README курса: индекс обновлён до «уроки 0–3»
- Проверка:
- LIMIT=50 make transform: dds.click=26, dds.event=50, orphan_events=0
- §4 на стенде: вставка события-сироты → orphan 0→1; LEFT JOIN в
dm.v_events_enriched даёт NULL по полям клика; make transform откатывает к 0
- /ai-text-lint (article): house style сохранён, AI-маркеры не найдены
- Зачем:
- наработанный по урокам 0–2 мягкий регистр жил только в памяти и хендоффах;
стандарт его не требовал — следующий урок мог уехать обратно в сжатый стиль
и повторить уже пройденные ошибки.
- Что:
- добавлен §2 «Регистр и голос»: расшифровка терминов на первом употреблении,
###-подзаголовки, разбивка «стен», человеческий тон, house style, ai-text-lint;
- в §1 описана шапка урока (Формат / «О чём урок простыми словами»), старые
«Статус: черновик» и «Режим: руки» помечены как не возвращать;
- добавлен §5 «Грабли»: проверять на стенде, сверять имена с DDL, один паттерн
на урок, спорные API ClickHouse — через MCP Context7;
- перенумерованы разделы (качество кода → §3, самопроверка → §4) и ссылки на них.
- Проверка:
- прочитать LESSON_STANDARD.md сверху вниз: §1–§5 идут по порядку, ссылки
«(раздел 4)» указывают на «Самопроверку».
- Зачем:
- на уроке 2 решили писать разжёванным языком; уроки 0–1 и шапки курса
остались в сжатом регистре, а слово «черновик»/«Режим: руки» путало менти.
- Что:
- урок 1: расшифрованы staging, MergeTree-дедуп, Materialized View и
виртуальные колонки; секция «Загляни внутрь» разбита на ###-подзаголовки;
плотные абзацы разбиты на пункты; добавлен зачин «О чём урок простыми словами».
- урок 0: добавлен зачин «О чём урок простыми словами» (лёгкая полировка).
- шапки всех уроков: «Статус: черновик. Режим: руки/наблюдение» заменены на
понятное «Формат: практика/наблюдение — …».
- PRD/LEARNING_PLAN/LESSON_STANDARD: убрано слово «черновик» из статуса.
- Проверка:
- grep -rn "черновик" docs/course/ — пусто;
- прочитать урок 1 сверху вниз: термины раскрыты на первом употреблении.
- Зачем:
- нужен учебный урок «руки» про типизацию слоя ODS и разделение
чистых/битых записей; по пути убрать мусор и неочевидности в
эталонном пути, чтобы он читался за один проход.
- Что:
- добавлен lessons/02_stg_to_ods.md по LESSON_STANDARD (6 секций,
режим «руки», эталон голоса — урок 1); регистр смягчён под уровень
«обзорно» с расшифровкой терминов (click-контекст, WITH, двойной учёт).
- 20_stg_to_ods.sql: поток данных в шапку + блок «DQ-split» (почему
строка может попасть и в основную таблицу, и в *_errors).
- 20_ods.sql: убран мусорный блок из 8 DROP TABLE mv_*_to_ods;
пояснено разное партиционирование (browser — по бизнес-дате,
click-контекст — по дате загрузки).
- Проверка:
- make ddl && make transform — проходят чисто, counts не изменились
(browser/location 50, device/geo 26 дедуп, *_errors 0).
- правка §4 (toFloat64OrNull→toInt64OrNull для geo_latitude) на стенде
даёт geo_by_click_errors 0→50 и NULL-широту с флагом bad_geo_latitude.
- Зачем:
- курсу нужна разминка перед уроком 1: связать словарь из обзорного
видео по Kafka (топик, партиция, offset, группа, lag) с живым стендом.
- Что:
- добавлен lessons/00_kafka_intro.md по LESSON_STANDARD в режиме
наблюдения (без управляемой правки и отката), эталон голоса — урок 1.
- честная врезка про lag: у групп ch_stg_* колонки offset/lag в Kafka UI
пустые, прогресс чтения смотреть в ClickHouse (system.kafka_consumers).
- README курса: в строке lessons теперь указаны уроки 0 и 1.
- Проверка:
- факты сверены на живом кластере: 4 топика *_events по 1 партиции,
4 группы ch_stg_* (STABLE, 1 участник); прогоном подтверждено, что
новая группа читает топик с начала (auto.offset.reset=earliest).
- Зачем:
- нужен первый урок курса по эталонному пути STG, а рамка курса описывала сопровождение как «сессию-сверку», хотя по факту это самостоятельная работа + еженедельный созвон.
- Что:
- добавлен docs/course/lessons/01_kafka_to_clickhouse.md (Kafka → ClickHouse, слой STG) по шаблону LESSON_STANDARD.
- в sql/ddl/stg/10_stg.sql исправлен баг kafka_ts во всех 4 MV: toInt64(DateTime64) срезал миллисекунды, kafka_ts по всему стенду был 1970-01-21; теперь _timestamp_ms присваивается напрямую (downstream на kafka_ts не опирается).
- урок 1 §3/§4 приведены к исправленному коду; врезка про рассинхрон MV↔таблица описывает реальное поведение (молчаливый сброс лишней колонки, не ошибка).
- «сессия/сессия-сверка» → «созвон» в PRD (датированная поправка), LESSON_STANDARD §6 (секция «Что должно получиться») и README курса; добавлена ссылка на открытый DE-роадмап.
- в LEARNING_PLAN исправлен вердикт аудита урока 1 (баг найден прогоном), war-story про toInt64(DateTime64) припаркована в урок 2.
- Проверка:
- прогон на стенде: make up && make ddl && LIMIT=50 make data → kafka_ts = 2026-… с миллисекундами; правка §4 (ALTER + пересоздание MV + TRUNCATE + перезаливка) и откат отработали.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- середина пайплайна перегружала один урок тремя паттернами; нужны честный такт и разведённые слои.
- Что:
- середина расщеплена: ODS и DDS — отдельные уроки (один паттерн на урок), DM демотирован в поверхность потребления; всего 7 уроков.
- зафиксированы финальные вердикты аудита и список правок по урокам (LEARNING_PLAN §3/§3.1), включая гейт целостности DAG.
- в LESSON_STANDARD добавлены шаг отката «верни как было» и артефакт на сессию; в PRD обновлены скоуп и такт ~день на урок.
- Проверка:
- вычитка docs/course/{PRD,LEARNING_PLAN,LESSON_STANDARD}.md: номера уроков, скоуп и перекрёстные ссылки сходятся.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- развести документацию по времени жизни: транзиентные спеки отдельно от
долговечных решений (ADR) и доменного словаря (CONTEXT.md), вместо одного
громоздкого spec-документа.
- Что:
- добавлен блок Agent skills в AGENTS.md (issue tracker / triage / domain docs).
- созданы docs/agents/{issue-tracker,triage-labels,domain}.md: локальный
markdown-трекер в .scratch/, дефолтные triage-метки, single-context раскладка.
- зафиксировано решение как docs/adr/0001-spec-adr-issue-layout.md.
- Проверка:
- git show --stat HEAD; прочитать AGENTS.md и docs/adr/0001-spec-adr-issue-layout.md.
- Зачем:
- превратить стенд в самостоятельный учебный материал (трек «со звёздочкой») для продвинутых менти.
- Что:
- docs/course/: PRD, LEARNING_PLAN, LESSON_STANDARD и README-индекс.
- AGENTS.md: ссылка на курс в разделе навигации.
- CLAUDE.md: @-include AGENTS.md для контекста агента.
- Проверка:
- открыть docs/course/README.md и пройти по ссылкам на PRD/план/стандарт.
- Зачем:
- уточнен приоритет языка (русский по умолчанию)
- добавлены критерии обязательности body
- дополнены примеры и шаблоны
- Что:
- изменен primary language на Russian
- добавлены правила для AI-generated commits
- добавлена форма глагола для русского языка (результативная)
- перенесены шаблоны: Russian → default, English → lang:en
- обновлены все примеры на русский язык
- Проверка:
- git log --oneline проверяет формат
- Why:
- VS Code settings are personal IDE preferences, not shared project config
- What:
- remove !.vscode/settings.json exception from .gitignore
- Refs: AGENTS.md
- make superset-init run via dedicated init service\n- tolerate missing dm views during early metadata refresh\n- add clickhouse dependency for init service\n- document clean-reset behavior and re-init flow
- switch Superset ClickHouse URI back to clickhousedb://\n- refresh dataset metadata during init to restore filter columns\n- install runtime deps in image layer and add troubleshooting notes
- Why:
- align interview demo with recruiter requirement for 10-15 minutes
- What:
- add timed walkthrough with code, architecture and verification points
- include fallback steps for UI issues and final speaking script
- Check:
- verify paths/commands against repository files and DAG ids
- Why:
- Superset bootstrap used outdated ClickHouse URI format and did not fail fast on init errors.
- docs and exported dashboard metadata diverged from runtime connection settings.
- What:
- build ClickHouse URI from env vars and use clickhousedb:// in init script.
- refresh dataset metadata on existing datasets and surface import errors.
- run create_dashboard during superset-init startup and align docs/exported URI references.
- ignore node_modules in git.
- Check:
- python3 -m py_compile superset/init_superset.py
- manual dashboard smoke check in UI (charts render)
- Why:
- dashboard tiles failed with "Item with key 'echarts_bar' is not registered".
- existing slice query_context stayed stale after config updates.
- What:
- switch Top Pages and Data Quality Summary from \'echarts_bar\' to \'dist_bar\'.
- use \'groupby\' for categorical bar charts and sync this into query_context.
- keep dashboard export config aligned with runtime chart definitions.
- Check:
- python3 -m py_compile superset/create_dashboard.py
- docker compose exec -T superset python /app/superset_init/create_dashboard.py
- DB check for slices 9/10: viz_type=form_data=query_context set to dist_bar
- Добавлена автоматическая инициализация Superset (подключение ClickHouse, 6 датасетов, 10 чартов, дашборд)
- Переведено хранение метаданных с SQLite на PostgreSQL (shared с Airflow)
- Добавлен superset_config.py для конфигурации PostgreSQL
- Обновлен Dockerfile.superset: postgresql-client, psycopg2-binary
- Обновлен docker-compose.yml: volume mount конфига, SUPERSET_CONFIG_PATH
- Исправлены скрипты init_superset.py и create_dashboard.py для работы с shell
- Обновлена документация в README.md: раздел Superset с инструкциями
Тестирование:
- Проверена работа после перезапуска (данные сохраняются)
- Проверен чистый запуск с нуля
- API и UI доступны
- Исправлен путь Kafka volume с /tmp/kraft-combined-logs на /var/lib/kafka/data
(решена проблема с правами доступа при старте Kafka)
- Обновлен superset/init_superset.py: улучшена обработка ошибок SQLite
- Обновлен superset/create_dashboard.py: оптимизирован импорт модулей
- Why:
- give a student a short, repeatable interview demo script
- What:
- add 5-minute timeline with speaking prompts
- add SQL/CLI commands and fallback plan for UI issues
- Check:
- review markdown content in docs/DEMO_CHEATSHEET_5MIN.md
- Why:
- formalize complete end-to-end verification for the demo DWH stack
- provide fast regression checks and full validation before demo/release
- What:
- add new TEST_PLAN.md with two execution contours: Smoke and Full
- include checks for infra bootstrap, Airflow DAG flow, STG/ODS/DDS/DM data quality, monitoring and alert provisioning
- add dedicated scenario proving dirty records are captured in ods.*_errors without breaking ETL
- Check:
- aligned steps with current DAG parameters/tasks and SQL transformation flow
- validated expected alert names against Grafana provisioning files
- Why:
- intensive development needs quick cluster stop/cleanup commands
- current Makefile had only up and pipeline/monitoring targets
- What:
- add make target down for standard docker compose shutdown
- add make target clean for full cleanup with volumes and orphans
- update OPERATIONS runbook with new make commands
- Check:
- make -n down clean
- Why:
- during intensive development monitoring can get stuck (No data, out of bounds)
- regular reload is not always enough to recover Prometheus + StatsD pipeline
- What:
- add make target recover-monitoring for hard recovery path
- recreate prometheus and statsd-exporter, restart airflow scheduler/webserver
- keep Grafana provisioning reload and target checks in one command
- document when to use recover-monitoring in OPERATIONS runbook
- Check:
- run make recover-monitoring
- verify Prometheus targets for airflow/clickhouse/kafka are up
- Add port 9126 mapping for ClickHouse Prometheus metrics endpoint
(was configured in prometheus_ch.xml but not exposed in docker-compose.yml)
- Fix CPU Usage panel: use delta() instead of rate() for gauge metric
ClickHouseProfileEvents_OSCPUVirtualTimeMicroseconds is a gauge, not counter
- Add explicit datasource blocks to dashboard queries for consistency
ClickHouse ProfileEvents metrics correctly use rate() — they are counters.
Warning about missing _total suffix is expected (ClickHouse naming convention).
- Why:
- Airflow task metrics were mapped to non-emitted StatsD keys
- reload-monitoring did not restart statsd-exporter after mapping changes
- What:
- update StatsD mapping for Airflow 2.10.5 metric names
- remove problematic catch-all mapping that produced inconsistent series
- restart statsd-exporter in reload-monitoring flow
- sync operations runbook and airflow monitoring plan with actual metrics
- Check:
- make reload-monitoring
- Prometheus targets: airflow/clickhouse/kafka are UP
- trigger ddl_init and verify airflow_task_duration_seconds_count
- verify airflow_task_success_total and airflow_task_failures_total in Prometheus
Fix Grafana warning about using rate() on gauge metric:
- ClickHouseProfileEvents_OSCPUVirtualTimeMicroseconds is a gauge, not counter
- rate() should only be used with counters; using delta() instead
- Add explicit datasource block for consistency
API verified via Context7:
- /prometheus/docs: rate() should never be used on gauges
Add missing entries for monitoring infrastructure:
- prometheus.yml, statsd_mapping.yml configs
- ClickHouse user configs (default_user.xml, prometheus_ch.xml)
- Grafana alerting rules for Kafka and Airflow
- Grafana dashboards for all services
- Monitoring plans (airflow, kafka)
This completes the documentation for the monitoring stack added
in the previous commits.
- Add statsd-exporter service to docker-compose.yml (prom/statsd-exporter:v0.27.1)
- Add StatsD env vars to airflow-default-env for metrics export
- Add airflow job to prometheus.yml scrape configs
- Add Airflow Overview dashboard (Grafana provisioning)
- Add Airflow alert rules: scheduler down, queue backlog, failures, parse time
- Add configs/statsd_mapping.yml for StatsD → Prometheus conversion
- Use Prometheus naming convention (_total for counters, _seconds for timers)
- Add monitoring plan at plans/monitoring_airflow_plan.md
- Update OPERATIONS.md and Makefile for airflow monitoring
Tested: all 3 jobs (airflow, clickhouse, kafka) showing UP in Prometheus,
metrics flowing (dagbag_size=3, executor slots, heartbeats with _total suffix),
all 4 alert rules loaded in Grafana
- Why:
- dashboard showed offset as throughput and produced misleading values
- kafka-exporter metric/label naming was inconsistent across alerts/docs
- consumer-group-missing alert was noisy for demo runs
- What:
- switch throughput panel to rate(kafka_topic_partition_current_offset[5m]) aggregated by topic and exclude __* topics
- align lag metric/labels to kafka_consumergroup_lag + consumergroup
- remove Kafka Consumer Group Missing alert from provisioning
- pin kafka-exporter image to v1.9.0 and update OPERATIONS.md checks
- Check:
- airflow dags list-import-errors -> No data found
- Prometheus targets: clickhouse up, kafka up
- PromQL kafka_consumergroup_lag returns series
- Grafana dashboards provisioning reload returns success
- Why:
- students hit permission denied after pull and grafana restart-loop with readonly db
- What:
- run grafana as default non-root user
- mount provisioning directory as read-only
- add troubleshooting for git permission issues and grafana volume reset
- normalize file modes for data jsonl and docs/DE-task.md to 100644
- Check:
- docker compose config
- docker compose up -d grafana
- curl -u admin:admin http://localhost:3000/api/health
- Add kafka-exporter service to docker-compose.yml
- Add kafka job to prometheus.yml scrape configs
- Add Kafka Overview dashboard (Grafana provisioning)
- Add Kafka alert rules (broker down, consumer lag, etc.)
- Add make reload-monitoring command for easy updates
- Update OPERATIONS.md with TL;DR and troubleshooting
API verified via Context7:
- /danielqsj/kafka_exporter for exporter config
- /prometheus/docs for scrape_configs format
- Why:
- student needs a simple way to apply Grafana/monitoring config updates after git pull
- What:
- add TL;DR block with minimal commands in monitoring section
- add detailed post-pull runbook for datasource/dashboard/alerting reload
- include clickhouse restart note for prometheus_ch.xml changes
- Check:
- reviewed commands and paths in docs/OPERATIONS.md
- Why:
- dashboard panels could resolve to stale datasource uid and show No data
- monitoring required proactive alerts for ClickHouse health signals
- What:
- pin dashboard panels to prometheus_uid and remove datasource templating variable
- fix PromQL metrics for CPU, inserted rows, and parts panels
- add provisioning alert rules for failed queries, memory resident, and active parts
- pin Prometheus datasource uid and update monitoring documentation
- Check:
- POST /api/admin/provisioning/datasources/reload
- POST /api/admin/provisioning/dashboards/reload
- POST /api/admin/provisioning/alerting/reload
- GET /api/v1/provisioning/alert-rules
- Why:
- commit messages with literal \n are hard to read in UI
- What:
- add explicit rule for multiline body formatting in CLI
- add correct examples with git commit -m and -F heredoc
- Check:
- reviewed new section in docs/COMMIT_RULES.md
- Why:\n - AGENTS.md became too large and mixed policy with operational details\n - context7 requirement was easy to miss in long text\n- What:\n - reduce AGENTS.md to a compact contributor contract\n - add explicit mandatory MCP Context7 workflow block\n - move runbook details to docs/OPERATIONS.md\n - move artifact map to docs/REPO_MAP.md\n- Check:\n - reviewed links and content after split\n - ensured only documentation files are included in commit
- Why:
- keep Airflow artifacts under a single airflow/ directory
- align repository layout with intended project structure
- What:
- move dags/ to airflow/dags/ and update compose mounts
- make SQL root resolution work in container and local runs
- update DAG path references in README, AGENTS, ARCHITECTURE, and plans
- remove tracked Python cache artifacts from old DAG location
- Check:
- airflow dags list
- airflow dags list-import-errors
- e2e success: ddl_init, kafka_load(limit=50), etl_pipeline
ddadmin
