Un guide pratique pour diagnostiquer et corriger les problèmes Kafka les plus fréquents. Apprenez à lire les logs, exécuter des commandes sûres, confirmer les causes racines et appliquer des workflows de récupération étape par étape. ## Introduction Les problèmes Kafka se manifestent souvent d'abord par des timeouts, une augmentation du consumer lag ou des lignes de log alarmantes en période de pointe. Ce guide vous donne une méthode pratique et reproductible pour diagnostiquer et corriger les pannes les plus courantes sans risquer de perte de données. Vous apprendrez à lire les logs des brokers et des clients, exécuter des commandes sûres, confirmer les causes racines et exécuter des workflows de récupération étape par étape. Les exemples sont conçus pour les développeurs, consultants DevOps et équipes techniques de startups faisant tourner Kafka aux côtés d'outils comme NiFi, Apache Spark, HDFS et Apache Airflow. ## Vue d'ensemble du workflow Utilisez ce parcours triage-vers-récupération pour rester méthodique sous pression : - Stabiliser et délimiter - Geler les changements risqués. Mettre en pause l'automatisation bruyante si elle masque les symptômes. - Délimiter le rayon d'impact : client unique, topic, broker, zone de disponibilité ou cluster entier. - Capturer les signaux - Sauvegarder les 15 à 60 dernières minutes de logs des clients et des brokers. - Faire un instantané des métriques clés : latences des requêtes, consumer lag, partitions sous-répliquées, disque broker, descripteurs de fichiers, CPU et réseau. - Classifier le symptôme - Timeouts producer ou latence élevée - Croissance du consumer lag ou partitions bloquées - Partitions sous-répliquées ou ISR qui rétrécit - Échecs d'authentification ou d'autorisation - Échecs de démarrage broker ou basculements de contrôleur - Exécuter des vérifications en lecture seule d'abord - Décrire topics, groupes, brokers. Inspecter les configs et états de partitions. - Confirmer la connectivité réseau et la résolution DNS. - Formuler une hypothèse de cause racine - Côté client vs côté broker vs infra (réseau, disque) vs sécurité. - Appliquer le plus petit changement sûr - Privilégier les changements réversibles : throttles, pause des consommateurs, redémarrages roulants. - Éviter les suppressions, forcer le leadership ou modifier des configs qui réduisent la sécurité sauf en dernier recours. - Vérifier et annuler les mesures temporaires - Re-vérifier métriques et logs. Retirer les throttles et bascules temporaires. - Documenter les constats - Capturer l'ensemble minimal de faits qui expliquent la panne et la correction. ## Symptômes courants et logs Faites correspondre ces lignes de log et métriques aux causes probables : ### Symptômes côté producer

Log / Erreur	Signification probable
`Request timed out`, `TimeoutException`	Congestion réseau, broker surchargé, bootstrap incorrect ou mauvais DNS.
`NotEnoughReplicas` ou `NotEnoughReplicasAfterAppend`	ISR trop petit pour `acks=all`, répliques hors ligne ou disque lent.
`RecordTooLargeException`	Message dépasse la taille max du topic ou du broker.

### Symptômes côté consumer

Log / Erreur	Signification probable
Lag augmente alors que le consumer tourne	Traitement trop lent, boucles de rééquilibrage ou partition bloquée sur un broker mort.
`OffsetOutOfRange`	Offsets expirés à cause de la rétention ou compactés.
Tempêtes de rééquilibrage dans les logs	Instabilité du groupe, `max.poll.interval.ms` dépassé ou broker instable.

### Symptômes broker et cluster

Log / Métrique	Signification probable
Partitions sous-répliquées > 0	Une ou plusieurs répliques sont en retard ou hors ligne. Vérifier disque, réseau, CPU.
Élections de contrôleur ou logs de contrôleur qui fluctuent	Instabilité des métadonnées, partitions réseau ou problèmes de quorum.
File d'attente `SocketServer`, `RequestHandlerPool`	Saturation broker. Regarder CPU et I/O.
Avertissements `ReplicaFetcherThread`	Les followers ne suivent pas à cause d'un disque ou réseau lent.

### Symptômes sécurité

Log / Erreur	Signification probable
`SSL handshake error`, `SASL handshake failed`, `Client authentication failed`	Mécanisme mal assorti ou problèmes de confiance des certificats.
`Authorization failed for Create/Write/Read`	ACLs manquantes ou principal incorrect.

### Symptômes stockage et OS

Log / Métrique	Signification probable
Disque à ou près de 100%	Rétention trop longue, backlog de compactage ou nettoyage de logs bloqué.
`Too many open files`	Limite de descripteurs de fichiers trop basse pour le nombre topic-partitions.

## Vérifications de causes racines ### Vérifications client - Vérifier les serveurs bootstrap, security.protocol et paramètres d'authentification. - Mesurer le taux de retentatives producer, tailles de batch et efficacité de la compression. - Pour les consumers, confirmer max.poll.interval.ms , max.poll.records et temps de traitement. ### Vérifications réseau - Tester la résolution DNS des brokers et advertised.listeners . - Vérifier latence et perte de paquets inter-AZ ou inter-DC. - Confirmer règles pare-feu ou groupes de sécurité sur ports broker. ### Vérifications broker - Décrire brokers et topics pour trouver leaders, ISR et états des répliques. - Rechercher épuisement des pools de threads, pauses GC et pression sur le cache de pages. - Valider comportement min.insync.replicas vs acks=all . ### Vérifications stockage - S'assurer d'espace libre adéquat sur log.dirs . Kafka a besoin de marge pour le roulement de segments et la compactation. - Surveiller débit disque et iowait. Disques lents causent rétrécissement de l'ISR. ### Vérifications métadonnées et quorum - Vérifier stabilité du contrôleur. Si ZooKeeper : vérifier stabilité des sessions. Si KRaft : confirmer voters du quorum et logs d'élection. - Surveiller changements de leader fréquents qui peuvent cascader en timeouts clients. ### Vérifications sécurité - Confirmer principaux, mécanismes et truststores. Aligner configs client et broker. - Vérifier ACLs pour opérations requises sur topics et groupes cibles. ## Commandes sûres et récupération Utilisez d'abord les commandes en lecture seule. Privilégiez --describe et --list avant tout changement. Remplacez les <...> par vos valeurs. ### État topics et brokers # Lister les topics kafka-topics.sh --bootstrap-server --list # Décrire un topic en détail kafka-topics.sh --bootstrap-server --describe --topic # Décrire les brokers (via dump métadonnées si dispo) ou consulter logs serveur pour node IDs et infos listeners. ### Groupes de consommateurs # Lister les groupes kafka-consumer-groups.sh --bootstrap-server --list # Décrire le lag d'un groupe kafka-consumer-groups.sh --bootstrap-server --describe --group # Réinitialiser offsets proprement (dry run d'abord) kafka-consumer-groups.sh --bootstrap-server \ --group --topic --reset-offsets --to-latest --dry-run # Appliquer seulement après vérification kafka-consumer-groups.sh --bootstrap-server \ --group --topic --reset-offsets --to-latest --execute ### Configurations # Inspecter configs d'un topic kafka-configs.sh --bootstrap-server --entity-type topics \ --entity-name --describe # Modifier une config de topic proprement (ex: augmentation temporaire rétention) kafka-configs.sh --bootstrap-server --entity-type topics \ --entity-name --alter --add-config retention.ms= ### Déplacement de partitions - Générer et appliquer un plan de réassignation avec throttle. Toujours revoir le plan et appliquer en fenêtre de faible trafic. ### Throttling - Throttler temporairement les producers ou utiliser des quotas pour réduire la charge pendant la récupération. ### Prudence - Éviter les élections de leader forcées et la désactivation des configs de sécurité sauf si vous acceptez le risque de perte de données. Documenter les risques avant de procéder. - Privilégier tout changement broker en rolling. Changer un broker, valider, puis continuer. ## Exemples pratiques ### Exemple 1 : Pic de consumer lag après un déploiement Objectif : Restaurer une consommation stable sans perdre de messages. - Vérifier lag et assignation kafka-consumer-groups.sh --bootstrap-server --describe --group - Repérer partitions avec lag élevé et vérifier si le consumer est assigné. - Examiner les logs consumer - Signes : boucles de rééquilibrage, CommitFailedException , traitement trop long. - Hypothèse - Le déploiement a augmenté le temps de traitement ou réduit la fréquence de poll, atteignant max.poll.interval.ms (défaut 300000 ms / 5 minutes). - Actions sûres - Augmenter max.poll.interval.ms modérément (ex: 600000 ms / 10 minutes) ou réduire le travail par enregistrement. - Mettre à l'échelle temporairement les consumers pour correspondre au nombre de partitions. - Si le lag est ancien et acceptable à ignorer, planifier une réinitialisation d'offsets avec --dry-run d'abord. - Vérifier - Le lag doit baisser. Surveiller fréquence des rééquilibrages et métriques de temps de traitement consumer. ### Exemple 2 : Partitions sous-répliquées après remplissage disque broker Objectif : Restaurer ISR et santé de réplication proprement. - Confirmer la portée kafka-topics.sh --bootstrap-server --describe --topic - Surveiller métrique cluster : partitions sous-répliquées. - Inspection broker - Vérifier espace disque libre sur le broker affecté. Revoir logs serveur pour erreurs disque. - Stabiliser - Throttler temporairement les producers ou mettre en pause l'ingestion à haut volume. - Envisager d'augmenter temporairement retention.ms seulement si vous avez besoin de marge pour compacter ou déplacer les données plus tard (ex: de 604800000 ms / 7 jours à 1209600000 ms / 14 jours). - Remédier au disque - Libérer de l'espace proprement ou ajouter de la capacité sur log.dirs . - Éviter la suppression manuelle de segments de log Kafka sauf si vous en comprenez parfaitement les implications. - Récupérer et vérifier - Redémarrer le broker affecté si requis. Confirmer que l'ISR repousse. - Surveiller ReplicaFetcherThread et débit réseau. ### Exemple 3 : Timeouts producer et RecordTooLargeException Objectif : Restaurer le débit producer sans casser les consumers. - Confirmer l'erreur - Logs producer montrent RecordTooLargeException ou similaire. - Options - Réduire la taille des messages en divisant les payloads ou augmentant la compression. - Si nécessaire, ajuster prudemment les limites broker ou topic : - Config topic : max.message.bytes - Configs broker associées : message.max.bytes , replica.fetch.max.bytes - Faire les changements incrémentalement et privilégier un changement au niveau topic plutôt que cluster-wide. - Exemple : si vos messages font 2 MB, mettre topic max.message.bytes à 2097152 (2 MB) et broker message.max.bytes à au moins 2097152. - Vérifier bout-en-bout - S'assurer que les consumers peuvent récupérer les messages plus gros. Valider absence de pic de timeouts fetch. ### Exemple 4 : Échecs d'authentification après rotation de certificats Objectif : Restaurer la confiance client-broker. - Examiner les logs - Chercher erreurs SSL handshake ou mismatches de mécanisme SASL. - Valider les configs - Aligner security.protocol et mécanisme des deux côtés. - Vérifier chemins keystore/truststore, mots de passe et présence de la chaîne CA. - Tester la connectivité - Depuis l'hôte client, confirmer accessibilité TCP vers le listener broker. - Vérifier la correction - Connexion réussie et boucle produire-consommer stable. ### Exemple 5 : Contrôleur qui fluctue et changements de leader fréquents Objectif : Stabiliser les métadonnées pour réduire les timeouts clients. - Observer - Logs broker montrent élections de contrôleur fréquentes. Clients voient NotLeaderForPartition et timeouts. - Vérifier stabilité du quorum - Pour ZooKeeper : vérifier stabilité des sessions et réseau entre brokers et ZooKeeper. - Pour KRaft : confirmer ensemble des voters, connectivité et santé du nœud contrôleur. - Remédier - Corriger partitions réseau, éliminer redémarrages bruyants, s'assurer que les horloges sont synchronisées. - Appliquer redémarrages roulants seulement après confirmation santé du quorum. - Vérifier - Contrôleur devient stable. Changements de leader reviennent à des niveaux normaux. ## Plan pilote local Objectif : Prouver un petit ensemble de workflows de dépannage localement avant de toucher aux environnements partagés. ### Périmètre - Choisir 2 scénarios : pic de consumer lag et RecordTooLargeException . - Utiliser un topic de test unique avec 3 partitions et un facteur de réplication faible. ### Plan - Préparer l'outillage - Scripts pour capturer logs et lancer commandes describe rapidement. - Dashboard ou graphiques simples pour lag, latence et partitions sous-répliquées. - Exécuter les scénarios - Générer petits messages, puis injecter un gros message pour déclencher RecordTooLargeException . - Ralentir le traitement consumer pour déclencher croissance du lag. - Pratiquer la récupération - Pour gros enregistrements : diviser payloads ou ajuster topic max.message.bytes de façon contrôlée. - Pour lag : ajuster paramètres poll consumer et mettre à l'échelle les workers. - Mesurer - Temps pour détecter le symptôme : cible sous 2 minutes. - Temps pour confirmer cause racine : cible sous 10 minutes. - Temps pour récupération sûre : cible sous 20 minutes. - Codifier - Transformer commandes et vérifications en runbook court avec extraits copier-coller. Ce pilote étroit et mesurable est facile à inspecter localement et bâtit la confiance avant changements cluster-wide. ## Conclusion Un workflow de dépannage stable 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. Pratiquez avec un pilote local pour que l'équipe puisse exécuter sous stress. Gardez un runbook court de commandes et patterns de logs. Avec le temps, vous réduirez le temps de récupération et éviterez les actions risquées de dernier recours. ### Liste de vérification rapide - Puis-je délimiter le rayon d'impact rapidement ? - Ai-je la dernière heure de logs clients et brokers ? - Dans quelle catégorie d'erreur suis-je : producer, consumer, broker, sécurité ou stockage ? - Quelle commande en lecture seule confirmera mon hypothèse ? - Quel est le plus petit changement sûr et comment l'annuler ? - Les métriques ont-elles récupéré et ai-je retiré les throttles temporaires ?