ddadminandDmitry Dementiev
731d991f94
- Зачем:
- ревью rev5: ClickHouse-интеграция была проблемной (порт 9000 native vs HTTP,
неработающий fallback, отсутствие DDL для базы meta)
- архитектурно чище: генератор остаётся pure Kafka producer,
история доступна для аналитики через стандартный ingestion
- Что:
- удален ClickHouseBatchHistory, clickhouse-connect зависимость
- добавлен KafkaBatchHistory с записью в топик generator_batch_history
- добавлен BatchRecord.to_dict() для JSON-сериализации
- добавлен рабочий fallback: Kafka → InMemory при недоступности
- удален pytest-asyncio (не использовался)
- добавлены тесты test_kafka_history.py (15 тестов) и test_service.py (6 тестов)
- обновлена документация: топик вместо таблицы ClickHouse
- Проверка:
- make generator-test: 44/44 тестов пройдено
- docker-compose валиден, генератор не зависит от clickhouse
151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# Генератор событий (MVP rev5)
|
|
|
|
Автономный генератор событий для Kafka с режимом `steady-stream`.
|
|
|
|
## Архитектура
|
|
|
|
```
|
|
generator-service -> Kafka topics -> (потребители отдельно)
|
|
```
|
|
|
|
Генератор работает автономно и не зависит от потребителей (Airflow, ClickHouse).
|
|
|
|
## Режим работы: `steady-stream`
|
|
|
|
- Публикуем постепенно, **короткими тиками** (по умолчанию каждые 5 секунд)
|
|
- На каждом тике отправляем небольшую порцию сообщений
|
|
- Держим целевую интенсивность `events/min` без крупных минутных batch
|
|
- Распределяем события по 4 топикам:
|
|
- `browser_events`
|
|
- `location_events`
|
|
- `device_events`
|
|
- `geo_events`
|
|
- Сохраняем связи `event_id <-> location`, `click_id <-> device/geo`
|
|
|
|
## Конфигурация (env)
|
|
|
|
| Переменная | Описание | По умолчанию |
|
|
|------------|----------|--------------|
|
|
| `KAFKA_BOOTSTRAP_SERVERS` | Адрес Kafka | `kafka:29092` |
|
|
| `GEN_TICK_SECONDS` | Интервал между тиками | `5` (1-10 сек рекомендуется) |
|
|
| `GEN_LAMBDA_BASE_PER_MIN` | Базовая интенсивность (событий/мин) | `200` |
|
|
| `GEN_JITTER_PCT` | Процент вариативности | `20` |
|
|
| `GEN_MIN_EVENTS_PER_TICK` | Минимум событий за тик | `5` |
|
|
| `GEN_MAX_EVENTS_PER_TICK` | Максимум событий за тик | `50` |
|
|
| `GEN_DATA_DIR` | Путь к JSONL файлам | `/data` |
|
|
| `GEN_SEED` | Сид для воспроизводимости | — |
|
|
| `GEN_ENABLED` | Включить генерацию | `true` |
|
|
| `GEN_METRICS_PORT` | Порт для Prometheus | `9109` |
|
|
|
|
### Режим "раз в минуту" (для демо)
|
|
|
|
Для контролируемых демо можно установить:
|
|
```bash
|
|
GEN_TICK_SECONDS=60
|
|
GEN_MIN_EVENTS_PER_TICK=50
|
|
GEN_MAX_EVENTS_PER_TICK=500
|
|
```
|
|
|
|
## Управление через Makefile
|
|
|
|
```bash
|
|
# Запустить только генератор
|
|
make generator-up
|
|
|
|
# Остановить генератор
|
|
make generator-down
|
|
|
|
# Смотреть логи
|
|
make generator-logs
|
|
|
|
# Перезапуск с пересборкой
|
|
make generator-restart
|
|
|
|
# Запуск тестов
|
|
make generator-test
|
|
```
|
|
|
|
## Метрики Prometheus
|
|
|
|
Генератор экспортирует метрики на `:9109/metrics`:
|
|
|
|
| Метрика | Тип | Описание |
|
|
|---------|-----|----------|
|
|
| `generator_events_total` | Counter | Всего отправлено событий (по топикам) |
|
|
| `generator_publish_errors_total` | Counter | Ошибки публикации (по топикам) |
|
|
| `generator_tick_duration_seconds` | Histogram | Длительность тика |
|
|
| `generator_last_success_timestamp` | Gauge | Время последнего успешного тика |
|
|
|
|
### Проверка метрик
|
|
|
|
```bash
|
|
curl http://localhost:9109/metrics
|
|
curl http://localhost:9090/api/v1/targets | grep generator
|
|
```
|
|
|
|
## История batch
|
|
|
|
История пишется в Kafka-топик `generator_batch_history` (JSON). При недоступности Kafka используется in-memory fallback (последние 1000 записей).
|
|
|
|
Поля сообщения:
|
|
- `batch_id` — идентификатор батча
|
|
- `started_at` / `finished_at` — время начала/окончания (ISO format)
|
|
- `sent_total` — всего отправлено
|
|
- `sent_browser/location/device/geo` — по топикам
|
|
- `status` — success/partial/error
|
|
- `error_message` — описание ошибки (если есть)
|
|
|
|
### Чтение истории из Kafka
|
|
|
|
```bash
|
|
docker compose exec kafka /opt/kafka/bin/kafka-console-consumer.sh \
|
|
--bootstrap-server kafka:29092 \
|
|
--topic generator_batch_history \
|
|
--from-beginning
|
|
```
|
|
|
|
## Тестирование
|
|
|
|
Тесты написаны на **pytest**.
|
|
|
|
### Запуск тестов
|
|
|
|
```bash
|
|
# Через Makefile (рекомендуется)
|
|
make generator-test
|
|
|
|
# Вручную через Docker
|
|
docker build -t generator:test .
|
|
docker run --rm -v $(PWD):/workspace -w /workspace/generator generator:test pytest tests/ -v
|
|
|
|
# Конкретный файл тестов
|
|
docker run --rm -v $(PWD):/workspace -w /workspace/generator generator:test pytest tests/test_generation.py -v
|
|
```
|
|
|
|
### Структура тестов
|
|
|
|
```
|
|
generator/tests/
|
|
├── conftest.py # Fixtures pytest
|
|
├── test_config.py # Тесты конфигурации
|
|
├── test_generation.py # Тесты генерации событий
|
|
└── test_history.py # Тесты истории батчей
|
|
```
|
|
|
|
### Интеграционный тест
|
|
|
|
```bash
|
|
# Запустить стек с генератором
|
|
make generator-up
|
|
|
|
# Проверить логи
|
|
make generator-logs
|
|
|
|
# Проверить метрики
|
|
curl http://localhost:9109/metrics
|
|
|
|
# Проверить сообщения в Kafka
|
|
docker compose exec kafka /opt/kafka/bin/kafka-console-consumer.sh \
|
|
--bootstrap-server kafka:29092 --topic browser_events --from-beginning
|
|
```
|