From 4fbe82e74c0aa117da2eaf0eff81220e505044e4 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Mon, 9 Feb 2026 23:21:12 +0300 Subject: [PATCH] docs(docs): add plan for long-running demo data generator - Why: - define a clear architecture for continuous demo data generation - ensure visual analytics with realistic scenario-based behavior - What: - add a standalone plan with target architecture and components - define demo_visible_v1 scenarios, KPI ranges, and DQ behavior - describe Airflow orchestration, observability, rollout stages, and acceptance criteria - Check: - reviewed document structure and consistency in plans/ --- plans/generator_demo_stream_plan.md | 234 ++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 plans/generator_demo_stream_plan.md diff --git a/plans/generator_demo_stream_plan.md b/plans/generator_demo_stream_plan.md new file mode 100644 index 0000000..2525bb4 --- /dev/null +++ b/plans/generator_demo_stream_plan.md @@ -0,0 +1,234 @@ +# План реализации: генератор долгоживущего demo-потока данных + +Цель: спроектировать генератор, который непрерывно производит правдоподобный поток событий для стенда и делает графики/аналитику визуально "живыми" без ручной подгрузки файлов. + +Документ фиксирует верхнеуровневую архитектуру, целевые параметры для наглядности и этапы внедрения с минимальным риском для текущего контура. + +--- + +## 1) Цель и границы MVP + +### Цель + +- Обеспечить поток данных "в долгую" (24/7 или во время демо-сессий). +- Сохранить совместимость с текущим контрактом входных событий. +- Получить в дашбордах заметные изменения метрик за 10-15 минут наблюдения. + +### Границы MVP + +- Никаких изменений в текущих слоях `STG -> ODS -> DDS -> DM`. +- Генератор работает как отдельный upstream к Kafka. +- Формат output генератора идентичен текущему формату `data/*.jsonl` (1 JSON = 1 Kafka message). + +--- + +## 2) Нефункциональные требования для "наглядного" демо + +- Запуск генерации: каждую минуту. +- Время обработки одного запуска: до 40 секунд, чтобы не накапливались overlapping runs. +- Контролируемая нагрузка для локального стенда: базово `~300 events/min`, пик `~900 events/min`. +- Детерминизм при retry: повторный запуск того же `run_id` формирует тот же набор событий. +- Устойчивость к "грязным" данным: ошибки должны фиксироваться downstream, но не валить пайплайн. + +--- + +## 3) Целевая архитектура генератора + +### 3.1 Позиция в текущем контуре + +`Generator -> Kafka topics -> ClickHouse STG -> ODS -> DDS -> DM` + +Текущие DAG'и `ddl_init`, `kafka_load`, `etl_pipeline` остаются рабочими. Генератор добавляется как отдельный режим поставки данных. + +### 3.2 Логические компоненты + +1. `Scheduler` +- Триггер раз в минуту через отдельный Airflow DAG `generator_minutely`. + +2. `Scenario Engine` +- Вычисляет профиль минуты: сколько и каких событий генерировать. +- Управляет сценариями `normal`, `promo`, `incident`. + +3. `State Store` +- Хранит состояние между запусками: активные пользователи/сессии, текущий сценарий, служебные seed/run метаданные. +- MVP-вариант: таблица в ClickHouse (`ods.generator_state`) или отдельный компактный state-файл в volume. + +4. `Event Builder` +- Генерирует события строго по действующему контракту полей и типов. +- Добавляет служебные поля только при обратной совместимости (например, `generator_run_id`, `scenario_version`). + +5. `Corruption Injector` +- Добавляет управляемую долю неидеальных событий (malformed, missing fields, duplicate, late events). + +6. `Publisher` +- Публикует события в те же Kafka-топики, что использует текущий ingest. + +7. `Metrics Emitter` +- Пишет техметрики генератора для Prometheus/Grafana. + +--- + +## 4) Модель "наглядного" поведения (demo_visible_v1) + +### 4.1 Базовые сценарии + +1. `normal` (около 70% времени) +- Стабильный фоновый трафик. + +2. `promo` (около 20% времени) +- Рост paid-трафика и CTR. +- Умеренный рост конверсий. + +3. `incident` (около 10% времени) +- Рост доли ошибок и late events. +- Просадка CR и качества данных. + +Переключение сценариев должно быть запланированным и видимым на горизонте 10-15 минут. + +### 4.2 Целевые KPI-диапазоны + +- `CTR`: 3-8% +- `CR`: 1-2.5% +- `AOV` (средний чек): медиана 35-60, длинный хвост до 200+ +- `DQ error rate`: 1-2%, во время `incident` до 4-5% + +### 4.3 Распределения и зависимости + +- Нагрузка во времени: неравномерная (пики и просадки). +- Сегменты: `new/returning`, `device`, `source`, `geo`. +- Переходы внутри сессии: вероятностная цепочка `view -> click -> add_to_cart -> purchase`. +- Поля не генерируются независимо: должны быть корреляции (пример: изменение source влияет на CTR/CR). + +--- + +## 5) Контракт данных и идемпотентность + +### 5.1 Контракт output + +- Формат сообщения: JSON-объект одной строкой. +- Topic mapping: как в текущем процессе загрузки (`browser_events`, `location_events`, `device_events`, `geo_events`). +- Совместимость с текущими парсингом и DDL обязательна. + +### 5.2 Batch/run модель + +- Каждый минутный запуск имеет `batch_id` (`YYYYMMDDHHmm`) и `run_id`. +- Seed вычисляется детерминированно от `batch_id` (+ version salt). +- При retry того же `run_id` набор событий должен совпадать. + +--- + +## 6) Оркестрация в Airflow (верхний уровень) + +Отдельный DAG `generator_minutely`: + +- `schedule`: каждую минуту. +- `catchup=False` +- `max_active_runs=1` +- Короткий `execution_timeout`. + +Этапы DAG: + +1. `prepare_context` +- Рассчитать `batch_id`, `run_id`, seed, активный сценарий. + +2. `generate_batch` +- Сгенерировать события за минуту в памяти/временном буфере. + +3. `publish_kafka` +- Отправить события в Kafka. + +4. `emit_metrics` +- Зафиксировать метрики запуска (объем, ошибки, задержка). + +--- + +## 7) Наблюдаемость и алерты + +### 7.1 Метрики генератора (минимум) + +- `generator_events_total` +- `generator_invalid_total` +- `generator_duplicates_total` +- `generator_late_events_total` +- `generator_batch_duration_seconds` +- `generator_publish_errors_total` + +### 7.2 Минимальные алерты + +- Нет новых событий > 3 минут. +- Длительность batch выше порога (например, > 45 сек). +- Доля invalid выше ожидаемой (например, > 5% вне `incident` окна). + +--- + +## 8) План внедрения по этапам + +### Этап 1: Skeleton + совместимость + +- Реализовать каркас генератора без сложных распределений. +- Включить публикацию в Kafka в текущем формате. +- Проверить, что текущий `etl_pipeline` работает без изменений. + +Критерий готовности: +- Поток стабильно идет 30+ минут. +- STG/ODS/DDS/DM наполняются штатно. + +### Этап 2: Сценарии и распределения + +- Добавить `normal/promo/incident`. +- Включить корреляции полей и KPI-диапазоны. +- Включить управляемую "грязь". + +Критерий готовности: +- На дашбордах заметны смены сценариев и поведение KPI. + +### Этап 3: Statefulness + reliability + +- Добавить хранилище state между минутами. +- Доработать retry/идемпотентность и recovery. +- Ввести базовые алерты на генератор. + +Критерий готовности: +- При рестартах и ретраях поток остается предсказуемым. + +--- + +## 9) Риски и меры снижения + +1. Слишком "ровный" поток неинтересен для аналитики. +- Мера: сценарные переключения и целевые KPI-паттерны. + +2. Слишком тяжелая генерация перегружает стенд. +- Мера: жесткие лимиты `events/min`, timeout и `max_active_runs=1`. + +3. Ломается совместимость формата. +- Мера: contract tests against current parser/ODS inserts. + +4. Дубли при ретраях. +- Мера: детерминированный seed + фиксированный `run_id`. + +--- + +## 10) Acceptance criteria для demo-ready статуса + +Считаем задачу завершенной, если: + +1. Генератор работает по расписанию 1 раз в минуту и стабильно публикует данные. +2. Текущий downstream пайплайн не требует изменений для приема потока. +3. За 10-15 минут на графиках видно: +- смену структуры трафика, +- заметное изменение CTR/CR, +- реакцию DQ-метрик в `incident`. +4. Повторный retry run не генерирует новый "случайный" набор событий. +5. Есть базовые техметрики и алерты генератора. + +--- + +## 11) Что намеренно не включаем в MVP + +- Продвинутое ML-моделирование поведения пользователей. +- Сложные внешние reference-данные и enrichment в генераторе. +- Полную эмуляцию всех edge-кейсов production-среды. + +Сначала приоритет: наглядность, повторяемость, совместимость со стендом. +