clickstream-ch-kafka-superset-demo/docs/course/lessons/00_kafka_intro.md

Урок 0. Вводный по Kafka (Kafka UI, наблюдение)

Формат: наблюдение — ничего не запускаем и не меняем, только смотрим. Пререквизит: обзорное видео по Kafka из роадмапа — оттуда ты уже знаешь слова «топик», «партиция», «offset», «consumer-группа», «lag». Этот урок связывает их с живым стендом, чтобы они перестали быть просто словами. Эталонный путь: сам Kafka UI на http://localhost:8082.

Поток данных одной строкой: готовый источник данных стенда → топики Kafka (партиции, offset'ы) → consumer-группа ClickHouse вычитывает

О чём урок простыми словами: ходим по Kafka UI и разглядываем поток — где лежат события, кто их читает и как Kafka помнит, до какого места уже дочитано.

---

1. Зачем и где в проде

В обычной кликстрим-аналитике между тем, кто порождает события (трекер на сайте, в приложении), и тем, кто их считает (хранилище, BI), почти всегда стоит Kafka. Она — буфер и общий журнал: producer пишет события, не зная и не дожидаясь, кто их прочитает; consumer читает в своём темпе, не трогая producer'а. Если читатель отстал или прилёг — события не теряются, они лежат в топике и ждут.

На нашем стенде роли уже расставлены: готовый источник данных стенда играет роль трекера и пишет события в топики, а ClickHouse — это consumer, который их вычитывает. Для курса нам важно не устройство источника, а сам путь данных: Kafka → STG → ODS → DDS → DM → Superset. Файлы data/*.jsonl здесь не источник аналитики; пока это только кладовка готовых значений для источника данных стенда.

В этом уроке мы не запускаем пайплайн и ничего не меняем — мы открываем Kafka UI и узнаём в живом кластере те самые понятия из видео. Это разминка: в уроке 1 ты уже руками увидишь, как эти же сообщения доезжают до таблиц ClickHouse.

В проде так же, только крупнее. Здесь один брокер и крошечный срез данных. В бою брокеров несколько, топик разбит на много партиций, читателей в группе — тоже несколько, и Kafka сама делит партиции между ними. Понятия при этом ровно те же, что мы сейчас разглядим на маленьком кластере.

---

2. Наблюдай: открой Kafka UI

Стенд уже должен быть поднят, а в топиках должны лежать события после стартовой истории:

make generated-history-analytics
make up

Открой Kafka UI: http://localhost:8082. Ходи по нему свободно — это режим чтения, сломать тут ничего нельзя.

Пройди по трём экранам и просто посмотри.

Топики (раздел Topics). Увидишь четыре топика событий — по одному на тип:

• browser_events — события браузера (pageview и т.п.);
• device_events — про устройство;
• geo_events — гео;
• location_events — местоположение.

Рядом могут быть служебные топики:

• __consumer_offsets — внутренний топик Kafka. В нём Kafka хранит прогресс consumer-групп;
• generator_state — слепок состояния генератора на правой границе стартовой истории. По нему live-продолжение понимает, откуда продолжать тот же мир;
• generator_startup_history_manifest — паспорт стартовой истории: seed, границы модельного времени и контрольные числа.

Служебные топики нужны стенду, но в упражнениях курса мы их не меняем. У каждого нашего топика событий в колонке с партициями стоит 1: топик маленький, делить не на что.

Сообщения в топике. Открой browser_events → вкладку Messages. Это и есть события стенда. У каждого сообщения видно:

• Offset — порядковый номер сообщения в партиции (0, 1, 2, …);
• Timestamp — когда сообщение легло в Kafka (время доставки, не время самого события);
• Value — тело: JSON события целиком, например:

{"event_id": "8cca1c7d-...", "event_timestamp": "2026-01-01 00:01:00.000000",
 "event_type": "pageview", "browser_name": "Chrome", "browser_language": "sat_IN"}

Загляни внутрь Value: у события есть своё event_timestamp (когда оно случилось, модельное время стенда), и оно отличается от Kafka-Timestamp (когда оно попало в топик). Два разных времени у одной записи — запомни этот момент, в уроке 1 он всплывёт уже на стороне ClickHouse.

Consumer-группы (раздел Consumers). Здесь видно, кто читает топики. Найдёшь четыре группы — по одной на топик:

• ch_stg_browser, ch_stg_device, ch_stg_geo, ch_stg_location.

Это ClickHouse: он подключился к Kafka как читатель и для каждого топика завёл отдельную группу. У каждой статус STABLE и 1 участник (member) — тот самый единственный consumer ClickHouse.

---

3. Загляни глубже: что значат эти экраны

Сложим увиденное в понятия — те же, что в видео, но теперь привязанные к экрану.

Понятие	Что это	Где увидел в Kafka UI
Топик	именованный поток событий одного типа	browser_events и три соседних
Партиция	часть топика, внутри которой строгий порядок	у нас по 1 на топик
Offset	номер сообщения внутри партиции, по нему адресуют запись	колонка Offset в Messages
Consumer-группа	читатели топика; группа помнит, до какого offset'а дочитали	ch_stg_* в разделе Consumers
Lag	отставание: сколько в топике уже есть, но ещё не прочитано	колонка пустая — см. врезку ниже

Главная мысль: offset — это адрес сообщения, а не его содержимое. Пара «партиция + offset» однозначно показывает на конкретную запись в топике. Именно по offset'у consumer-группа помнит, где остановилась: дочитала до 19 — в следующий раз начнёт с 20, а не сначала. Поэтому имя группы — не косметика: смени его, и читатель начнёт топик заново (это ты потрогаешь руками в уроке 1, там группа задаётся в DDL как kafka_group_name).

Lag (отставание) — это, по сути, простая арифметика: сколько сообщений в топике уже есть, минус сколько группа успела прочитать. Ноль — читатель идёт вровень с потоком; растёт — читатель не успевает.

Маленькая честность про lag. У групп ch_stg_* колонки offset и lag в Kafka UI окажутся пустыми, хотя сама группа живая (STABLE, 1 участник). Это не баг и не поломка: так уж ClickHouse-движок работает с группой — свой прогресс чтения он держит на своей стороне (его видно в системной таблице system.kafka_consumers), и именно там стоит смотреть, не отстаёт ли он. Не удивляйся пустой ячейке offset/lag в Kafka UI; проверять отставание ClickHouse удобнее с его конца — этим и займёшься в уроке 1.

---

4. Проверь себя

Действие	Где смотреть	Что ожидать
открыть список топиков	Kafka UI → Topics	4 топика событий (*_events) и, возможно, служебные топики генератора
открыть browser_events	вкладка Messages	сообщения с offset'ами 0, 1, 2, …; в Value — JSON события
сравнить два времени	Value (event_timestamp) vs Kafka Timestamp	время события и время доставки в Kafka различаются
открыть consumers	Kafka UI → Consumers	4 группы ch_stg_*, статус STABLE, по 1 участнику

---

5. Что должно получиться

После урока у тебя в голове — карта живого кластера: четыре топика событий, в каждом сообщения с offset'ами, и четыре consumer-группы ClickHouse, которые их читают. Ничего не меняли — только сопоставили слова из видео с экранами Kafka UI.

И проверь себя на словах: сможешь объяснить, чем топик отличается от партиции, что такое offset и зачем consumer-группе его помнить? Короткая зацепка для ответа — что произойдёт, если читатель забудет свой offset и начнёт топик сначала? Примерно такие вопросы по теме урока всплывут на еженедельном созвоне.

---

Мост к уроку 1

Мы посмотрели на поток со стороны Kafka: события лежат в топиках, ClickHouse подключён к ним группами и что-то вычитывает. Логичный следующий вопрос: а куда именно ClickHouse кладёт прочитанное и как он это делает? Об этом — урок 1: там ты руками увидишь, как сообщение из топика превращается в строку таблицы ClickHouse, и заодно посмотришь на чтение Kafka «с другого конца».