Supervision des métriques Kafka avec ClickStack

Intégration avec un déploiement Kafka existant

Surveillez votre déploiement Kafka existant en exécutant le conteneur OpenTelemetry JMX Metric Gatherer afin de collecter des métriques et de les envoyer à ClickStack via OTLP.

Si vous souhaitez d’abord tester cette intégration sans modifier votre configuration existante, passez à la section sur le jeu de données de démonstration.

Prérequis

Instance ClickStack en cours de fonctionnement
Installation existante de Kafka (version 2.0 ou plus récente) avec JMX activé
Accès réseau entre ClickStack et Kafka (port JMX 9999, port Kafka 9092)
JAR OpenTelemetry JMX Metric Gatherer (instructions de téléchargement ci-dessous)

Obtenir la clé API ClickStack

Le JMX Metric Gatherer envoie des données vers l’endpoint OTLP de ClickStack, qui nécessite une authentification.

Ouvrez HyperDX à l’URL de votre instance ClickStack (par exemple, http://localhost:8080)
Créez un compte ou connectez-vous si nécessaire
Accédez à Team Settings → API Keys
Copiez votre Ingestion API Key

Définissez-la comme variable d’environnement :

export CLICKSTACK_API_KEY=your-api-key-here

Téléchargez JMX Metric Gatherer pour OpenTelemetry

Téléchargez le fichier JAR de 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

Vérifiez que JMX est activé pour Kafka

Assurez-vous que JMX est activé sur vos brokers Kafka. Pour les déploiements Docker :

services:
  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      # ... other Kafka configuration
    ports:
      - "9092:9092"
      - "9999:9999"

Pour les déploiements sans Docker, définissez ces paramètres au démarrage de Kafka :

export JMX_PORT=9999

Vérifiez que JMX est accessible :

netstat -an | grep 9999

Déployer JMX Metric Gatherer avec Docker Compose

Cet exemple présente une configuration complète avec Kafka, JMX Metric Gatherer et ClickStack. Ajustez les noms des services et les endpoints pour qu’ils correspondent à votre déploiement existant :

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

Paramètres de configuration clés :

service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi - URL de connexion JMX (utilisez le hostname de votre instance Kafka)
otel.jmx.target.system=kafka - Active les metrics spécifiques à Kafka
http://clickstack:4318 - endpoint HTTP OTLP (utilisez le hostname de votre instance ClickStack)
authorization=\${CLICKSTACK_API_KEY} - API key pour l'authentification (obligatoire)
service.name=kafka,kafka.broker.id=broker-0 - resource attributes pour le filtrage
10000 - Intervalle de collecte en millisecondes (10 secondes)

Vérifier les métriques dans HyperDX

Connectez-vous à HyperDX et vérifiez que les métriques remontent bien :

Accédez à Chart Explorer
Recherchez kafka.message.count ou kafka.partition.count
Les métriques doivent apparaître toutes les 10 secondes

Métriques clés à vérifier :

kafka.message.count - Nombre total de messages traités
kafka.partition.count - Nombre total de partitions
kafka.partition.under_replicated - Doit être égal à 0 dans un cluster sain
kafka.network.io - Débit réseau
kafka.request.time.* - Percentiles de latence des requêtes

Pour générer de l'activité et faire remonter davantage de métriques :

# Create a test topic
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Send test messages
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"

Jeu de données de démonstration

Pour les utilisateurs qui souhaitent tester l’intégration Kafka Metrics avant de configurer leurs systèmes de production, nous fournissons un jeu de données pré-généré avec des schémas réalistes de métriques Kafka.

Télécharger l’exemple de jeu de données de métriques

Téléchargez les fichiers de métriques pré-générés (29 heures de métriques Kafka avec des schémas réalistes) :

# Télécharger les métriques gauge (nombre de partitions, tailles des files d’attente, latences, consumer lag)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-gauge.csv

# Télécharger les métriques sum (débits de messages, débits en octets, nombre de requêtes)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-sum.csv

Le jeu de données inclut des schémas réalistes pour un cluster Kafka e-commerce à un seul broker :

06:00-08:00: Pic matinal - Forte montée du trafic à partir du niveau nocturne de référence
10:00-10:15: Vente flash - Pic spectaculaire à 3,5 fois le trafic normal
11:30: Événement de déploiement - Pic de consumer lag multiplié par 12 avec des partitions sous-répliquées
14:00-15:30: Pic d’achats - Trafic soutenu à 2,8 fois le niveau de référence
17:00-17:30: Pic de fin de journée - Pic de trafic secondaire
18:45: Rééquilibrage du consumer - Pic de lag multiplié par 6 pendant le rééquilibrage
20:00-22:00: Baisse en soirée - Forte baisse jusqu’aux niveaux nocturnes

Démarrer ClickStack

Démarrez une instance ClickStack :

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

Charger les métriques dans ClickStack

Chargez les métriques directement dans ClickHouse :

# Charger les métriques gauge (nombre de partitions, tailles des files d’attente, latences, consumer lag)
cat kafka-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Charger les métriques sum (débits de messages, débits en octets, nombre de requêtes)
cat kafka-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Vérifier les métriques dans HyperDX

Une fois chargées, le moyen le plus rapide de visualiser vos métriques est d’utiliser le tableau de bord préconfiguré.

Rendez-vous dans la section Tableaux de bord et visualisation pour importer le tableau de bord et afficher toutes les métriques Kafka d’un seul coup.

Tableaux de bord et visualisations

Pour vous aider à démarrer la supervision de Kafka avec ClickStack, nous fournissons les visualisations essentielles pour les métriques Kafka.

Télécharger la configuration du tableau de bord

Télécharger le fichier de configuration du tableau de bord.

Importer le tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section Dashboards
Cliquez sur Import Dashboard dans l’angle supérieur droit, dans le menu à trois points

Téléversez le fichier kafka-metrics-dashboard.json, puis cliquez sur Finish Import

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations préconfigurées :

Dépannage

Aucune métrique ne s’affiche dans HyperDX

Vérifiez que la clé d’API est définie et transmise au conteneur :

# Check environment variable
echo $CLICKSTACK_API_KEY

# Verify it's in the container
docker exec <jmx-exporter-container> env | grep CLICKSTACK_API_KEY

S’il n’est pas défini, définissez-le et redémarrez :

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

Vérifiez si les métriques parviennent à ClickHouse :

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

Si vous ne voyez aucun résultat, vérifiez les logs du JMX exporter :

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

Générez de l’activité Kafka pour alimenter les métriques :

# Create a test topic
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Send test messages
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"

Erreurs d’authentification

Si vous voyez Authorization failed ou 401 Unauthorized :

Vérifiez la clé API dans l’interface utilisateur HyperDX (Paramètres → Clés API → Clé API d’ingestion)
Exportez-la de nouveau, puis redémarrez :

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

Conflits de ports avec les commandes du client Kafka

Lorsque vous exécutez des commandes Kafka depuis le conteneur Kafka, il se peut que le message suivant s’affiche :

Error: Port already in use: 9999

Faites précéder les commandes de unset JMX_PORT && :

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

Problèmes de connectivité réseau

Si les logs du JMX exporter indiquent Connection refused :

Vérifiez que tous les conteneurs se trouvent sur le même réseau Docker :

docker compose ps
docker network inspect <network-name>

Tester la connectivité :

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

Prochaines étapes

Configurez des alertes pour les métriques critiques (partitions sous-répliquées, hausse du consumer lag, pics de latence des requêtes)
Créez des tableaux de bord supplémentaires pour des cas d'utilisation spécifiques (débit par topic, surveillance des groupes de consommateurs)
Surveillez plusieurs brokers Kafka en ajoutant des instances JMX Metric Gatherer supplémentaires avec des attributs de ressource kafka.broker.id uniques

Passage en production

Ce guide envoie les métriques directement du JMX Metric Gatherer vers l’endpoint OTLP de ClickStack, ce qui convient bien aux tests et aux petits déploiements.

Pour les environnements de production, déployez votre propre OpenTelemetry Collector comme agent afin de recevoir les métriques du JMX Exporter et de les transmettre à ClickStack. Cela apporte le traitement par lots, la résilience et une gestion centralisée de la configuration.

Consultez Ingestion avec OpenTelemetry pour découvrir des modèles de déploiement en production et des exemples de configuration du collector.