clickstream-ch-kafka-superset-demo/plans/generator_demo_stream_plan.md

План реализации: простой автономный генератор (rev4)

Дата ревизии: 14 февраля 2026.

---

1) Цель

Сделать простой генератор, который:

• работает автономно и не зависит от потребителей;
• может стабильно работать несколько часов;
• публикует данные в текущие Kafka-топики по существующему контракту;
• реально внедряется за короткий срок, без «проекта на недели».

---

2) Что делаем в MVP (и что не делаем)

Делаем

• один режим генерации;
• один автономный сервис (контейнер);
• простая конфигурация через env;
• базовые метрики и логи;
• минимальная история запусков.

Не делаем в MVP

• много сценариев (promo/incident/...);
• сложные state machines;
• сложный replay;
• сложную оркестрацию с зависимостями от ETL;
• «идеальный прод» (exactly-once и т.д.).

---

3) Архитектура MVP

generator-service -> Kafka topics -> (потребители отдельно)

Генератор не вызывает Airflow DAG-и и не ждёт их.
Потребители запускаются по своему расписанию/логике.

---

4) Единственный режим генерации: steady

Логика режима:

• каждую минуту публикуем фиксированный объём событий;
• распределяем события по 4 топикам:
  • browser_events
  • location_events
  • device_events
  • geo_events
• слегка «оживляем» поток:
  • варьируем объём в небольшом диапазоне;
  • обновляем event_timestamp;
  • сохраняем реалистичные связи event_id <-> location, click_id <-> device/geo.

Этого достаточно, чтобы стенд жил часами и данные выглядели не статично.

4.1 Минимальная статистическая модель (Poisson)

Чтобы линия не была «ровной», используем простую интенсивность событий:

• число событий на тик: N_t ~ Poisson(lambda_t);
• базовая интенсивность: lambda_base (например, 200 событий/мин);
• плавный профиль времени: lambda_t = lambda_base * hour_factor(t).

Где hour_factor(t) можно сделать очень простым:

• дневное окно: 1.2
• ночное окно: 0.7
• остальное время: 1.0

Плюс добавляем «защиту от шума»:

• N_min и N_max (жёсткие границы);
• опционально короткое сглаживание по 3 последним тикам.

Итог: поведение уже похоже на живой поток, но код остаётся компактным.

---

5) Как упростить реализацию

Чтобы не писать сложную генеративную модель:

1. Берём существующие JSONL как «базовый словарь» валидных событий.
2. На каждом тике семплируем записи из этого словаря.
3. Перегенерируем только необходимые поля (event_id, click_id, event_timestamp) с сохранением связности.
4. Публикуем в Kafka.

Плюс:

• быстро;
• совместимо с текущим ODS-парсингом;
• минимум риска «сломать контракт».

---

6) Минимальная конфигурация сервиса

Через env:

• GEN_TICK_SECONDS (по умолчанию 60)
• GEN_EVENTS_PER_TICK (например, 200)
• GEN_JITTER_PCT (например, 20)
• GEN_SEED (для воспроизводимости)
• KAFKA_BOOTSTRAP_SERVERS
• GEN_LAMBDA_BASE_PER_MIN (базовый lambda для Poisson)
• GEN_MIN_EVENTS_PER_TICK (нижняя граница)
• GEN_MAX_EVENTS_PER_TICK (верхняя граница)

Опционально:

• GEN_ENABLED (быстро включать/выключать цикл)
• GEN_HOUR_PROFILE (простая карта коэффициентов по часам)

---

7) Минимальная наблюдаемость

Логи

• старт/стоп сервиса;
• batch_id, объём отправки по топикам;
• длительность тика;
• ошибки публикации.

Метрики (минимум)

• generator_events_total
• generator_publish_errors_total
• generator_tick_duration_seconds
• generator_last_success_timestamp

Минимальная история

Таблица meta.generator_batches (или файл/лог на первом шаге):

• batch_id
• started_at
• finished_at
• sent_total
• sent_browser/location/device/geo
• status

---

8) План внедрения (короткий и реалистичный)

Шаг 1. Skeleton сервиса

• отдельная папка generator/;
• бесконечный цикл с тиком;
• подключение к Kafka;
• публикация в 4 топика.

Готово, если:

• сервис работает 1+ час без падений.

Шаг 2. Контрактная генерация из словаря

• чтение базовых JSONL;
• семплирование + обновление ключевых полей;
• проверка, что downstream не ломается.

Готово, если:

• ODS/DDS наполняются штатно.

Шаг 3. Логи/метрики/история batch

• добавить базовые метрики;
• писать историю batch;
• оформить runbook запуска/проверки.

Готово, если:

• можно показать историю работы стенда за несколько часов.

---

9) Критерии успеха MVP

MVP успешен, если:

1. Генератор автономно работает 2-4 часа.
2. Потребители можно останавливать/запускать отдельно, генератор продолжает работу.
3. Данные остаются совместимыми с текущим пайплайном.
4. Есть базовые метрики и понятные логи.
5. Есть история batch-ов для учебного разбора.

---

10) Что делаем потом (после рабочего MVP)

Когда простой генератор стабильно работает:

1. Добавляем второй режим (например, «spike»).
2. Делаем инкрементальных потребителей и расписание ETL.
3. Расширяем учебные кейсы по observability и DQ.
4. Усиливаем статистику: например, Gamma-Poisson/Negative Binomial для более «рваного» трафика.

Принцип: сначала работающий простой baseline, потом расширение.