Distributed Event-Driven Analytics Engine

Производственная, высокопроизводительная распределённая система аналитики, построенная на FastAPI, Kafka, Redis и ClickHouse.
Проект демонстрирует принципы Clean Architecture, современные асинхронные паттерны Python и уровень observability, характерный для enterprise-систем.

Обзор архитектуры

Система построена в соответствии с принципами Clean Architecture и имеет чёткое разделение ответственности между слоями:

┌─────────────────────────────────────────────────────────────┐
│                     API Layer (FastAPI)                      │
│  ┌──────────────┐              ┌──────────────┐            │
│  │   Ingestor   │              │   Processor  │            │
│  │   Service    │              │   Service    │            │
│  └──────┬───────┘              └──────┬───────┘            │
└─────────┼──────────────────────────────┼────────────────────┘
│                              │
┌─────────┼──────────────────────────────┼────────────────────┐
│         │  Application Layer           │                    │
│         │  ┌────────────────────────┐  │                    │
│         │  │  IngestService         │  │                    │
│         │  │  ProcessService        │  │                    │
│         │  └────────────────────────┘  │                    │
└─────────┼──────────────────────────────┼────────────────────┘
│                              │
┌─────────┼──────────────────────────────┼────────────────────┐
│         │  Domain Layer                │                    │
│         │  ┌────────────────────────┐  │                    │
│         │  │  TelemetryEvent        │  │                    │
│         │  │  ProcessedEvent        │  │                    │
│         │  │  Interfaces (Ports)    │  │                    │
│         │  └────────────────────────┘  │                    │
└─────────┼──────────────────────────────┼────────────────────┘
│                              │
┌─────────┼──────────────────────────────┼────────────────────┐
│         │  Infrastructure Layer        │                    │
│         ▼                              ▼                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐            │
│  │  Kafka   │  │  Redis   │  │  ClickHouse  │            │
│  └──────────┘  └──────────┘  └──────────────┘            │
└─────────────────────────────────────────────────────────────┘

Ключевые возможности

1. Ingestor Service

• Высокопроизводительный FastAPI-endpoint для приёма телеметрии
• Валидация данных с помощью Pydantic v2
• Kafka-producer с retry-логикой и обработкой ошибок
• Rate limiting (по умолчанию 10 000 запросов в минуту)
• Middleware для логирования запросов
• Поддержка batch-ингеста
• Prometheus-метрики для мониторинга

2. Processor Service

• Асинхронный Kafka-consumer с пакетной обработкой сообщений
• Агрегация «горячих» метрик в Redis (скользящие окна по 5 минут)
• Хранение аналитических данных в ClickHouse (OLAP)
• Dead Letter Queue (DLQ) для событий с ошибками
• Retry-механизмы с экспоненциальной задержкой
• Корректное завершение работы (graceful shutdown) с использованием TaskGroups (Python 3.12)
• Метрики обработки для Prometheus

3. Надёжность

• Retry-механизмы для Kafka, Redis и ClickHouse
• Dead Letter Queue для необрабатываемых событий
• Пуллинг соединений и корректное освобождение ресурсов
• Поддержка graceful shutdown

4. Наблюдаемость (Observability)

• Метрики Prometheus (/metrics)
• Структурированное логирование с настраиваемыми уровнями
• Health-check эндпоинты (/health)
• Отслеживание задержек ingestion и processing

Технологический стек

• Framework: FastAPI (Async)
• Message Broker: Apache Kafka (aiokafka)
• Cache: Redis
• Analytics DB: ClickHouse
• Validation: Pydantic v2
• Monitoring: Prometheus
• Containerization: Docker, Docker Compose
• Python: 3.12+

Структура проекта

distributed-event-driven-analytics-engine/
├── core/
│   ├── domain/
│   │   ├── models.py
│   │   └── interfaces.py
│   ├── application/
│   │   └── services.py
│   └── infrastructure/
│       ├── kafka_producer.py
│       ├── kafka_consumer.py
│       ├── redis_repository.py
│       ├── clickhouse_repository.py
│       └── dlq.py
├── services/
│   ├── ingestor/
│   │   └── main.py
│   └── processor/
│       └── main.py
├── infra/
│   ├── clickhouse/
│   │   └── init.sql
│   └── prometheus/
│       └── prometheus.yml
├── docker-compose.yml
├── Dockerfile.ingestor
├── Dockerfile.processor
├── requirements.txt
└── README.md

Быстрый старт

Требования

• Docker и Docker Compose
• (Опционально) Python 3.12+ для локальной разработки

Запуск системы

docker-compose up -d

Будут запущены:

• Zookeeper (2181)
• Kafka (9092, 9093)
• Redis (6379)
• ClickHouse (8123, 9000)
• Ingestor Service (8000)
• Processor Service (8001)
• Prometheus (9090)

Проверка состояния:

curl http://localhost:8000/health
curl http://localhost:8001/health

Масштабирование

Горизонтальное масштабирование

• Ingestor — stateless, масштабируется за load balancer’ом
• Processor — consumer group Kafka
• Kafka — увеличение числа партиций и брокеров
• Redis — Redis Cluster
• ClickHouse — кластеризация и партиционирование по времени

Вертикальное масштабирование

• Настройка CPU и RAM контейнеров
• Оптимизация batch-размеров Kafka
• Тюнинг Redis и ClickHouse

Поток данных

1. Клиент отправляет событие → Ingestor
2. Валидация → Kafka topic
3. Processor читает batch
4. Агрегация в Redis
5. Запись в ClickHouse
6. Commit offset
7. Ошибки → DLQ

Преимущества Clean Architecture

• Инверсия зависимостей
• Высокая тестируемость
• Гибкость инфраструктуры
• Простота сопровождения
• Независимое масштабирование сервисов

Production-аспекты

• Аутентификация и авторизация API
• TLS для Kafka и БД
• Distributed tracing (OpenTelemetry)
• Grafana + алерты
• Replication для Kafka, Redis и ClickHouse

• или адаптировать текст под open-source репозиторий