Supervision des logs Kafka avec ClickStack

Intégration avec une installation Kafka existante

Cette section explique comment configurer votre installation Kafka existante pour envoyer les logs des brokers à ClickStack en modifiant la configuration du ClickStack OTel collector. Si vous souhaitez tester l’intégration des logs Kafka avant de configurer votre propre installation, vous pouvez utiliser notre configuration préconfigurée et les données d’exemple de la section "Jeu de données de démonstration".

Prérequis

Instance ClickStack en fonctionnement
Installation Kafka existante (version 2.0 ou ultérieure)
Accès aux fichiers journaux de Kafka (server.log, controller.log, etc.)

Vérifier la configuration de journalisation de Kafka

Kafka utilise Log4j et écrit les logs dans le répertoire indiqué par la propriété système kafka.logs.dir ou la variable d’environnement LOG_DIR. Vérifiez l’emplacement de votre fichier de logs :

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

Principaux fichiers de logs Kafka :

server.log : Logs généraux du broker (démarrage, connexions, réplication, erreurs)
controller.log : Événements propres au contrôleur (élection du leader, réattribution des partitions)
state-change.log : Transitions d’état des partitions et des répliques

Le format Log4j par défaut de Kafka génère des lignes comme :

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

Créez une configuration personnalisée de l’OTel collector pour Kafka

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement. Cette configuration personnalisée est fusionnée avec la configuration de base gérée par HyperDX via OpAMP.

Créez un fichier nommé kafka-logs-monitoring.yaml contenant la configuration suivante :

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

Configurer ClickStack pour charger une configuration personnalisée

Pour activer une configuration personnalisée du collector dans votre déploiement ClickStack existant, vous devez :

Monter le fichier de configuration personnalisé sur /etc/otelcol-contrib/custom.config.yaml
Définir la variable d'environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Monter votre répertoire de logs Kafka afin que le collector puisse les lire

Mettez à jour la configuration de votre déploiement ClickStack :

services:
  clickstack:
    # ... configuration existante ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... autres variables d'environnement ...
    volumes:
      - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/kafka:/var/log/kafka:ro
      # ... autres volumes ...

Si vous utilisez l'image tout-en-un avec Docker, exécutez :

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

Vérifier les logs dans HyperDX

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les logs sont bien ingérés :

Jeu de données de démonstration

Testez l’intégration des logs Kafka avec un jeu de données d’exemple pré-généré avant de configurer vos systèmes de production.

Télécharger le jeu de données d’exemple

Téléchargez le fichier de logs d’exemple :

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

Créer une configuration de collector de test

Créez un fichier nommé kafka-logs-demo.yaml avec la configuration suivante :

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

Exécuter ClickStack avec la configuration de démonstration

Exécutez ClickStack avec les logs de démonstration et cette configuration :

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

Vérifier les logs dans HyperDX

Une fois ClickStack démarré :

Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
Accédez à la vue Search et définissez la source sur Logs
Réglez l’intervalle de temps pour inclure 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

Tableaux de bord et visualisations

Télécharger la configuration du tableau de bord

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

Importer un tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section Dashboards.
Cliquez sur « Import Dashboard » en haut à droite, sous le menu à trois points.

Téléversez le fichier kafka-logs-dashboard.json, puis cliquez sur « Finish import ».

Finaliser l’importation du tableau de bord des logs Kafka

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

Pour le jeu de données de démonstration, définissez l’intervalle de temps de façon à inclure 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

Exemple de tableau de bord des logs Kafka

Résolution des problèmes

Vérifiez que la config effective inclut votre filelog receiver :

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

Vérifiez s’il y a des erreurs du collector :

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

Vérifiez que le format des logs de Kafka correspond au motif attendu :

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

Si votre installation Kafka utilise un format Log4j personnalisé, adaptez la regex de regex_parser en conséquence.

Prochaines étapes

Configurez des alertes pour les événements critiques (pannes de broker, erreurs de réplication, problèmes de groupe de consommateurs)
Combinez avec les métriques Kafka pour une supervision complète de Kafka
Créez des Dashboards supplémentaires pour des cas d’utilisation précis (événements du contrôleur, réaffectation des partitions)

Passage en production

Ce guide s'appuie sur l'OpenTelemetry Collector intégré à ClickStack pour une mise en place rapide. Pour les déploiements en production, nous recommandons d'exécuter votre propre OTel Collector et d'envoyer les données vers l'endpoint OTLP de ClickStack. Consultez Envoi de données OpenTelemetry pour la configuration de production.