Мониторинг метрик Kafka с помощью ClickStack

ВкратцеОтслеживайте метрики производительности Apache Kafka в ClickStack с помощью OTel JMX Metric Gatherer. Включает демо-набор данных и преднастроенную панель мониторинга.

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

Чтобы отслеживать существующее развертывание Kafka, запустите контейнер OpenTelemetry JMX Metric Gatherer для сбора метрик и отправки их в ClickStack через OTLP. Если вы хотите сначала протестировать эту интеграцию, не изменяя текущую конфигурацию, перейдите к разделу о демо-наборе данных.

Необходимые условия

Запущенный экземпляр ClickStack
Имеющаяся установка Kafka (версии 2.0 или выше) с включенным JMX
Сетевой доступ между ClickStack и Kafka (порт JMX 9999, порт Kafka 9092)
JAR-файл OpenTelemetry JMX Metric Gatherer (инструкции по загрузке ниже)

Получите ключ API ClickStack

JMX Metric Gatherer отправляет данные в конечную точку OTLP ClickStack, которая требует аутентификации.

Откройте HyperDX по адресу вашего ClickStack (например, http://localhost:8080)
Создайте учётную запись или войдите в систему при необходимости
Перейдите в Team Settings → API Keys
Скопируйте свой ключ API для приёма данных

Задайте его как переменную окружения:

export CLICKSTACK_API_KEY=your-api-key-here

Скачайте OpenTelemetry JMX Metric Gatherer

Скачайте JAR-файл JMX Metric Gatherer:

curl -L -o opentelemetry-jmx-metrics.jar \
  https://github.com/open-telemetry/opentelemetry-java-contrib/releases/download/v1.32.0/opentelemetry-jmx-metrics.jar

Убедитесь, что JMX в Kafka включен

Убедитесь, что JMX включен на ваших брокерах Kafka. Для Docker-развертываний:

services:
  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      # ... другие настройки Kafka
    ports:
      - "9092:9092"
      - "9999:9999"

Если вы используете развертывание не в Docker, задайте следующее при запуске Kafka:

export JMX_PORT=9999

Убедитесь, что JMX доступен:

netstat -an | grep 9999

Развертывание JMX Metric Gatherer с помощью Docker Compose

В этом примере показана полная конфигурация с Kafka, JMX Metric Gatherer и ClickStack. Измените имена сервисов и конечные точки в соответствии с существующим развертыванием:

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring

  kafka:
    image: confluentinc/cp-kafka:latest
    hostname: kafka
    container_name: kafka
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:9092'
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://kafka:9092,CONTROLLER://kafka:29093'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      KAFKA_JMX_OPTS: '-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=kafka -Dcom.sun.management.jmxremote.rmi.port=9999'
    ports:
      - "9092:9092"
      - "9999:9999"
    networks:
      - monitoring

  kafka-jmx-exporter:
    image: eclipse-temurin:11-jre
    depends_on:
      - kafka
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./opentelemetry-jmx-metrics.jar:/app/opentelemetry-jmx-metrics.jar
    command: >
      sh -c "java
      -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi
      -Dotel.jmx.target.system=kafka
      -Dotel.metrics.exporter=otlp
      -Dotel.exporter.otlp.protocol=http/protobuf
      -Dotel.exporter.otlp.endpoint=http://clickstack:4318
      -Dotel.exporter.otlp.headers=authorization=\${CLICKSTACK_API_KEY}
      -Dotel.resource.attributes=service.name=kafka,kafka.broker.id=broker-0
      -Dotel.jmx.interval.milliseconds=10000
      -jar /app/opentelemetry-jmx-metrics.jar"
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Ключевые параметры конфигурации:

service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi - URL JMX-подключения (используйте имя хоста Kafka)
otel.jmx.target.system=kafka - Включает метрики Kafka
http://clickstack:4318 - HTTP-конечная точка OTLP (используйте имя хоста ClickStack)
authorization=\${CLICKSTACK_API_KEY} - API key для аутентификации (обязательно)
service.name=kafka,kafka.broker.id=broker-0 - Атрибуты ресурса для фильтрации
10000 - Интервал сбора в миллисекундах (10 секунд)

Проверьте метрики в HyperDX

Войдите в HyperDX и убедитесь, что метрики поступают:

Перейдите в Chart Explorer
Найдите kafka.message.count или kafka.partition.count
Метрики должны появляться с интервалом 10 секунд

Ключевые метрики для проверки:

kafka.message.count - Общее количество обработанных сообщений
kafka.partition.count - Общее количество партиций
kafka.partition.under_replicated - В исправном кластере должно быть 0
kafka.network.io - Сетевая пропускная способность
kafka.request.time.* - Перцентили задержки запросов

Чтобы сгенерировать активность и получить больше метрик:

# Создать тестовый топик
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Отправить тестовые сообщения
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

При запуске команд клиента Kafka (kafka-topics, kafka-console-producer и т. д.) из контейнера Kafka добавляйте префикс unset JMX_PORT &&, чтобы избежать конфликтов JMX-портов.

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

Для пользователей, которые хотят протестировать интеграцию Kafka Metrics перед настройкой продакшен-систем, мы предоставляем заранее сгенерированный набор данных с реалистичной динамикой метрик Kafka.

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

Скачайте заранее сгенерированные файлы метрик (29 часов метрик Kafka с реалистичной динамикой):

# Скачайте gauge-метрики (количество партиций, размеры очередей, задержки, отставание потребителя)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-gauge.csv

# Скачайте sum-метрики (частота сообщений, скорость передачи байтов, количество запросов)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-sum.csv

Набор данных включает реалистичные паттерны для одноброкерного Kafka-кластера электронной коммерции:

06:00-08:00: Утренний всплеск - Резкий рост трафика от ночного базового уровня
10:00-10:15: Флеш-распродажа - Резкий скачок до 3.5x от обычного трафика
11:30: Событие развертывания - 12x всплеск отставания потребителя с недореплицированными партициями
14:00-15:30: Пик покупок - Стабильно высокий трафик на уровне 2.8x от базового
17:00-17:30: Всплеск после работы - Вторичный пик трафика
18:45: Перебалансировка потребителей - 6x всплеск отставания во время перебалансировки
20:00-22:00: Вечерний спад - Резкое снижение до ночных уровней

Запустите ClickStack

Запустите экземпляр ClickStack:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Загрузите метрики в ClickStack

Загрузите метрики напрямую в ClickHouse:

# Загрузите gauge-метрики (количество партиций, размеры очередей, задержки, отставание потребителя)
cat kafka-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Загрузите sum-метрики (частота сообщений, скорость передачи байтов, количество запросов)
cat kafka-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Проверьте метрики в HyperDX

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

Отображение часового поясаHyperDX отображает временные метки в локальном часовом поясе вашего браузера. Демо-данные охватывают 2025-11-05 16:00:00 - 2025-11-06 16:00:00 (UTC). Установите временной диапазон 2025-11-04 16:00:00 - 2025-11-07 16:00:00, чтобы гарантированно увидеть демо-метрики независимо от вашего местоположения. После этого можно сузить диапазон до 24 часов для более наглядных визуализаций.

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

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

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

Импортируйте преднастроенный дашборд

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

Загрузите файл kafka-metrics-dashboard.json и нажмите Finish Import

Откройте панель мониторинга

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

Для демо-набора данных установите временной диапазон 2025-11-05 16:00:00 - 2025-11-06 16:00:00 (UTC) (скорректируйте его в соответствии с вашим местным часовым поясом). По умолчанию у импортированной панели мониторинга временной диапазон не задан.

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

Метрики не отображаются в HyperDX

Проверьте, что ключ API задан и передаётся в контейнер:

# Проверить переменную окружения
echo $CLICKSTACK_API_KEY

# Убедиться, что она передана в контейнер
docker exec <jmx-exporter-container> env | grep CLICKSTACK_API_KEY

Если его нет, задайте его и перезапустите:

export CLICKSTACK_API_KEY=your-api-key-here
docker compose up -d kafka-jmx-exporter

Проверьте, поступают ли метрики в ClickHouse:

docker exec <clickstack-container> clickhouse-client --query "
SELECT DISTINCT MetricName 
FROM otel_metrics_sum 
WHERE ServiceName = 'kafka' 
LIMIT 10
"

Если результатов нет, проверьте журналы JMX exporter:

docker compose logs kafka-jmx-exporter | grep -i "error\|connection" | tail -10

Сгенерируйте активность в Kafka, чтобы появились метрики:

# Создать тестовый топик
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Отправить тестовые сообщения
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

Ошибки аутентификации

Если вы видите Authorization failed или 401 Unauthorized:

Проверьте ключ API в интерфейсе HyperDX (Settings → API Keys → Ingestion API Key)
Повторно экспортируйте переменные и перезапустите:

export CLICKSTACK_API_KEY=your-correct-api-key
docker compose down
docker compose up -d

Конфликт портов при выполнении команд клиента Kafka

При запуске команд Kafka из контейнера Kafka вы можете увидеть:

Error: Port already in use: 9999

Добавьте к командам префикс unset JMX_PORT &&:

docker exec kafka bash -c "unset JMX_PORT && kafka-topics --list --bootstrap-server kafka:9092"

Проблемы с подключением к сети

Если в журнале JMX exporter есть сообщение Connection refused: Убедитесь, что все контейнеры находятся в одной сети Docker:

docker compose ps
docker network inspect <network-name>

Проверьте подключение:

# От JMX exporter до ClickStack
docker exec <jmx-exporter-container> sh -c "timeout 2 bash -c 'cat < /dev/null > /dev/tcp/clickstack/4318' && echo 'Connected' || echo 'Failed'"

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

Настройте оповещения для критически важных метрик (партиции с недостаточной репликацией, рост отставания потребителя, всплески задержки запросов)
Создайте дополнительные панели мониторинга для конкретных сценариев использования (пропускная способность по топикам, мониторинг групп потребителей)
Отслеживайте несколько брокеров Kafka, добавив дополнительные экземпляры JMX Metric Gatherer с уникальными атрибутами ресурса kafka.broker.id

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

В этом руководстве метрики отправляются напрямую из JMX Metric Gatherer в конечную точку OTLP ClickStack, что хорошо подходит для тестирования и небольших развертываний. Для промышленной эксплуатации разверните собственный OpenTelemetry Collector в роли агента, чтобы он принимал метрики от JMX Exporter и пересылал их в ClickStack. Это обеспечивает пакетную обработку, отказоустойчивость и централизованное управление конфигурацией. См. Приём данных с помощью OpenTelemetry, где описаны схемы развертывания для промышленной эксплуатации и приведены примеры конфигурации OpenTelemetry Collector.

​Интеграция с существующим развертыванием Kafka

Необходимые условия

​Получите ключ API ClickStack

​Скачайте OpenTelemetry JMX Metric Gatherer

​Убедитесь, что JMX в Kafka включен

​Развертывание JMX Metric Gatherer с помощью Docker Compose

​Проверьте метрики в HyperDX

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

​Скачайте пример набора данных с метриками

​Запустите ClickStack

​Загрузите метрики в ClickStack

​Проверьте метрики в HyperDX

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

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

​Импортируйте преднастроенный дашборд

​Откройте панель мониторинга

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

​Метрики не отображаются в HyperDX

​Ошибки аутентификации

​Конфликт портов при выполнении команд клиента Kafka

​Проблемы с подключением к сети

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

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

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

Получите ключ API ClickStack

Скачайте OpenTelemetry JMX Metric Gatherer

Убедитесь, что JMX в Kafka включен

Развертывание JMX Metric Gatherer с помощью Docker Compose

Проверьте метрики в HyperDX

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

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

Запустите ClickStack

Загрузите метрики в ClickStack

Проверьте метрики в HyperDX

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

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

Импортируйте преднастроенный дашборд

Откройте панель мониторинга

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

Метрики не отображаются в HyperDX

Ошибки аутентификации

Конфликт портов при выполнении команд клиента Kafka

Проблемы с подключением к сети

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

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