## Introduction Apache Hop (Hop Orchestration Platform) est un outil open source d'intégration et d'orchestration de données conçu pour créer, exécuter et surveiller des pipelines et des flux de travail de données. L'interface en ligne de commande (CLI) de Hop fournit un ensemble d'utilitaires pour gérer les projets, les environnements, les pipelines et les flux de travail sans interface graphique. Les opérateurs et les développeurs utilisent ces commandes pour automatiser des tâches, diagnostiquer des problèmes et maintenir des systèmes de traitement de données fiables. Cet article fournit des exemples pratiques, prêts à copier-coller, des commandes essentielles d'Apache Hop. Il s'adresse aux développeurs, aux ingénieurs DevOps et aux ingénieurs de données qui doivent faire fonctionner Hop en production et dans des environnements de test. Chaque commande inclut les prérequis, un exemple concret, la sortie attendue, les signaux d'échec courants et des conseils de récupération. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier les résultats et documenter les étapes de récupération. Nous supposons que Hop est installé et configuré conformément à la documentation officielle, et nous mettons l'accent sur des commandes adaptées à la version, en utilisant Hop 1.2.0 comme version de référence. ## Inventaire de la version et de l'environnement La première étape de toute tâche opérationnelle consiste à déterminer la version exacte d'Apache Hop et son environnement d'exécution. Ces informations sont essentielles pour le dépannage, la vérification de compatibilité et l'application de la syntaxe correcte des commandes. ### Vérifier la version de Hop Prérequis : Les binaires Hop sont disponibles dans votre PATH ou vous êtes dans le répertoire d'installation de Hop. Commande : hop -version Sortie attendue : Apache Hop 1.2.0 Ce qu'il faut observer : Le numéro de version doit correspondre à la version que vous souhaitez utiliser. Si la commande échoue avec command not found , votre PATH n'est pas configuré correctement. Si une version plus ancienne apparaît, vous avez peut-être plusieurs installations. Récupération : Vérifiez le répertoire d'installation et assurez-vous que le script hop est exécutable. Sur Linux/macOS, vérifiez avec which hop . Sur Windows, vérifiez l'emplacement du fichier hop.bat et la variable d'environnement PATH. ### Vérifier la version de Java Prérequis : Java est installé et JAVA_HOME est défini. Commande : java -version Sortie attendue (exemple pour Java 11) : openjdk version "11.0.12" 2021-07-20 OpenJDK Runtime Environment (build 11.0.12+7) OpenJDK 64-Bit Server VM (build 11.0.12+7, mixed mode) Ce qu'il faut observer : Apache Hop 1.2.0 prend en charge Java 11 et 17. Si vous voyez Java 8 ou une version non prise en charge, Hop risque de ne pas démarrer. Récupération : Installez un JDK pris en charge et définissez correctement JAVA_HOME. Par exemple, sur Linux : export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 export PATH=$JAVA_HOME/bin:$PATH ### Vérifier la configuration de l'environnement Hop utilise des fichiers de configuration d'environnement pour définir les connexions et les variables. Pour lister les environnements disponibles, exécutez : Commande : hop -list-environments Sortie attendue : Available environments: - local - dev - prod Ce qu'il faut observer : Assurez-vous que l'environnement que vous souhaitez utiliser existe. Sinon, vous devrez peut-être le créer avec hop -create-environment ou via l'interface graphique. Récupération : Si un environnement manque, définissez-le dans le répertoire config ou utilisez la commande pour le créer. Par exemple : hop -create-environment -name staging -variables staging-variables.json ## Gestion sûre de la configuration Apache Hop vous permet de gérer les fichiers de configuration des projets, des environnements et des métadonnées. Modifier la configuration peut affecter tous les pipelines, il faut donc le faire avec précaution. ### Sauvegarder la configuration avant toute modification Sauvegardez toujours le répertoire config avant de faire des modifications. Commande (Linux/macOS) : tar -czf hop-config-backup-$(date +%Y%m%d).tar.gz config/ Commande (Windows PowerShell) : Compress-Archive -Path config\* -DestinationPath hop-config-backup-$(Get-Date -Format yyyyMMdd).zip Ce qu'il faut observer : Le fichier d'archive doit être créé sans erreur. Vérifiez que sa taille est raisonnable. Récupération : Si une modification de configuration casse Hop, restaurez la sauvegarde : tar -xzf hop-config-backup-YYYYMMDD.tar.gz ### Modifier une propriété de configuration en toute sécurité Supposons que vous deviez changer le niveau de journalisation de INFO à DEBUG pour le dépannage. La configuration de Hop est stockée dans des fichiers comme hop-config.json ou log4j2.xml selon la version. Pour Hop 1.2.0, la configuration de la journalisation se trouve dans config/log4j2.xml . Étape 1 : Observer le réglage actuel grep -n "Root level" config/log4j2.xml Sortie attendue : Étape 2 : Faire une copie du fichier cp config/log4j2.xml config/log4j2.xml.bak Étape 3 : Modifier le fichier Changez level="INFO" en level="DEBUG" . Étape 4 : Vérifier la modification grep -n "Root level" config/log4j2.xml Sortie attendue : Étape 5 : Tester Exécutez un pipeline simple pour voir si les journaux sont plus détaillés. Récupération : En cas de problème, restaurez à partir de la sauvegarde : cp config/log4j2.xml.bak config/log4j2.xml ### Éviter de coder en dur les secrets Ne mettez jamais de mots de passe ou de jetons directement dans les fichiers de configuration ou les paramètres de pipeline. Utilisez des variables d'environnement ou le système de variables de Hop. Exemple : Dans config/environments/dev.json , définissez une variable pour le mot de passe de la base de données : { "variables": { "DB_PASSWORD": "${env:DB_PASSWORD}" } } Ensuite, dans votre pipeline, utilisez ${DB_PASSWORD} . Lors de l'exécution, définissez la variable d'environnement : export DB_PASSWORD='votre-mot-de-passe-secret' hop -run -file my-pipeline.hpl -environment dev Cela permet de garder les secrets hors du contrôle de version. ## Vérification et diagnostic Après avoir exécuté un pipeline ou un flux de travail, vous devez vérifier qu'il s'est exécuté correctement et diagnostiquer tout problème. ### Exécuter un pipeline avec journalisation La commande de base pour exécuter un pipeline est : Commande : hop -run -file /chemin/vers/my-pipeline.hpl -environment dev -level Basic Sortie attendue : En cas de succès, vous verrez des messages de journalisation montrant la progression et la fin. Exemple d'extrait : 2023-03-15 14:30:22 - INFO - Pipeline started 2023-03-15 14:30:25 - INFO - Transformation completed 2023-03-15 14:30:25 - INFO - Pipeline finished successfully En cas d'erreur, vous verrez des traces de pile ou des messages d'erreur. ### Vérifier le résultat du pipeline à l'aide du journal Souvent, vous voulez vérifier le résultat d'un pipeline de manière programmatique. Vous pouvez utiliser l'option -capture pour écrire les métriques dans un fichier : Commande : hop -run -file /chemin/vers/my-pipeline.hpl -environment dev -capture metrics.csv Fichiers attendus : - metrics.csv contenant les métriques de performance comme les lignes traitées, la durée, etc. Inspecter les métriques : head metrics.csv Exemple de contenu : StepName,Copynr,Read,Written,Input,Output,Updated,Rejected,Errors,Status Table input,0,10000,0,10000,0,0,0,0,Finished Table output,0,0,10000,0,10000,0,0,0,Finished Ce qu'il faut observer : La colonne Errors doit être à 0 pour toutes les étapes. Si une étape a une valeur non nulle, enquêtez. Récupération : Consultez les journaux Hop dans le répertoire logs/ pour des messages d'erreur détaillés. ### Diagnostiquer les problèmes de connexion Si un pipeline échoue en raison d'une erreur de connexion à la base de données, vous pouvez tester la connexion en utilisant un pipeline simple ou la commande hop -test-database si elle est disponible. Dans Hop 1.2.0, il n'y a pas de commande intégrée de test de base de données, mais vous pouvez exécuter un pipeline qui ne contient qu'une connexion à la base de données et une transformation factice. Alternativement, utilisez l'interface graphique de Hop pour tester les connexions. Commande pour exécuter un pipeline minimal avec base de données : hop -run -file test-db-connection.hpl -environment dev Sortie attendue : Si la connexion réussit, les journaux du pipeline n'afficheront aucune erreur. Si elle échoue, le message d'erreur indiquera la cause (par exemple, mauvais hôte, échec d'authentification). Récupération : Vérifiez les détails de la connexion dans la configuration de l'environnement, assurez l'accès réseau et vérifiez les informations d'identification. ## Modes de défaillance et récupération Comprendre les modes de défaillance courants vous aide à réagir rapidement et à minimiser les temps d'arrêt. ### Le pipeline échoue immédiatement avec ClassNotFoundError Symptôme : Lors de l'exécution d'un pipeline, vous voyez une erreur comme : java.lang.ClassNotFoundException: com.mysql.jdbc.Driver Cause : Le pilote JDBC pour MySQL n'est pas dans le classpath. Récupération : - Téléchargez le fichier JAR du pilote JDBC MySQL depuis le site officiel. - Placez-le dans le répertoire lib de votre installation Hop. - Redémarrez Hop et exécutez à nouveau le pipeline. ### Le pipeline se bloque et ne se termine jamais Symptôme : Le pipeline démarre mais ne se termine pas, aucun message d'erreur. Causes possibles : Une transformation attend une entrée qui ne vient jamais, une ressource réseau est lente, ou il y a un blocage. Étapes de diagnostic : - Vérifiez l'utilisation du CPU et de la mémoire du processus Hop. - Regardez les journaux pour la dernière activité. - Utilisez jstack sur le processus Java pour obtenir un vidage de thread et identifier les threads bloqués. Commande pour le vidage de thread : jstack > threaddump.txt Analysez threaddump.txt pour les threads bloqués ou en attente. Récupération : Une fois la cause identifiée, terminez le pipeline (Ctrl+C ou kill) et corrigez le problème sous-jacent (par exemple, ajustez les délais d'attente, corrigez le flux de données). ### Le flux de travail échoue en raison d'une variable manquante Symptôme : Erreur comme : Variable ${my_var} is not defined Cause : La variable n'a pas été fournie via l'environnement ou le paramètre. Récupération : Assurez-vous que la variable est définie dans la configuration de l'environnement ou passez-la avec l'option -param . Exemple de passage de paramètre : hop -run -file my-pipeline.hpl -param my_var=value ### Récupération après un échec d'exécution de pipeline Si un pipeline échoue en cours de route, vous devrez peut-être redémarrer à partir d'un point de contrôle. Hop ne fait pas de point de contrôle automatiquement, mais vous pouvez concevoir des pipelines avec des transformations idempotentes (par exemple, en utilisant upsert au lieu d'insert). Procédure de récupération : - Identifiez l'étape où l'échec s'est produit à partir des journaux. - Déterminez si des données partielles ont été écrites. - Nettoyez les données partielles si nécessaire (en utilisant SQL ou d'autres moyens). - Réexécutez le pipeline après avoir corrigé la cause. ## Liste de contrôle des opérations Utilisez cette liste de contrôle pour vous assurer de suivre les meilleures pratiques pour l'exploitation d'Apache Hop. - [ ] Vérifier la version : Exécutez hop -version et assurez-vous qu'elle correspond aux attentes. - [ ] Vérifier Java : Exécutez java -version et confirmez la version prise en charge (11 ou 17 pour Hop 1.2.0). - [ ] Sauvegarder la configuration : Avant toute modification, archivez le répertoire config . - [ ] Tester la connexion : Si vous utilisez des ressources externes, testez la connectivité avant d'exécuter des pipelines complets. - [ ] Exécuter le pipeline d'abord dans un environnement de test : Utilisez un environnement dédié (par exemple, dev ) avant la production. - [ ] Surveiller les journaux : Suivez les journaux pendant l'exécution : tail -f logs/hop.log - [ ] Capturer les métriques : Utilisez -capture pour enregistrer les données de performance pour une analyse post-exécution. - [ ] Sécuriser les secrets : Ne codez jamais en dur les mots de passe ; utilisez des variables d'environnement ou des variables Hop. - [ ] Avoir un plan de retour en arrière : Sachez comment restaurer la configuration ou la version précédente du pipeline. - [ ] Documenter les incidents : Enregistrez les symptômes de défaillance, la cause et les étapes de récupération pour référence future. ## Conclusion Les commandes de base d'Apache Hop sont essentielles pour une gestion efficace des pipelines de données. En utilisant les commandes d'inventaire de version et d'environnement, vous établissez une base solide. Des pratiques de configuration sûres évitent les pannes accidentelles. La vérification et le diagnostic vous aident à confirmer le succès des exécutions et à identifier rapidement les problèmes. Comprendre les modes de défaillance et disposer de procédures de récupération minimise les temps d'arrêt. La liste de contrôle des opérations sert de référence rapide pour les tâches quotidiennes. Comme prochaine étape, choisissez une vérification à faible risque de cet article, comme vérifier la version de Hop ou sauvegarder votre configuration. Ensuite, exécutez un pipeline simple avec journalisation et capturez les métriques pour vous familiariser avec le flux de travail en ligne de commande. N'oubliez pas qu'un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision.