## Intro Apache NiFi déplace les données de manière fiable lorsque tout fonctionne, mais les systèmes réels font face à des conflits de ports, à l'engorgement des files d'attente (backpressure), à la pression mémoire JVM, à une configuration SSL incorrecte et à l'instabilité des clusters. Ce guide vous fournit des diagnostics pratiques, ce qu'il faut rechercher dans les journaux NiFi, des commandes sûres à exécuter et des workflows de récupération étape par étape. Il s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui exploitent NiFi aux côtés de Kafka, HDFS (Hadoop Distributed File System) : système de fichiers distribué Hadoop, Spark, Airflow et d'autres outils de pipelines de données. Ce que vous obtiendrez : - Une méthode de dépannage reproductible applicable sous pression - Des exemples concrets de pannes NiFi courantes et leurs correctifs - Des commandes et chemins de fichiers sûrs qui comptent en production - Un petit pilote mesurable à exécuter localement avant de toucher à la production ## Aperçu du workflow Utilisez cette séquence comme playbook par défaut. Elle raccourcit le temps de correction et évite les changements risqués. - Triage rapide - Symptôme : impossible de démarrer, UI (User Interface) : interface utilisateur inaccessible, files d'attente qui grossissent, erreurs sur les processeurs, nœud déconnecté ou risque de perte de données. - Ne redémarrez pas encore. Capturez d'abord l'état et les preuves. - Instantané d'état sécurisé - Obtenez le statut NiFi : bin/nifi.sh status - Capturez les journaux et la configuration du flux : mkdir -p snapshots cp logs/nifi-*.log snapshots/ cp conf/nifi.properties snapshots/ cp conf/flow.xml.gz snapshots/ 2>/dev/null || true cp conf/flow.json.gz snapshots/ 2>/dev/null || true - Inspectez les bons journaux - Problèmes de démarrage : logs/nifi-bootstrap.log - Erreurs d'exécution et de processeurs : logs/nifi-app.log - Événements utilisateur et accès : logs/nifi-user.log - Motifs grep rapides : grep -iE "exception|error|outofmemory|bind|zookeeper|ssl|trust|keystore|backpressure" logs/nifi-app.log | tail -n 200 tail -n 200 logs/nifi-bootstrap.log - Vérifiez les points chauds de configuration - conf/nifi.properties : - Port web : nifi.web.http.port ou nifi.web.https.port - SSL (Secure Sockets Layer) : protocole de sécurisation des échanges : nifi.security.* (keystore, truststore, types, mots de passe) - Répertoires : nifi.content.repository.directory , nifi.provenance.repository.directory , nifi.flowfile.repository.directory - Cluster : nifi.cluster.is.node , nifi.zookeeper.connect.string - Tas JVM (Java Virtual Machine) : machine virtuelle Java : conf/bootstrap.conf (lignes Xms/Xmx) - Contrôlez les dépendances externes et l'hôte - Ports en écoute : lsof -i -P -n | grep -E "LISTEN|:8080|:8443" | sort -u - Espace disque et pression d'inodes : df -h; df -i du -sh content_repository/* 2>/dev/null | sort -h | tail -n 20 du -sh provenance_repository/* 2>/dev/null | sort -h | tail -n 20 - Accessibilité réseau vers Kafka, HDFS, etc. : nc -vz votre-broker-kafka 9092 - Corrigez les schémas courants (voir le cookbook ci-dessous) - Validez le correctif - Santé via l'API REST (Representational State Transfer) : style d'architecture pour les services web : curl -s http://localhost:8080/nifi-api/flow/status | jq '.controllerStatus' 2>/dev/null || true - Les bulletins de l'UI sont clairs, les files drainent, le nombre d'erreurs chute et la provenance montre une lignée saine. - Prévenez la récurrence - Ajustez le backpressure, les tailles de lots et la concurrence - Augmentez le tas si nécessaire et revoyez la rétention des dépôts - Ajoutez des alertes pour la profondeur des files, les bulletins d'erreur et l'usage disque ### Cookbook des pannes courantes avec exemples pratiques ### Échec de démarrage : adresse déjà utilisée - Symptôme : l'UI ne démarre pas ; le log bootstrap affiche BindException: Address already in use - Diagnostiquez : grep -i bind logs/nifi-bootstrap.log | tail -n 50 lsof -i :8080 -sTCP:LISTEN -n -P - Corrigez : changez le port dans conf/nifi.properties ( nifi.web.http.port ou nifi.web.https.port ) vers un port libre, ou arrêtez le service en conflit. - Redémarrage sûr : bin/nifi.sh stop && sleep 5 && bin/nifi.sh start bin/nifi.sh status ### Épuisement du tas : java.lang.OutOfMemoryError - Symptôme : nifi-app.log affiche OutOfMemoryError ou des pauses GC (Garbage Collection) : ramasse-miettes fréquentes ; UI lente. - Diagnostiquez : grep -i outofmemory logs/nifi-app.log | tail -n 50 - Corrigez : augmentez Xms/Xmx dans conf/bootstrap.conf (par exemple de 2g à 4g) et réduisez les tailles par transaction ou le parallélisme sur les processeurs lourds. Assurez-vous que l'hôte a de la marge. - Exemple d'édition bootstrap.conf : java.arg.2=-Xms4g java.arg.3=-Xmx4g - Prévenez : activez le backpressure sur les connexions chaudes et dimensionnez correctement les lots. ### Files d'attente bloquées et backpressure - Symptôme : une connexion affiche le backpressure atteint ; les processeurs amont cèdent (yield) ; bulletins d'erreur sur les sinks comme PutKafka ou PutHDFS. - Diagnostiquez : - Dans l'UI, ouvrez les détails de la connexion. Vérifiez les seuils d'objets et de taille. - Dans les logs, cherchez les erreurs répétées de processeurs : grep -iE "backpressure|penalized|failed to send" logs/nifi-app.log | tail -n 200 - Corrigez : - Augmentez la capacité aval : haussez les tâches concurrentes, ajoutez des partitions ou des threads consommateurs selon le cas. - Baissez la taille des lots amont ou ajoutez un prioritizer. - En dernier recours, supprimez les FlowFiles non critiques de la connexion congestionnée (UI : List queue → sélectionner → Drop). Confirmez toujours la rétention des données et les SLA (Service Level Agreement) : accord de niveau de service d'abord. ### Conflits NAR ou de classpath - Symptôme : un processeur ne s'active pas ; ClassNotFoundException ou NoSuchMethodError dans nifi-app.log . - Diagnostiquez : grep -iE "classnotfound|nosuchmethod|nar" logs/nifi-app.log | tail -n 200 - Corrigez : - Retirez le NAR (NiFi Archive) : archive d'extension NiFi en conflit de lib ou extensions . - Nettoyez les répertoires de travail NiFi et redémarrez : bin/nifi.sh stop rm -rf work/nar/ work/jetty/ bin/nifi.sh start ### Échecs SSL ou d'authentification - Symptôme : javax.net.ssl.SSLHandshakeException , CertificateExpiredException ou échecs de connexion. - Diagnostiquez : grep -iE "ssl|handshake|certificate|truststore|keystore" logs/nifi-app.log | tail -n 200 - Corrigez : - Vérifiez les chemins et mots de passe du keystore/truststore dans conf/nifi.properties . - Contrôlez l'expiration du certificat : openssl x509 -in server.crt -noout -dates - Si nécessaire, renouvelez les certificats et mettez à jour les relations de confiance avant de redémarrer. ### Déconnexion de nœud de cluster - Symptôme : le nœud affiche Disconnected ; les logs mentionnent des problèmes de heartbeat ou ZooKeeper. - Diagnostiquez : grep -iE "disconnected|heartbeat|zookeeper|session" logs/nifi-app.log | tail -n 200 - Corrigez : - Validez nifi.zookeeper.connect.string et la santé de ZooKeeper. - Assurez-vous que les horloges sont synchronisées et que la latence réseau est stable. - Si un nœud est corrompu ou trop en retard, arrêtez-le, nettoyez work/ et les dépôts seulement en dernier recours après sauvegardes, puis rejoignez le cluster. ### Disque plein dans les dépôts - Symptôme : processeurs pénalisés ; écritures de provenance en échec ; le log d'application note des erreurs I/O. - Diagnostiquez : df -h; du -sh content_repository/* provenance_repository/* 2>/dev/null | sort -h | tail -n 20 - Corrigez : - Libérez de l'espace ou déplacez les dépôts vers des volumes plus grands en éditant conf/nifi.properties (planifiez une fenêtre de maintenance). - Réduisez la rétention de provenance (taille de stockage ou nombre d'événements) et augmentez la fréquence de purge. ## Commandes sûres et références rapides Utilisez-les depuis le répertoire d'installation NiFi. Contrôle du service et statut : bin/nifi.sh status bin/nifi.sh start bin/nifi.sh stop Suivi des logs : tail -f logs/nifi-app.log Vérification des ports : lsof -i -P -n | grep LISTEN | grep -E "\:8080|\:8443" Sauvegarde des configs critiques : cp conf/nifi.properties conf/nifi.properties.bak.$(date +%s) cp conf/flow.xml.gz conf/flow.xml.gz.bak.$(date +%s) 2>/dev/null || true cp conf/flow.json.gz conf/flow.json.gz.bak.$(date +%s) 2>/dev/null || true Endpoints REST sélectionnés (exemple HTTP) : curl -s http://localhost:8080/nifi-api/flow/status | jq 2>/dev/null || true curl -s http://localhost:8080/nifi-api/system-diagnostics | jq 2>/dev/null || true ## Workflows de récupération étape par étape ### Scénario A : NiFi ne démarre pas à cause d'un conflit de port - Confirmez l'échec et l'usage du port tail -n 100 logs/nifi-bootstrap.log lsof -i :8080 -sTCP:LISTEN -n -P - Choisissez un port libre et mettez à jour conf/nifi.properties - Définissez nifi.web.http.port=8082 (exemple) - Redémarrez et vérifiez bin/nifi.sh stop && sleep 5 && bin/nifi.sh start bin/nifi.sh status curl -s http://localhost:8082/nifi/ >/dev/null && echo OK ### Scénario B : Engorgement de file avec échecs PutKafka - Identifiez la connexion congestionnée et le processeur en échec dans l'UI ; capturez les bulletins. - Consultez les détails d'erreur dans les logs grep -iE "kafka|timeout|backpressure|broker" logs/nifi-app.log | tail -n 200 - Réduisez le débit ou la taille des lots amont ; augmentez les tâches concurrentes sur PutKafka ; confirmez l'accessibilité du broker nc -vz votre-broker-kafka 9092 - Si nécessaire, supprimez les FlowFiles non critiques après validation des parties prenantes. - Validez : la profondeur de file diminue, le débit d'envoi est stable, aucune nouvelle erreur pendant 15+ minutes. ### Scénario C : Nœud de cluster déconnecté - Inspectez les logs sur le nœud affecté grep -iE "disconnected|heartbeat|zookeeper|auth" logs/nifi-app.log | tail -n 200 - Validez nifi.zookeeper.connect.string et le chemin réseau. Assurez la synchronisation temporelle (exécutez chronyc tracking ou ntpdate -q pool.ntp.org ). - Redémarrez le nœud si transitoire. Si persistant, arrêtez NiFi, nettoyez work/nar et work/jetty , puis redémarrez bin/nifi.sh stop rm -rf work/nar/ work/jetty/ bin/nifi.sh start - Vérifiez que le nœud réintègre le cluster et que les flux sont synchronisés. ## Plan pilote local Objectif : pratiquer le diagnostic et la récupération sur un minuscule flux isolé exécutable sur votre poste. Restez ciblé, mesurable et facile à inspecter localement avant tout changement en production. - Construisez un petit flux - GenerateFlowFile → UpdateAttribute → LogAttribute - Ajoutez une branche : UpdateAttribute → PutFile vers un répertoire temporaire - Créez des pannes volontaires en toute sécurité - Conflit de port : définissez nifi.web.http.port sur un port utilisé, tentez de démarrer, puis corrigez - Backpressure : réglez le seuil d'objets d'une connexion à 10, puis envoyez 100 FlowFiles de test - Erreur de sink fichier : pointez PutFile vers un répertoire non accessible en écriture pour déclencher des bulletins - Exercez le workflow - Capturez le statut et les logs, grepez les erreurs, appliquez les correctifs du cookbook, et revérifiez - Définissez les signaux de réussite - Temps moyen de diagnostic sous 5 minutes - Aucune perte de données pour la branche LogAttribute - Bulletins clairs et files drainées dans les 10 minutes après correctif - Checklist pour aller au-delà du local - Sauvegardez conf et flux avant tout changement - Documentez les ports, dépôts, tas JVM et endpoints externes - Réexécutez les mêmes étapes sur un NiFi de staging avec une charge représentative ## Conclusion Le dépannage NiFi devient prévisible quand on suit un flux simple : triage, instantané, inspection des logs, vérification de la configuration et des dépendances, application des correctifs connus, et validation. Commencez par un petit pilote local pour développer les réflexes, puis reportez les mêmes étapes en staging et en production. Surveillez les suspects habituels : ports, paramètres SSL, tas JVM, capacité des dépôts et systèmes aval comme Kafka et HDFS. Avec des commandes sûres, des motifs de logs clairs et des workflows de récupération pas à pas, vous pouvez restaurer la santé des flux rapidement et prévenir la récurrence des incidents.