ddadminandClaude Opus 5
a61f7934ec
- Зачем:
- до сих пор генератор умел собирать день, но не умел его отдать: топик
hits наполнялся пробником, а не настоящими данными. Тикет #41 доводит
события до стенда и закрывает форму на проводе, на которую обопрётся
типизированный ODS (#43).
- сериализатор один по решению спеки: второе место, печатающее событие в
JSON, разошлось бы с первым молча.
- Что:
- serialize.py — канонический сериализатор на orjson: единственное место,
где событие целиком становится JSON; 47 ключей всегда, «пусто» это
пустое значение, даты ISO-8601, ecommerce строкой. Вложенный блок
ecommerce в commerce.py вторым сериализатором не считается — правило
про событие, а не про блок внутри него.
- sinks.py — приёмники: файл (одно событие — одна строка) и Kafka (одно
событие — одно сообщение). Ключа у сообщения нет: WatchID уникален,
ключом он был бы ключом лишь на вид.
- player.py, cli.py — проигрыватель и интерфейс запуска: режимы batch и
live (темп ×60), несколько дней одним запуском, ограниченная пачка,
раздельные тайминги генерации и доставки, лаг в логе.
- день на оси и имя топика умолчаний не имеют: параметр, описывающий
среду или позицию, приходит от зовущего, иначе отказ до генерации.
Умолчания зерна, числа дней и темпа остаются — они описывают мир.
- generator/Dockerfile — свой образ: зависимости из uv.lock, база
закреплена до патча, раскладка репозитория сохранена ради каталога
товаров. Образ Airflow не тронут.
- разовая служба compose под профилем, цели generate-batch и
generate-live, .dockerignore, tmp/ в .gitignore.
- решения внесены в спеку (разделы 4, 8, 9), быстрый старт — в README.
- Проверка:
- make test 406 passed, make lint, make typecheck, make config-test.
- побайтовый детерминизм: два прогона дня в независимых процессах дают
один sha256; день в контейнере совпадает с днём на машине.
- на стенде: пакетный день доехал до stg.hits_raw_dist, счёт по
Distributed сошёлся — отправлено 50626, в таблице 50626.
- топик прочитан обеими нодами: clickhouse-01 раздел 0 (26368),
clickhouse-02 раздел 1 (24258).
- живой день: модельное время 01:00 на 60-й секунде, 02:00 на 120-й —
темп ×60, лаг печатается.
- форма на проводе в колонке raw: даты читаются глазами, ecommerce лежит
строкой.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Генератор кликстрима
Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения — спека «Генератор (этап 2)».
События уже есть и уже уезжают: день-функция отдаёт по паре (зерно, D) упорядоченный поток трёх видов — просмотр страницы, корзина, покупка, — канонический сериализатор превращает его в JSON, а проигрыватель гонит в файл или в Kafka. Клиентская сторона на этом целая; заказы бэкенда — за следующими этапами.
Как это работает
Раздел черновой. По сути он верен, но на понятность читателем со стороны не выверен: пишет его тот, кто держит устройство генератора в голове, а это худший судья понятности. Выверка — вместе с путеводителем, тикет #48.
Цепочка одна и всегда та же: корневое зерно → подпотоки по позиции в дереве → когорта дня (кто впервые пришёл, сколько раз вернётся, чей паспорт какой) → аудитория дня, то есть когорта плюс возвраты когорт окна → визиты этих кук → строки событий. Мир при этом ленив: когорта считается по требованию, а до D0 живёт предыстория, поэтому любой день собирается сам по себе — прожитая история для него не нужна и на него не влияет.
Главное правило для того, кто придёт следующим: внутри подпотока порядок
бросков — часть контракта. Броски раздаёт один генератор подряд, и k-й
бросок достаётся тому, кто спросил k-м. Приписать новый бросок в конец
функции безопасно: у прежних он ничего не отнимает. Вставить в середину —
значит сдвинуть все броски после него, а с ними и весь мир: события того же
дня станут другими, счётчики канонического мира разойдутся с манифестом, и
поймается это не ошибкой, а красным чеком. Ровно поэтому паспорта кук в
plan.cohort бросаются последними.
Случайность целочисленная — только диапазоны и выбор по целым весам: готовые
распределения numpy расходятся между версиями и архитектурами, а обещано
побайтовое совпадение (спека, раздел 2). Отсюда weights.py вместо
rng.choice с вероятностями.
Что где лежит
src/clickstream_generator/world.py— конфигурация мира: все его числа одним местом. Правка любого — смена мира; крутить их и предлагается.src/clickstream_generator/seeds.py— иерархия зёрен: кто из какого подпотока берёт случайность. На ней держится весь детерминизм.src/clickstream_generator/plan.py— план состава: кто есть в мире в день D. Когорты, приток, двухкуковые пары, паспорта кук и счётчики — до генерации событий.src/clickstream_generator/weights.py— выбор по целым весам: один приём на весь генератор, чтобы дисциплина целочисленной случайности не жила копиями.src/clickstream_generator/reference.py— справочники: устройства, города, источники трафика, карта сайта. Таблицы-литералы: доля живёт в строке, которой принадлежит.src/clickstream_generator/catalog.py— каталог товаров изdata/catalog/products.csv, общего у генератора и словаря ClickHouse.src/clickstream_generator/day.py— день-функция: визиты, страницы, атрибуция, устройство и гео. Там же правила резки визитов и шов, на который садятся торговые события.src/clickstream_generator/commerce.py— торговые события: что легло в корзину, что из этого куплено, деньги, номера заказов и сыройecommerce. Своя случайность, поэтому правка торговли трафик не двигает.src/clickstream_generator/ids.py— номера событий: неповторяющиеся и ниже 2^53. Обещание одно на обе половины дня, поэтому и живёт отдельно.src/clickstream_generator/serialize.py— канонический сериализатор: единственное место, где событие целиком превращается в JSON. Порядок ключей, все 47 колонок всегда и форма на проводе — ISO-8601.src/clickstream_generator/sinks.py— приёмники: файл (одно событие — одна строка) и Kafka (одно событие — одно сообщение). Про содержимое они не знают; там же довод, почему у сообщения нет ключа.src/clickstream_generator/player.py— проигрыватель: гонит дни в приёмник пачкой или с темпом живого дня. Состояния не хранит.src/clickstream_generator/cli.py— интерфейс запуска: параметры аргументами или окружением, логи в стандартный вывод, итог кодом возврата.src/clickstream_generator/schema.py— контракт схемы: чистые данные о колонках выгрузки. Собственность генератора; из него выводятся сам генератор, его валидация и описание выгрузки в доках.src/clickstream_generator/schema_doc.py— сборка «описания выгрузки» (docs/formats/clickstream-event.md) из контракта. Документ руками не правят — пересобирают.tests/— инварианты контракта, свежесть описания и обещания мира: чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны и сборка визитов по задокументированным правилам. Там же побайтовое обещание, доведённое до диска: два прогона дня в файл дают тот же файл, а строк в нём ровно столько, сколько событий.
Команды
Проиграть день — быстрый старт и --help.
Из корня репозитория:
make test— тесты генератора;make lint— ruff: проверка и формат;make typecheck— ty: проверка типов;make docs— пересобрать описание выгрузки.
Python и зависимости — через uv, версии закреплены в uv.lock: на этом
держится обещание побайтовой воспроизводимости (спека, раздел 2).