NiFi troubleshooting avec des exemples pratiques : guide concret

Intro

Apache NiFi déplace les données de façon fiable lorsque tout est sain, mais en production on rencontre inévitablement des conflits de ports, de la backpressure sur les files, de la pression mémoire JVM, des erreurs SSL et de l'instabilité de cluster. Ce guide propose une méthode pratique de NiFi troubleshooting, ce qu'il faut chercher dans les NiFi logs, des NiFi commands sûres à exécuter, et des workflows de NiFi recovery étape par étape. Il s'adresse aux développeurs, consultants DevOps et équipes techniques opérant NiFi aux côtés de Kafka, HDFS, Apache Spark, Apache Airflow et autres data pipelines.

Ce que vous obtiendrez :

• Une méthode de troubleshooting reproductible sous pression
• Des exemples concrets de pannes NiFi courantes et leurs corrections
• Des NiFi commands et chemins de fichiers utiles en production
• Un petit pilote local mesurable avant toute action en production

Vue d'ensemble du workflow

Utilisez cette séquence comme playbook par défaut. Elle réduit le temps de correction et évite les changements risqués.

1. Triage rapide

• Symptômes : impossible de démarrer, UI inaccessible, files qui grossissent, erreurs sur des processors, nœud déconnecté, ou crainte de perte de données.
• Ne redémarrez pas tout de suite. Capturez d'abord l'état et les preuves.

1. Instantané d'état en sécurité

• État NiFi :

bin/nifi.sh status

• Snapshot des logs et de la config du flow :

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

1. Inspecter les bons logs

• Problèmes au démarrage : logs/nifi-bootstrap.log
• Erreurs runtime et processors : 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

1. Vérifier les points chauds de configuration

• conf/nifi.properties :
• Port Web : nifi.web.http.port ou nifi.web.https.port
• SSL : nifi.security.* (keystore, truststore, types, mots de passe)
• Répertoires des dépôts : nifi.content.repository.directory, nifi.provenance.repository.directory, nifi.flowfile.repository.directory
• Cluster : nifi.cluster.is.node, nifi.zookeeper.connect.string
• Heap JVM : conf/bootstrap.conf (lignes Xms/Xmx)

1. Vérifier dépendances externes et hôte

• Ports en écoute :

lsof -i -P -n | grep -E "LISTEN|:8080|:8443" | sort -u

• Espace disque et 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

• Connectivité réseau vers Kafka, HDFS, etc. (exemple) :

nc -vz your-kafka-broker 9092

1. Corriger selon les schémas connus (voir cookbook ci-dessous)

1. Valider la correction

• Santé via l'API REST NiFi :

curl -s http://localhost:8080/nifi-api/flow/status | jq '.controllerStatus' 2>/dev/null || true

• Les bulletins UI sont clairs, les files se vident, le nombre d'erreurs baisse et la provenance montre une lignée saine.

1. Prévenir la récidive

• Ajuster backpressure, tailles de batch et parallélisme
• Augmenter le heap si nécessaire et revoir la rétention des dépôts
• Ajouter des alertes sur profondeur de file, bulletins d'erreur, et usage disque

Recettes de pannes courantes avec exemples pratiques

1. Échec au démarrage : Address already in use

• Symptôme : l'UI ne s'ouvre jamais ; le bootstrap log affiche BindException: Address already in use
• Diagnostic :

grep -i bind logs/nifi-bootstrap.log | tail -n 50
lsof -i :8080 -sTCP:LISTEN -n -P

• Correction : changer le port dans conf/nifi.properties (nifi.web.http.port ou nifi.web.https.port) vers un port libre, ou arrêter le service en conflit.
• Redémarrage sûr :

bin/nifi.sh stop && sleep 5 && bin/nifi.sh start
bin/nifi.sh status

1. Épuisement de heap : java.lang.OutOfMemoryError

• Symptôme : OutOfMemoryError dans nifi-app.log ou pauses GC fréquentes ; UI lente.
• Diagnostic :

grep -i outofmemory logs/nifi-app.log | tail -n 50

• Correction : augmenter Xms/Xmx dans conf/bootstrap.conf (par ex. de 2g à 4g) et réduire les tailles de transaction ou le parallélisme des processors lourds. S'assurer que l'hôte a la marge nécessaire.
• Exemple d'édition bootstrap.conf :

java.arg.2=-Xms4g
java.arg.3=-Xmx4g

• Prévention : activer la backpressure sur les connexions chaudes et calibrer les tailles de lots.

1. Files bloquées et backpressure

• Symptôme : une connexion atteint la backpressure ; les processors amont cèdent ; bulletins d'erreur sur des sinks comme PutKafka ou PutHDFS.
• Diagnostic :
• Dans l'UI, ouvrir le détail de la connexion. Vérifier seuils d'objets et de taille.
• Dans les logs, chercher les erreurs répétées.

grep -iE "backpressure|penalized|failed to send" logs/nifi-app.log | tail -n 200

• Correction :
• Augmenter la capacité aval : plus de tâches concurrentes, plus de partitions ou de threads consommateurs si pertinent.
• Réduire la taille des lots en amont ou ajouter un prioritizer.
• En dernier recours, supprimer des FlowFiles non critiques depuis la connexion congestionnée (UI : List queue -> sélectionner -> Drop) après validation des exigences de rétention et SLA.

1. Conflits NAR ou classpath

• Symptôme : un processor ne peut pas s'activer ; ClassNotFoundException ou NoSuchMethodError dans nifi-app.log.
• Diagnostic :

grep -iE "classnotfound|nosuchmethod|nar" logs/nifi-app.log | tail -n 200

• Correction :
• Retirer le NAR en conflit de lib ou extensions.
• Purger les répertoires de travail NiFi et redémarrer :

bin/nifi.sh stop
rm -rf work/nar/ work/jetty/
bin/nifi.sh start

1. Échecs SSL ou d'authentification

• Symptôme : javax.net.ssl.SSLHandshakeException, CertificateExpiredException ou échecs de connexion.
• Diagnostic :

grep -iE "ssl|handshake|certificate|truststore|keystore" logs/nifi-app.log | tail -n 200

• Correction :
• Vérifier chemins et mots de passe keystore/truststore dans conf/nifi.properties.
• Vérifier l'expiration des certificats :

openssl x509 -in server.crt -noout -dates

• Si besoin, faire tourner les certificats et mettre à jour les relations de confiance avant redémarrage.

1. Nœud de cluster déconnecté

• Symptôme : le nœud est Disconnected ; logs mentionnant heartbeat ou ZooKeeper.
• Diagnostic :

grep -iE "disconnected|heartbeat|zookeeper|session" logs/nifi-app.log | tail -n 200

• Correction :
• Valider nifi.zookeeper.connect.string et la santé de ZooKeeper.
• S'assurer de la synchronisation d'horloge et d'une latence réseau stable.
• Si un nœud est corrompu ou très en retard, l'arrêter, ne nettoyer work/ et les dépôts qu'en dernier recours après sauvegardes, puis le réintégrer au cluster.

1. Disque plein dans les dépôts

• Symptôme : processors pénalisés ; écritures de provenance en échec ; erreurs d'E/S dans les logs.
• Diagnostic :

df -h; du -sh content_repository/* provenance_repository/* 2>/dev/null | sort -h | tail -n 20

• Correction :
• Libérer de l'espace ou déplacer les dépôts vers des volumes plus grands via conf/nifi.properties (prévoir un créneau de maintenance).
• Diminuer la rétention de provenance (taille ou nombre d'événements) et augmenter la fréquence de purge.

Commandes sûres et mémo rapide

À exécuter 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

Suivre les logs :

tail -f logs/nifi-app.log

Vérifier les ports :

lsof -i -P -n | grep LISTEN | grep -E ":8080|:8443"

Sauvegarder la configuration critique :

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 reprise pas à pas

Scénario A : NiFi ne démarre pas à cause d'un conflit de port

1. Confirmer l'échec et l'usage du port

tail -n 100 logs/nifi-bootstrap.log
lsof -i :8080 -sTCP:LISTEN -n -P

1. Choisir un port libre et mettre à jour conf/nifi.properties

• Exemple : nifi.web.http.port=8082

1. Redémarrer et vérifier

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 : File bloquée avec échecs PutKafka

1. Identifier dans l'UI la connexion congestionnée et le processor en échec ; capturer les bulletins.
2. Consulter les détails d'erreur dans les logs

grep -iE "kafka|timeout|backpressure|broker" logs/nifi-app.log | tail -n 200

1. Réduire le débit entrant ou la taille des lots en amont ; augmenter les tâches concurrentes de PutKafka ; confirmer l'accessibilité du broker

nc -vz your-kafka-broker 9092

1. Au besoin, supprimer les FlowFiles non critiques après validation des parties prenantes.
2. Valider : la profondeur de file baisse, le taux d'envoi se stabilise, plus de nouvelles erreurs pendant 15+ minutes.

Scénario C : Nœud de cluster déconnecté

1. Inspecter les logs du nœud affecté

grep -iE "disconnected|heartbeat|zookeeper|auth" logs/nifi-app.log | tail -n 200

1. Valider nifi.zookeeper.connect.string et le chemin réseau. Assurer la synchro de l'heure.
2. Redémarrer le nœud si c'est transitoire. Si persistant, arrêter NiFi, purger work/nar et work/jetty, puis redémarrer

bin/nifi.sh stop
rm -rf work/nar/ work/jetty/
bin/nifi.sh start

1. Vérifier la réintégration du nœud et la synchronisation des flows.

Plan pilote local

Objectif : s'exercer au diagnostic et à la reprise sur un flux minuscule et isolé, exécutable en local. Restreint, mesurable, et simple à inspecter avant toute action en production.

1. Construire un petit flux

• GenerateFlowFile -> UpdateAttribute -> LogAttribute
• Ajouter une branche : UpdateAttribute -> PutFile vers un répertoire temporaire

1. Provoquer des échecs sûrs

• Conflit de port : définir nifi.web.http.port sur un port utilisé, tenter de démarrer, puis corriger
• Backpressure : seuil d'objets à 10 sur une connexion, puis envoyer 100 FlowFiles de test
• Erreur de sink fichier : pointer PutFile vers un répertoire non inscriptible pour déclencher des bulletins

1. Pratiquer le workflow

• Capturer l'état et les logs, grep les erreurs, appliquer les corrections du cookbook, puis revérifier

1. Définir les signaux de succès

• Temps moyen de diagnostic < 5 minutes
• Aucune perte de données sur la branche LogAttribute
• Bulletins clairs et files en décrue sous 10 minutes après correctif

1. Checklist avant d'aller plus loin

• Sauvegarder conf et flow avant tout changement
• Documenter ports, dépôts, heap JVM et endpoints externes
• Répliquer ces étapes sur un NiFi de staging avec une charge représentative

Conclusion

Le NiFi troubleshooting devient prévisible avec une routine simple : triage, capture d'instantané, inspection des NiFi logs, vérification de la configuration et des dépendances, application des correctifs connus, puis validation. Commencez avec un petit pilote local pour ancrer les réflexes, puis appliquez les mêmes étapes en staging et en production. Surveillez les suspects habituels : ports, réglages SSL, heap JVM, capacité des dépôts et systèmes aval comme Kafka et HDFS. Avec des NiFi commands sûres, des motifs de logs clairs et des workflows de NiFi recovery pas à pas, vous restaurez rapidement la santé du flux et réduisez les incidents répétés.