Comprendre les outils en ligne de commande Kafka : Guide de référence CLI

Les outils en ligne de commande de Kafka sont le moyen le plus rapide de répondre aux questions opérationnelles de base : ce sujet existe-t-il, quel broker dirige cette partition, que contient le sujet, pourquoi ce groupe de consommateurs est-il en retard, et ce client peut-il s'authentifier auprès du cluster ? Vous n'en avez pas besoin pour chaque tâche, et la plupart des modifications en production devraient toujours passer par l'automatisation, mais lors d'un déploiement défaillant ou d'une question de données tardive, la CLI est souvent le chemin le plus court vers les faits.

Les exemples ci-dessous supposent que les scripts sont dans votre PATH. Dans de nombreuses installations, ils se trouvent sous le répertoire bin/ de Kafka, donc la même commande peut être exécutée sous la forme bin/kafka-topics.sh. Pour les clusters sécurisés, la plupart des commandes nécessitent également --command-config client.properties, où ce fichier contient les paramètres SASL, SSL et autres paramètres client.

Outils CLI Kafka de base

Les distributions Kafka incluent généralement un répertoire bin/ contenant divers scripts et exécutables. Nous nous concentrerons sur les plus fréquemment utilisés pour gérer Kafka efficacement.

1. kafka-topics.sh

C'est sans doute l'outil en ligne de commande le plus fréquemment utilisé. Il vous permet de créer, lister, décrire, supprimer, modifier et gérer les sujets Kafka. La gestion des sujets est fondamentale pour organiser les flux de données dans Kafka.

Sous-commandes et arguments courants :

• --create : Crée un nouveau sujet.
• --list : Liste tous les sujets du cluster.
• --describe : Fournit des informations détaillées sur des sujets spécifiques.
• --delete : Supprime un ou plusieurs sujets.
• --alter : Modifie la configuration d'un sujet existant.
• --topic <nom_du_sujet> : Spécifie le nom du sujet.
• --partitions <nombre_de_partitions> : Définit le nombre de partitions pour un sujet (utilisé avec --create).
• --replication-factor <facteur> : Définit le facteur de réplication pour un sujet (utilisé avec --create).
• --bootstrap-server <hôte:port> : Spécifie le broker Kafka auquel se connecter.

Exemples :

• Créer un sujet nommé mon_sujet avec 3 partitions et un facteur de réplication de 2 :

  kafka-topics.sh --create --topic mon_sujet --partitions 3 --replication-factor 2 --bootstrap-server kafka-broker-1:9092,kafka-broker-2:9092
  

• Lister tous les sujets du cluster :

  kafka-topics.sh --list --bootstrap-server kafka-broker-1:9092
  

• Décrire un sujet nommé mon_sujet :

  kafka-topics.sh --describe --topic mon_sujet --bootstrap-server kafka-broker-1:9092
  

  Cela affichera des détails comme les partitions, le leader, les réplicas et les ISR (réplicas en synchronisation).

• Supprimer un sujet nommé ancien_sujet :

  kafka-topics.sh --delete --topic ancien_sujet --bootstrap-server kafka-broker-1:9092
  

  Remarque : La suppression de sujet doit être activée dans les configurations du broker Kafka (delete.topic.enable=true).

2. kafka-console-producer.sh

Cet outil vous permet d'envoyer des messages vers un sujet Kafka à partir de l'entrée standard. Il est inestimable pour tester les producteurs, injecter des données d'exemple ou publier manuellement des messages.

Arguments courants :

• --topic <nom_du_sujet> : Spécifie le sujet cible.
• --bootstrap-server <hôte:port> : Spécifie le broker Kafka auquel se connecter.
• --property <clé>=<valeur> : Permet de définir des propriétés de producteur (par exemple, key.serializer, value.serializer).
• --producer-property <clé>=<valeur> : Similaire à --property, mais spécifiquement pour les configurations côté producteur.

Exemples :

• Envoyer des messages vers mon_sujet :

  kafka-console-producer.sh --topic mon_sujet --bootstrap-server kafka-broker-1:9092
  

  Après avoir exécuté cette commande, vous pouvez taper des messages ligne par ligne. Appuyez sur Ctrl+C pour quitter.

• Envoyer des messages avec des clés (format JSON) :

  kafka-console-producer.sh --topic mon_sujet --bootstrap-server kafka-broker-1:9092 --property parse.key=true --property key.separator=':'
  

  Vous pouvez maintenant taper des paires clé:valeur, et Kafka les enverra avec la clé spécifiée.

3. kafka-console-consumer.sh

Cet outil s'abonne à un ou plusieurs sujets Kafka et imprime les messages qu'il reçoit sur la sortie standard. Il est essentiel pour tester les consommateurs, inspecter les données dans les sujets et déboguer les applications producteur/consommateur.

Arguments courants :

• --topic <nom_du_sujet> : Spécifie le(s) sujet(s) à consommer.
• --bootstrap-server <hôte:port> : Spécifie le broker Kafka auquel se connecter.
• --group-id <id_du_groupe> : Spécifie l'ID du groupe de consommateurs. Ceci est important pour gérer les offsets et permettre à plusieurs consommateurs de partager la charge de consommation.
• --from-beginning : Lit les messages depuis le début du journal du sujet.
• --offset <offset> : Commence la consommation à partir d'un offset spécifique.
• --partition <id_de_la_partition> : Consomme à partir d'une partition spécifique.
• --property <clé>=<valeur> : Permet de définir des propriétés de consommateur (par exemple, value.deserializer).

Exemples :

• Consommer tous les messages de mon_sujet :

  kafka-console-consumer.sh --topic mon_sujet --bootstrap-server kafka-broker-1:9092
  

• Consommer les messages depuis le début de mon_sujet pour le groupe de consommateurs mon_groupe :

  kafka-console-consumer.sh --topic mon_sujet --group-id mon_groupe --from-beginning --bootstrap-server kafka-broker-1:9092
  

• Consommer des messages avec les offsets et les clés imprimés :

  kafka-console-consumer.sh --topic mon_sujet --bootstrap-server kafka-broker-1:9092 --property print.key=true --property key.separator="\t" --property print.offset=true --property print.headers=true
  

4. kafka-consumer-groups.sh

Cet outil est utilisé pour gérer et inspecter les groupes de consommateurs. Il est essentiel pour comprendre le retard des consommateurs, réaffecter les partitions et résoudre les problèmes de consommation.

Sous-commandes et arguments courants :

• --list : Liste tous les groupes de consommateurs du cluster.
• --describe : Fournit des détails sur des groupes de consommateurs spécifiques, y compris le retard.
• --bootstrap-server <hôte:port> : Spécifie le broker Kafka auquel se connecter.
• --group <id_du_groupe> : Spécifie l'ID du groupe de consommateurs.
• --reset-offsets : Réinitialise les offsets pour un groupe de consommateurs.
• --topic <nom_du_sujet> : Spécifie le sujet pour la réinitialisation des offsets.
• --to-earliest : Réinitialise les offsets au message le plus ancien disponible.
• --to-latest : Réinitialise les offsets au message le plus récent disponible.
• --execute : Exécute l'opération de réinitialisation des offsets.

Exemples :

• Lister tous les groupes de consommateurs :

  kafka-consumer-groups.sh --list --bootstrap-server kafka-broker-1:9092
  

• Décrire un groupe de consommateurs mon_groupe et afficher son retard :

  kafka-consumer-groups.sh --describe --group mon_groupe --bootstrap-server kafka-broker-1:9092
  

  La sortie affichera le sujet, la partition, l'offset actuel, l'offset de fin de journal et le retard.

• Réinitialiser les offsets pour mon_groupe sur mon_sujet au message le plus ancien disponible :

  kafka-consumer-groups.sh --group mon_groupe --topic mon_sujet --reset-offsets --to-earliest --execute --bootstrap-server kafka-broker-1:9092
  

  Utilisez cette commande avec prudence, car elle affecte l'endroit où les consommateurs commenceront à lire.

5. kafka-log-dirs.sh

Cet outil permet d'inspecter les répertoires de journaux sur les brokers Kafka. Il peut être utile pour comprendre l'utilisation du disque et localiser les données des sujets.

Arguments courants :

• --bootstrap-server <hôte:port> : Spécifie le broker Kafka auquel se connecter.
• --topic <nom_du_sujet> : Filtre la sortie pour afficher les répertoires d'un sujet spécifique.

Exemples :

• Lister les répertoires de journaux sur un broker :

  kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092
  

• Afficher les répertoires de journaux pour un sujet spécifique :

  kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092 --topic mon_sujet
  

6. kafka-preferred-replica-election.sh

Ce script lance des élections de réplicas préférés pour les sujets. Un réplica préféré est le broker qui est choisi comme leader pour une partition en fonction de son facteur de réplication. Si un broker tombe en panne et qu'un réplica non préféré devient le leader, cet outil peut être utilisé pour ramener le leadership vers le réplica préféré.

Arguments courants :

• --topic <nom_du_sujet> : Spécifie le sujet pour lequel élire les réplicas préférés.
• --broker-list <id_broker1,id_broker2,...> : Spécifie une liste d'IDs de brokers séparés par des virgules.
• --bootstrap-server <hôte:port> : Spécifie le broker Kafka auquel se connecter.

Exemples :

• Élire les réplicas préférés pour mon_sujet :

  kafka-preferred-replica-election.sh --topic mon_sujet --bootstrap-server kafka-broker-1:9092
  

• Élire les réplicas préférés pour plusieurs sujets :

  kafka-preferred-replica-election.sh --topic sujet1,sujet2 --bootstrap-server kafka-broker-1:9092
  

Considérations importantes et meilleures pratiques

• --bootstrap-server est essentiel : Assurez-vous toujours de spécifier l'argument --bootstrap-server correct pour vous connecter à votre cluster Kafka. Il s'agit généralement d'une liste d'hôte:port séparés par des virgules pour vos brokers.
• Environnement : Ces commandes se trouvent généralement dans le répertoire bin/ de votre installation Kafka. Vous devrez naviguer vers ce répertoire ou vous assurer que le répertoire bin de Kafka est dans votre PATH système.
• Permissions : Assurez-vous que l'utilisateur exécutant ces commandes dispose de l'accès réseau nécessaire pour atteindre les brokers Kafka.
• Configuration : De nombreux outils CLI peuvent accepter des configurations client Kafka via les arguments --property ou --producer-property/--consumer-property. Ceci est utile pour remplacer les sérialiseurs/désérialiseurs par défaut ou définir d'autres configurations client spécifiques.
• Sécurité : Pour les clusters Kafka sécurisés (par exemple, avec SSL/TLS ou authentification SASL), vous devrez passer des arguments supplémentaires liés à la sécurité (comme --command-config pointant vers un fichier de propriétés client) à ces outils.
• Suppression de sujet : N'oubliez pas que la suppression de sujet est une opération sensible et doit être explicitement activée dans le fichier server.properties du broker Kafka en utilisant delete.topic.enable=true.

Une façon sûre d'utiliser la CLI en production

Utilisez la CLI d'abord comme un outil d'inspection, puis comme un outil de mutation. --list, --describe et les courtes lectures console présentent un faible risque. --delete, --alter, les augmentations de partitions et les réinitialisations d'offsets modifient le comportement du cluster et devraient, dans la mesure du possible, suivre le même chemin de révision que les modifications d'application.

Une session de production pratique commence généralement par un fichier de configuration client :

cat client.properties
# security.protocol=SASL_SSL
# sasl.mechanism=SCRAM-SHA-512
# sasl.jaas.config=...

Ensuite, chaque commande l'inclut :

kafka-topics.sh --bootstrap-server kafka-1:9093 --command-config client.properties --describe --topic commandes

Pour les consommateurs console, évitez de rejoindre accidentellement un groupe d'application réel. Utilisez un ID de groupe temporaire lorsque vous inspectez des données, et utilisez --max-messages pour que la commande se termine :

kafka-console-consumer.sh \
  --bootstrap-server kafka-1:9093 \
  --command-config client.properties \
  --topic commandes \
  --group debug-commandes-$(date +%s) \
  --from-beginning \
  --max-messages 5 \
  --property print.key=true \
  --property print.offset=true

Cette petite habitude empêche une commande de débogage de voler des partitions à un service en direct. Elle laisse également une piste d'audit plus propre car le nom du groupe rend l'intention évidente.

La CLI est à son meilleur quand elle est ennuyeuse : une commande pour inspecter, une commande pour confirmer, et un enregistrement clair de toute commande qui change l'état.

Recettes de dépannage quotidien

Si un producteur dit qu'il écrit avec succès mais que l'équipe consommateur ne voit rien, commencez par le sujet :

kafka-topics.sh --bootstrap-server kafka-1:9092 --describe --topic commandes

Confirmez le nom du sujet, le nombre de partitions, la disponibilité du leader et les réplicas en synchronisation. Une faute de frappe dans un nom de sujet peut ressembler exactement à un pipeline cassé lorsque la création automatique de sujets est activée dans un cluster de développement. En production, un sujet avec des partitions hors ligne ou un ISR qui rétrécit indique un problème de broker ou de réplication avant de pointer vers le code de l'application.

Ensuite, lisez un petit échantillon avec un groupe temporaire :

kafka-console-consumer.sh \
  --bootstrap-server kafka-1:9092 \
  --topic commandes \
  --group debug-commandes-$(date +%s) \
  --max-messages 10 \
  --property print.key=true \
  --property print.timestamp=true \
  --property print.offset=true

Si des enregistrements apparaissent, Kafka a les données et le problème est probablement le groupe de consommateurs réel, ses offsets, ses abonnements ou sa logique de traitement. Si aucun enregistrement n'apparaît, vérifiez le sujet du producteur, les sérialiseurs, l'authentification et si le producteur écrit sur un cluster différent.

Pour les questions de retard, allez directement au groupe :

kafka-consumer-groups.sh --bootstrap-server kafka-1:9092 --describe --group ecrivain-commandes

Ne vous arrêtez pas au retard total. Comparez les partitions. Une seule partition avec un grand retard signifie un problème différent de celui où chaque partition a un retard modéré. Un retard sur une seule partition signifie souvent une asymétrie de clé ou une mauvaise affectation d'un consommateur. Un retard uniforme signifie généralement que l'ensemble de l'application est plus lent que le taux d'entrée.

Pour les questions "qu'est-ce qui a changé ?", inspectez la configuration du sujet :

kafka-configs.sh \
  --bootstrap-server kafka-1:9092 \
  --entity-type topics \
  --entity-name commandes \
  --describe

C'est là que vous repérez les changements de rétention, les surprises de politique de nettoyage, les remplacements de compression et les paramètres de taille de message qui diffèrent des hypothèses du service.

La sortie de la CLI ne remplace pas la surveillance, mais elle est excellente pour réduire l'incertitude. Lors d'un incident réel, quelques sorties de commande collées dans le ticket peuvent éviter à tout le monde de débattre pour savoir si le sujet existe, si les enregistrements sont présents et si le groupe bouge réellement.

Commandes à traiter avec précaution

Certaines commandes CLI Kafka semblent inoffensives car elles sont courtes. Elles ne sont pas inoffensives.

kafka-topics.sh --alter --partitions ne fait qu'augmenter le nombre de partitions ; il ne le réduit pas plus tard si vous regrettez le changement. Plus de partitions peuvent aider le parallélisme des consommateurs, mais elles peuvent aussi changer la distribution des clés pour les nouveaux enregistrements et casser les hypothèses dans les systèmes qui s'attendaient à ce que tous les événements d'une plage de clés atterrissent dans un ensemble plus petit de partitions.

kafka-consumer-groups.sh --reset-offsets --execute change l'endroit où un groupe lira ensuite. Utilisez d'abord --dry-run, arrêtez les consommateurs concernés et enregistrez les anciens offsets. La réinitialisation au plus ancien peut rejouer des données dans des systèmes qui ne sont pas idempotents. La réinitialisation au plus récent peut sauter des données que l'entreprise s'attend encore à traiter.

kafka-topics.sh --delete dépend de la configuration et de la politique du cluster, mais lorsque la suppression est autorisée, elle doit être traitée comme la suppression d'une table de base de données. Vérifiez le cluster, vérifiez le sujet et vérifiez si un autre environnement utilise la même convention de nommage. Un sujet de production appelé commandes-test est toujours de la production si des services réels en dépendent.

Pour les opérations répétables, placez la commande dans un runbook ou un script avec des variables explicites pour le cluster, le sujet, le groupe et la configuration de commande. La CLI est excellente pour l'investigation, mais la mutation en production doit être ennuyeuse, révisée et facile à auditer.