Мониторинг логов Kafka с помощью ClickStack

Кратко

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

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

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

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

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

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

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

# Default locations
ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
ls /var/log/kafka/        # RPM/DEB package installations

Основные лог-файлы 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 — файловый appender отсутствует, поэтому логи записываются только в stdout. Чтобы использовать приёмник filelog, необходимо перенаправить логи в файл: добавив файловый appender в log4j.properties или перенаправив stdout через pipe (например, | tee /var/log/kafka/server.log).

Создание пользовательской конфигурации 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  # optional, only exists if log4j is configured with separate file appenders
      - /var/log/kafka/state-change.log  # optional, same as above
    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 гарантирует, что stack trace захватывается как одна запись лога.
• Эта конфигурация использует start_at: beginning, чтобы при запуске коллектора читать все существующие логи. Для развертываний в режиме промышленной эксплуатации измените значение на start_at: end, чтобы избежать повторного приёма логов при перезапусках коллектора.

Настройка 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 Image)

Если вы используете 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) и соблюдайте принцип минимальных привилегий.

Проверка логов в HyperDX

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

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

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

Загрузите образец датасета

Загрузите образец файла логов:

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

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

Создайте файл с именем 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

Запустите 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. Откройте HyperDX и перейдите в раздел Dashboards.
2. Нажмите "Import Dashboard" в правом верхнем углу в меню с многоточием.

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

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

Для демо-набора данных установите временной диапазон, включающий 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.

Следующие шаги

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

Переход к промышленной эксплуатации

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