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.
167 lines
12 KiB
Markdown
167 lines
12 KiB
Markdown
# Урок 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
|
||
|
||
Стенд уже должен быть поднят, а в топиках должны лежать события после стартовой истории:
|
||
|
||
```bash
|
||
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, границы
|
||
модельного времени и контрольные числа;
|
||
- `generator_batch_history` — журнал батчей генератора: сколько сообщений он
|
||
отправил и чем закончилась каждая пачка записи.
|
||
|
||
Служебные топики нужны стенду, но в упражнениях курса мы их не меняем. У каждого нашего
|
||
топика событий в колонке с партициями стоит **1**: топик маленький, делить не на что.
|
||
|
||
**Сообщения в топике.** Открой `browser_events` → вкладку *Messages*. Это и есть события
|
||
стенда. У каждого сообщения видно:
|
||
|
||
- **Offset** — порядковый номер сообщения в партиции (0, 1, 2, …);
|
||
- **Timestamp** — когда сообщение легло в Kafka (время *доставки*, не время самого события);
|
||
- **Value** — тело: JSON события целиком, например:
|
||
|
||
```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 «с другого конца».
|