Kafka troubleshooting avec des exemples pratiques : guide d'implémentation

Un guide pratique pour diagnostiquer et corriger les problèmes Kafka les plus courants. Apprenez à lire les logs, à lancer des commandes sûres, à confirmer les causes racines et à exécuter des workflows de récupération pas à pas. Les exemples s'adressent aux développeurs, consultants DevOps et équipes techniques de startups opérant Kafka aux côtés de NiFi, Apache Spark, HDFS et Apache Airflow.

Introduction

Les incidents Kafka surgissent souvent sous forme de timeouts, de lag consommateur qui grimpe ou de lignes de logs inquiétantes lors des pics de trafic. Ce guide propose une méthode reproductible pour faire du Kafka troubleshooting sans risque de perte de données. Vous saurez lire les Kafka logs côté brokers et clients, exécuter des Kafka commands en lecture seule, formuler une hypothèse de cause racine, et dérouler des étapes de Kafka recovery sûres.

Vue d'ensemble du workflow

Suivez ce cheminement de triage vers récupération :

1. Stabiliser et cadrer

• Geler les changements risqués. Mettre en pause les automatisations bruyantes qui masquent les symptômes.
• Délimiter le périmètre : client unique, topic, broker, zone de dispo ou tout le cluster.

1. Capturer les signaux

• Sauvegarder les 15-60 dernières minutes de logs côté clients et brokers.
• Prendre un instantané des métriques clés : latences requêtes, lag consommateur, partitions sous-répliquées, disque broker, descripteurs de fichiers, CPU et réseau.

1. Classer le symptôme

• Timeouts ou forte latence côté producteurs.
• Lag consommateur en hausse ou partitions bloquées.
• Partitions sous-répliquées ou ISR qui rétrécit.
• Échecs d'authentification/autorisation.
• Échecs de démarrage broker ou contrôleur instable.

1. Lancer d'abord des contrôles read-only

• Décrire topics, groupes, brokers. Inspecter les configs et l'état des partitions.
• Confirmer la connectivité réseau et la résolution DNS.

1. Formuler l'hypothèse de cause racine

• Côté client vs broker vs infrastructure (réseau, disque) vs sécurité.

1. Appliquer le plus petit changement sûr

• Privilégier les changements réversibles : throttles, pause des consommateurs, rolling restarts.
• Éviter suppressions, forçage de leadership, ou paramètres qui réduisent la sécurité, sauf en ultime recours.

1. Vérifier et revenir en arrière

• Recontrôler métriques et logs. Retirer les throttles/commutateurs temporaires.

1. Documenter les constats

• Capturer le minimum de faits expliquant la panne et la correction.

Symptômes et logs courants

Associez ces logs et métriques à des causes probables :

Côté producteurs

Interprétation : congestion réseau, broker surchargé, mauvais bootstrap, ou DNS défaillant.

Interprétation : ISR trop petit pour acks=all, réplicas hors ligne ou disque lent.

Interprétation : message qui dépasse la taille maximale du topic/broker.

• Erreur : Request timed out, TimeoutException
• Erreur : NotEnoughReplicas ou NotEnoughReplicasAfterAppend
• Erreur : RecordTooLargeException

Côté consommateurs

Interprétation : traitement trop lent, boucles de rebalance, ou partition coincée sur un broker indisponible.

Interprétation : offsets expirés par rétention ou compactés.

Interprétation : churn du groupe, max.poll.interval.ms dépassé, ou broker instable.

• Le lag augmente alors que le consommateur tourne
• Erreur : OffsetOutOfRange
• Tempêtes de rebalance dans les logs

Brokers et cluster

Interprétation : des réplicas sont en retard ou hors ligne. Vérifier disque, réseau, CPU.

Interprétation : instabilité des métadonnées, partitions réseau, ou problèmes de quorum.

Interprétation : saturation du broker. Inspecter CPU et I/O.

Interprétation : les followers n'arrivent pas à suivre (disque/réseau lent).

• Partitions sous-répliquées > 0
• Élections ou battements du contrôleur
• Arriérés SocketServer, RequestHandlerPool
• Avertissements ReplicaFetcherThread

Sécurité

Interprétation : mécanisme inadapté ou chaîne de confiance cert invalide.

Interprétation : ACLs manquantes ou principal incorrect.

• Client authentication failed, échec SASL/SSL handshake
• Authorization failed pour Create/Write/Read

Stockage et OS

Interprétation : rétention trop longue, backlog de compaction, ou nettoyage bloqué.

Interprétation : limite de descripteurs trop basse pour le volume de partitions.

• Disque à ~100 %
• Trop de fichiers ouverts

Vérifications de causes racines

Clients

• Vérifier bootstrap servers, security.protocol et paramètres d'auth.
• Mesurer le taux de retries producteurs, tailles de batch, efficacité de la compression.
• Côté consommateurs : confirmer max.poll.interval.ms, max.poll.records, et le temps de traitement.

Réseau

• Tester la résolution DNS des brokers et advertised.listeners.
• Vérifier latence et perte de paquets inter-AZ/DC.
• Confirmer les règles pare-feu/security groups sur les ports des brokers.

Brokers

• Décrire brokers et topics pour trouver leaders, ISR et états de réplicas.
• Chercher l'épuisement des pools de threads, pauses GC et pression sur le page cache.
• Valider min.insync.replicas vs acks=all.

Stockage

• Assurer de l'espace libre sur log.dirs ; Kafka a besoin de marge pour les segments et la compaction.
• Surveiller le débit disque et l'iowait. Des disques lents contractent l'ISR.

Métadonnées et quorum

• Vérifier la stabilité du contrôleur. ZooKeeper : sessions stables. KRaft : voters, connectivité, logs d'élection.
• Surveiller les changements fréquents de leaders qui provoquent des timeouts clients.

Sécurité

• Confirmer principals, mécanismes et truststores. Aligner les configs client/broker.
• Contrôler les ACLs pour les opérations nécessaires sur topics et groupes.

Commandes sûres et récupération

Utilisez d'abord des commandes read-only. Préférez --describe et --list avant toute modification. Remplacez <...> par vos valeurs.

État des topics et brokers

• Lister les topics :

kafka-topics.sh --bootstrap-server <broker:9092> --list

• Décrire un topic en détail :

kafka-topics.sh --bootstrap-server <broker:9092> --describe --topic <topic>

• Décrire les brokers (via dump de métadonnées si dispo) ou consulter les logs serveur pour IDs et listeners.

Groupes de consommateurs

• Lister les groupes :

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

• Décrire le lag d'un groupe :

kafka-consumer-groups.sh --bootstrap-server <broker:9092> --describe --group <group>

• Réinitialiser les offsets en sécurité (dry-run d'abord) :

kafka-consumer-groups.sh --bootstrap-server <broker:9092> \
  --group <group> --topic <topic> --reset-offsets --to-latest --dry-run

• Appliquer seulement après vérification :

kafka-consumer-groups.sh --bootstrap-server <broker:9092> \
  --group <group> --topic <topic> --reset-offsets --to-latest --execute

Configs

• Inspecter la config d'un topic :

kafka-configs.sh --bootstrap-server <broker:9092> --entity-type topics \
  --entity-name <topic> --describe

• Mettre à jour une config (ex. augmenter temporairement retention.ms) :

kafka-configs.sh --bootstrap-server <broker:9092> --entity-type topics \
  --entity-name <topic> --alter --add-config retention.ms=<value>

Mouvements de partitions

• Générer et appliquer un plan de réaffectation avec throttle. Toujours le relire et l'appliquer en période creuse.

Throttling

• Limiter temporairement les producteurs ou utiliser des quotas pour réduire la charge durant la récupération.

Attention

• Éviter d'imposer des élections de leader et de désactiver des paramètres de sécurité sauf si vous acceptez le risque de perte de données. Documenter les risques avant de poursuivre.
• Préférer des changements en rolling : un broker à la fois, vérifier, puis continuer.

Exemples pratiques

Exemple 1 : Pic de lag consommateur après un déploiement Objectif : Rétablir une consommation régulière sans perdre de messages.

1. Vérifier le lag et l'assignation

• Commande :

kafka-consumer-groups.sh --bootstrap-server <broker:9092> --describe --group <group>

• Rechercher des partitions à fort lag et confirmer l'assignation du consommateur.

1. Consulter les logs du consommateur

• Signes : boucles de rebalance, CommitFailedException, traitement trop long.

1. Hypothèse

• Le déploiement a ralenti le traitement ou réduit la fréquence des polls, dépassant max.poll.interval.ms.

1. Actions sûres

• Augmenter modérément max.poll.interval.ms ou réduire le travail par enregistrement.
• Augmenter temporairement le nombre de consommateurs jusqu'au nombre de partitions.
• Si le lag est très ancien et acceptable à ignorer, planifier un reset d'offsets avec --dry-run d'abord.

1. Vérification

• Le lag doit décroître. Surveiller la fréquence des rebalances et le temps de traitement.

Exemple 2 : Partitions sous-répliquées après un disque plein sur un broker Objectif : Rétablir l'ISR et la santé de la réplication en sécurité.

1. Confirmer le périmètre

• Commande :

kafka-topics.sh --bootstrap-server <broker:9092> --describe --topic <topic>

• Surveiller la métrique « under-replicated partitions ».

1. Inspection du broker

• Vérifier l'espace disque libre et les erreurs disque dans les logs serveur.

1. Stabiliser

• Throttler temporairement les producteurs ou mettre en pause les flux volumineux.
• Envisager d'augmenter provisoirement retention.ms du topic uniquement si besoin d'espace pour compacter/déplacer plus tard.

1. Remédiation disque

• Libérer de l'espace proprement ou ajouter de la capacité sur log.dirs.
• Éviter la suppression manuelle de segments Kafka sans maîtrise des implications.

1. Récupération et vérification

• Redémarrer le broker affecté si nécessaire. Confirmer le retour de l'ISR.
• Observer ReplicaFetcherThread et le débit réseau.

Exemple 3 : Timeouts producteurs et RecordTooLargeException Objectif : Rétablir le débit producteur sans casser les consommateurs.

1. Confirmer l'erreur

• Les logs producteurs montrent RecordTooLargeException ou équivalent.

1. Options

• Réduire la taille des messages en scindant les charges ou en augmentant la compression.
• Si nécessaire, ajuster prudemment les limites :
• Config topic : max.message.bytes
• Configs broker liées : message.max.bytes, replica.fetch.max.bytes
• Procéder par incréments, privilégier la modification au niveau du topic.

1. Vérification de bout en bout

• Vérifier que les consommateurs peuvent récupérer les messages plus volumineux et qu'il n'y a pas de pic de fetch timeouts.

Exemple 4 : Échecs d'authentification après rotation de certificats Objectif : Rétablir la confiance client-broker.

1. Vérifier les logs

• Rechercher des erreurs de handshake SSL ou des incompatibilités de mécanismes SASL.

1. Valider les configs

• Aligner security.protocol et le mécanisme côté client et broker.
• Vérifier chemins/MDP du keystore/truststore et la présence de la chaîne CA.

1. Tester la connectivité

• Depuis l'hôte client, confirmer la joignabilité TCP du listener broker.

1. Vérifier la correction

• Connexion réussie et boucle produce-consume stable.

Exemple 5 : Contrôleur instable et changements fréquents de leader Objectif : Stabiliser les métadonnées pour réduire les timeouts clients.

1. Observer

• Les logs broker montrent des élections fréquentes ; les clients voient NotLeaderForPartition et des timeouts.

1. Vérifier la stabilité du quorum

• ZooKeeper : sessions stables et réseau entre brokers et ZooKeeper.
• KRaft : ensemble de voters, connectivité, contrôleur sain.

1. Remédier

• Corriger les partitions réseau, arrêter les redémarrages intempestifs, synchroniser les horloges.
• Appliquer des rolling restarts seulement après avoir confirmé la santé du quorum.

1. Vérifier

• Le contrôleur se stabilise. Les changements de leader reviennent à un rythme normal.

Plan pilote local

Objectif : Valider un petit jeu de workflows de troubleshooting en local avant d'agir en environnement partagé.

Périmètre

• Choisir 2 scénarios : pic de lag consommateur et RecordTooLargeException.
• Utiliser un topic de test à 3 partitions et un facteur de réplication réduit.

Plan

1. Préparer l'outillage

• Scripts pour capturer les logs et exécuter rapidement les commandes describe.
• Un petit tableau de bord ou des graphes pour lag, latence et partitions sous-répliquées.

1. Exécuter les scénarios

• Générer de petits messages, puis injecter un gros message pour déclencher RecordTooLargeException.
• Ralentir le traitement consommateur pour faire croître le lag.

1. S'exercer à la récupération

• Pour les gros enregistrements : scinder les payloads ou ajuster max.message.bytes au niveau du topic de façon contrôlée.
• Pour le lag : ajuster les paramètres de poll et augmenter le nombre de workers.

1. Mesurer

• Temps de détection : objectif < 2 min.
• Temps pour confirmer la cause : objectif < 10 min.
• Temps pour une récupération sûre : objectif < 20 min.

1. Codifier

• Transformer commandes et contrôles en un runbook court avec extraits prêts à copier-coller.

Conclusion

Un workflow discipliné de troubleshooting transforme les incidents Kafka en opérations prévisibles. Commencez par l'inspection en lecture seule, classez le symptôme, testez le plus petit changement sûr et vérifiez. Entraînez-vous avec un pilote local pour exécuter sereinement sous pression. Conservez un runbook concis de commandes et de motifs de logs. Avec le temps, vous réduirez les délais de récupération et éviterez les actions de dernier recours.

Checklist rapide

• Puis-je cadrer rapidement le périmètre (blast radius) ?
• Ai-je la dernière heure de logs clients et brokers ?
• Quelle catégorie d'erreur : producteur, consommateur, broker, sécurité ou stockage ?
• Quelle commande read-only confirmera mon hypothèse ?
• Quel est le plus petit changement sûr, et comment le rollbacker ?
• Les métriques sont-elles revenues à la normale et ai-je retiré les throttles temporaires ?