Log Aggregator

Сервис для сбора логов от микросервисов, буферизации и пакетной записи в ClickHouse. Обеспечивает высокую пропускную способность, Graceful Shutdown и мониторинг через Prometheus.

Основные возможности

• Приём логов по HTTP (POST /log) в формате JSON.
• Асинхронная буферизация: логи складываются в канал, не блокируя клиента.
• Пакетная запись в ClickHouse (с возможностью переключения на stdout для разработки).
• Настраиваемое количество воркеров для параллельного флаша батчей.
• Graceful Shutdown: корректное завершение с дофлашиванием всех накопленных логов.
• Метрики в формате Prometheus (принято, переполнение канала, размер батча, длительность флаша).
• Полностью конфигурируется через переменные окружения (12‑factor).

Архитектура

• HTTP-хендлер принимает логи, валидирует их и отправляет в буферизированный канал. Если канал переполнен – возвращает 503 Service Unavailable и увеличивает счётчик logs_channel_overflow_total.
• Пул воркеров (количество задаётся через BATCH_COUNT) читает из канала, накапливает батчи до BATCH_SIZE или по таймеру FLUSH_INTERVAL.
• Flusher выполняет вставку в ClickHouse (или stdout) и записывает метрики времени и размера батча.
• Graceful Shutdown останавливает приём новых запросов, закрывает канал и дожидается завершения всех воркеров.
• Prometheus собирает метрики с эндпоинта /metrics.

Технологии

• Go 1.22+
• ClickHouse (в качестве хранилища логов)
• Prometheus (мониторинг)
• Docker & Docker Compose

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

1. Клонируйте репозиторий

git clone https://github.com/your-username/log-aggregator.git
cd log-aggregator

2. Запустите все сервисы

docker-compose up -d

Будут подняты:

• log-aggregator – сервис на порту 8080
• clickhouse – на портах 9000 (нативный) и 8123 (HTTP)
• prometheus – на порту 9090

3. Отправьте тестовый лог

curl -X POST http://localhost:8080/log \
  -H "Content-Type: application/json" \
  -d '{"message":"hello world","level":"info","service":"test","timestamp":"2026-07-14T12:00:00Z"}'

4. Проверьте метрики

curl http://localhost:8080/metrics | grep logs

Или откройте Prometheus: http://localhost:9090

5. Посмотрите данные в ClickHouse

docker exec -it clickhouse clickhouse-client --query "SELECT * FROM logs.logs LIMIT 5"

Конфигурация

Все настройки задаются через переменные окружения (файл .env или передача в контейнер).

Переменная	Описание	Значение по умолчанию
HTTP_PORT	Порт HTTP-сервера	8080
BATCH_SIZE	Количество записей в одном батче	10000
BATCH_COUNT	Количество параллельных воркеров для флаша	1
FLUSH_INTERVAL	Интервал принудительного сброса (секунды)	5
CHANNEL_SIZE	Размер буфера канала (макс. логов в очереди)	100000
SHUTDOWN_TIMEOUT	Таймаут для graceful shutdown (секунды)	10
MAX_LOG_SIZE_BYTES	Максимальный размер тела запроса (байты)	1048576 (1 МБ)
CLICKHOUSE_ADDR	Адрес ClickHouse (например, clickhouse:9000)	(пусто, stdout-режим)
CLICKHOUSE_DB	Имя базы данных	default
CLICKHOUSE_USER	Пользователь	default
CLICKHOUSE_PASS	Пароль	(пусто)

Пример .env:

HTTP_PORT=8080
BATCH_SIZE=10000
BATCH_COUNT=2
FLUSH_INTERVAL=5
CHANNEL_SIZE=100000
SHUTDOWN_TIMEOUT=10
MAX_LOG_SIZE_BYTES=1048576
CLICKHOUSE_ADDR=clickhouse:9000
CLICKHOUSE_DB=logs
CLICKHOUSE_USER=default
CLICKHOUSE_PASS=

Мониторинг

Сервис предоставляет эндпоинт /metrics с метриками в формате Prometheus:

• logs_received_total – общее количество принятых логов.

• logs_channel_overflow_total – сколько раз канал был переполнен (и возвращён 503).

• batch_size – гистограмма размера отправленных батчей.

• flush_duration_seconds – гистограмма времени выполнения флаша.

Эти метрики можно собирать в Prometheus и визуализировать в Grafana.

Нагрузочное тестирование

В папке loadtest/ находится инструмент для отправки большого количества запросов.

Запуск:

go run loadtest/main.go -n 1000000 -c 200 -url http://localhost:8080/log -service loadtest

Параметры:

• -n – общее количество запросов.
• -c – количество параллельных воркеров.
• -url – эндпоинт сервиса.
• -service – имя сервиса, передаваемое в каждом логе.
• -interval – задержка между запросами (например, 1ms).

Результаты теста выводятся в консоль: успешные запросы, ошибки, RPS.

Разработка и сборка

Локальный запуск без Docker

# Установите переменные окружения (например, через .env)
export HTTP_PORT=8080
export CLICKHOUSE_ADDR=localhost:9000
# ... остальные переменные

go run cmd/server/main.go

Сборка Docker-образа

docker build -t log-aggregator .

Лицензия

MIT

Автор

@Reactivity512

Контакты

Если у вас есть вопросы или предложения – создавайте Issue или пишите на почту.