Мониторинг журналов Kafka с ClickStack

Мониторинг журналов Kafka с ClickStack

Кратко

Собирайте и визуализируйте журналы Kafka broker в формате Log4j в ClickStack с помощью OTel-приёмника filelog. Включает демо-набор данных и преднастроенный дашборд.

​

Интеграция с существующей установкой Kafka

В этом разделе описано, как настроить существующую установку Kafka для отправки журналов брокера в ClickStack, изменив конфигурацию коллектора ClickStack OTel. Если вы хотите протестировать интеграцию журналов Kafka перед настройкой собственной среды, воспользуйтесь нашей предварительно настроенной средой и тестовыми данными из раздела “Демо-набор данных”.

​

Предварительные требования

• Запущенный экземпляр ClickStack
• Установленный Kafka версии 2.0 или новее
• Доступ к файлам журналов Kafka (server.log, controller.log и т. д.)

1. ​

   Проверьте конфигурацию логирования Kafka

   Kafka использует Log4j и записывает журналы в каталог, указанный в системном свойстве kafka.logs.dir или переменной окружения LOG_DIR. Проверьте расположение файла журнала:

   # Расположение по умолчанию
   ls $KAFKA_HOME/logs/      # Стандартный Apache Kafka (по умолчанию <install-dir>/logs/)
   ls /var/log/kafka/        # Установка из пакетов RPM/DEB
   

   Основные файлы журнала Kafka:

   • server.log: Общие журналы брокера (запуск, подключения, репликация, ошибки)
   • controller.log: События контроллера (выбор лидера, переназначение партиций)
   • state-change.log: Переходы состояний партиций и реплик

   Стандартный шаблон Log4j в Kafka создает строки вида:

   [2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)
   

   Для Kafka-развертываний на базе Docker (например, confluentinc/cp-kafka) конфигурация Log4j по умолчанию включает только консольный appender — file appender отсутствует, поэтому журналы записываются только в stdout. Чтобы использовать приёмник filelog, нужно перенаправить журналы в файл: либо добавив file appender в log4j.properties, либо перенаправив stdout через конвейер (например, | tee /var/log/kafka/server.log).

2. ​

   Создайте пользовательскую конфигурацию OTel collector для Kafka

   ClickStack позволяет расширить базовую конфигурацию OpenTelemetry Collector, подключив пользовательский файл конфигурации и задав переменную окружения. Пользовательская конфигурация объединяется с базовой конфигурацией, которой HyperDX управляет через OpAMP.

   Создайте файл с именем kafka-logs-monitoring.yaml со следующей конфигурацией:

   receivers:
     filelog/kafka:
       include:
         - /var/log/kafka/server.log
         - /var/log/kafka/controller.log  # необязательно, существует только если log4j настроен с отдельными файловыми аппендерами
         - /var/log/kafka/state-change.log  # необязательно, аналогично вышесказанному
       start_at: beginning
       multiline:
         line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
       operators:
         - type: regex_parser
           regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
           parse_from: body
           parse_to: attributes
           timestamp:
             parse_from: attributes.timestamp
             layout: '%Y-%m-%d %H:%M:%S,%L'
           severity:
             parse_from: attributes.severity
   
         - type: move
           from: attributes.message
           to: body
   
         - type: add
           field: attributes.source
           value: "kafka"
   
         - type: add
           field: resource["service.name"]
           value: "kafka-production"
   
   service:
     pipelines:
       logs/kafka:
         receivers: [filelog/kafka]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   

   • В пользовательской конфигурации вы определяете только новые приёмники и конвейеры. Процессоры (memory_limiter, transform, batch) и экспортеры (clickhouse) уже определены в базовой конфигурации ClickStack — здесь на них нужно только сослаться по имени.
   • Конфигурация multiline обеспечивает объединение трассировок стека в одну запись в журнале.
   • Эта конфигурация использует start_at: beginning, чтобы при запуске коллектора прочитать все существующие журналы. Для развертываний в продакшне измените значение на start_at: end, чтобы избежать повторного приёма журналов при перезапуске коллектора.
3. ​

   Настройка ClickStack для загрузки пользовательской конфигурации

   Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, необходимо:

   1. Смонтировать файл пользовательской конфигурации в /etc/otelcol-contrib/custom.config.yaml
   2. Задать переменную окружения CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
   3. Смонтировать каталог с журналами Kafka, чтобы коллектор мог их читать

   Docker Compose

   Обновите конфигурацию развертывания ClickStack:

   services:
     clickstack:
       # ... существующая конфигурация ...
       environment:
         - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
         # ... другие переменные окружения ...
       volumes:
         - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
         - /var/log/kafka:/var/log/kafka:ro
         # ... другие тома ...
   

   Docker Run (образ All-in-One)

   Если вы используете all-in-one image с Docker, выполните:

   docker run --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v /var/log/kafka:/var/log/kafka:ro \
     clickhouse/clickstack-all-in-one:latest
   

   Убедитесь, что у коллектора ClickStack есть необходимые разрешения на чтение файлов журналов Kafka. В продакшне используйте монтирования только для чтения (:ro) и придерживайтесь принципа наименьших привилегий.

4. ​

   Проверьте журналы в HyperDX

   После настройки войдите в HyperDX и убедитесь, что журналы поступают:

​

Демо-набор данных

Протестируйте интеграцию журналов Kafka на заранее подготовленном примере данных, прежде чем настраивать системы в продакшне.

1. ​

   Скачайте пример данных

   Скачайте пример файла журнала:

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log
   
2. ​

   Создайте тестовую конфигурацию коллектора

   Создайте файл kafka-logs-demo.yaml со следующей конфигурацией:

   cat > kafka-logs-demo.yaml << 'EOF'
   receivers:
     filelog/kafka:
       include:
         - /tmp/kafka-demo/server.log
       start_at: beginning
       multiline:
         line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
       operators:
         - type: regex_parser
           regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
           parse_from: body
           parse_to: attributes
           timestamp:
             parse_from: attributes.timestamp
             layout: '%Y-%m-%d %H:%M:%S,%L'
           severity:
             parse_from: attributes.severity
   
         - type: move
           from: attributes.message
           to: body
   
         - type: add
           field: attributes.source
           value: "kafka-demo"
   
         - type: add
           field: resource["service.name"]
           value: "kafka-demo"
   
   service:
     pipelines:
       logs/kafka-demo:
         receivers: [filelog/kafka]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   EOF
   
3. ​

   Запустите ClickStack с демо-конфигурацией

   Запустите ClickStack с демо-журналами и этой конфигурацией:

   docker run --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
     clickhouse/clickstack-all-in-one:latest
   

   ​

   Проверьте журналы в HyperDX

   После запуска ClickStack:

   1. Откройте HyperDX и войдите в свою учётную запись (возможно, сначала потребуется создать её)
   2. Перейдите в представление Search и выберите источник Logs
   3. Установите временной диапазон, включающий 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

​

Панели мониторинга и визуализация

1. ​

   конфигурацию панели мониторинга

2. ​

   Импорт преднастроенного дашборда

   1. Откройте HyperDX и перейдите в раздел Dashboards.
   2. Нажмите “Import Dashboard” в правом верхнем углу в меню с многоточием.

   3. Загрузите файл kafka-logs-dashboard.json и нажмите finish import.
3. ​

   Панель мониторинга будет создана со всеми преднастроенными визуализациями

   Для демо-набора данных установите временной диапазон, включающий 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

​

Устранение неполадок

Убедитесь, что фактическая конфигурация включает ваш приёмник filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Проверьте ошибки коллектора:

docker exec <container> cat /etc/otel/supervisor-data/agent.log

Проверьте, что формат логирования Kafka соответствует ожидаемому шаблону:

tail -1 /var/log/kafka/server.log

Если в вашей установке Kafka используется пользовательский шаблон Log4j, соответствующим образом настройте регулярное выражение для regex_parser.

​

Дальнейшие шаги

• Настройте оповещения для критически важных событий (сбои брокеров, ошибки репликации, проблемы consumer group)
• Используйте вместе с Kafka Metrics для комплексного мониторинга Kafka
• Создайте дополнительные панели мониторинга для конкретных сценариев использования (события контроллера, перераспределение партиций)

​

Переход в продакшн

В этом руководстве для быстрой настройки используется встроенный в ClickStack OpenTelemetry Collector. Для развертываний в продакшне мы рекомендуем запускать собственный OTel Collector и отправлять данные в конечную точку OTLP ClickStack. См. Отправка данных OpenTelemetry для настройки конфигурации продакшна.