Concepts avancés d'Apache Hop : guide opérationnel pratique

Introduction

Apache Hop (Hop Orchestration Platform) est une plateforme open source d'orchestration et d'ingénierie de données construite sur la base de code de Kettle. Elle permet aux équipes de concevoir, planifier et surveiller visuellement des pipelines et des workflows ETL. Cet article aborde les concepts avancés dont les ingénieurs ont besoin une fois qu'ils dépassent les bases du glisser-déposer : comment Hop est structuré, comment les pipelines et les workflows se comportent, comment l'injection de métadonnées et les variables fonctionnent, comment configurer la journalisation et la gestion des erreurs, et comment exploiter Hop en toute sécurité en production.

Ce guide combine une plongée conceptuelle avec des exemples concrets, prêts à être copiés-collés. Chaque section explique un domaine de l'architecture de Hop, puis montre comment vérifier, tester ou modifier le comportement concerné. Chaque commande inclut des vérifications de version explicites, des observations en lecture seule avant les modifications et des étapes de récupération. L'accent est mis sur des opérations sûres : connaître votre état actuel, limiter l'impact des changements et vérifier les résultats.

Bien qu'Apache Airflow, NiFi et des outils similaires soient parfois comparés à Hop, cet article ne les mentionne que lorsqu'ils affectent les décisions de compatibilité, de sécurité ou de migration.

Inventaire de version et d'environnement

Pourquoi c'est important

Avant d'apporter toute modification, vous avez besoin d'un inventaire précis de votre installation Hop : la version, le mode de déploiement et l'organisation des pipelines. Cela réduit le risque d'appliquer une documentation ou des commandes destinées à une version différente. Le comportement de Hop peut changer entre les versions, notamment en ce qui concerne l'API REST, le chargement des plugins et le composant hop-server.

Commandes en lecture seule

Commencez par ces vérifications en lecture seule :

# 1. Version de Hop
hop-conf --version
# Exemple de sortie attendue : 2.1.0

# 2. Répertoire d'installation de Hop
hop-conf --hop-home
# Exemple de sortie attendue : /opt/hop

# 3. Variables d'environnement
hop-conf --environment
# Liste les environnements configurés, tels que développement, production

Si la commande hop-conf n'est pas dans votre PATH, exécutez-la depuis le répertoire d'installation de Hop :

cd /opt/hop
./hop-conf --version

Pour les installations exécutées en tant que service, inspectez la définition du service :

# Linux (systemd)
systemctl cat hop
# Affiche le fichier de service, y compris ExecStart et le fichier d'environnement

La sortie indique la version de Java utilisée par Hop, les paramètres de mémoire et le répertoire de travail. Notez ces valeurs avant tout changement.

Topologie de déploiement

Hop peut fonctionner selon trois modes principaux :

• Local (client lourd) : Vous exécutez hop-gui ou hop-run directement sur une machine. Convient au développement.
• Moteur distant (hop-server) : Un serveur à longue durée de vie exécute des pipelines et des workflows soumis par un client ou via REST.
• Cluster : Plusieurs serveurs Hop coordonnés par un gestionnaire de cluster léger (souvent ZooKeeper) pour une exécution distribuée.

Chaque mode a des prérequis et des modes de défaillance différents. Par exemple, l'absence du binaire hop-server sur le client signifie que vous ne pouvez pas soumettre d'exécutions distantes, mais ce binaire n'est pas nécessaire si vous exécutez uniquement en local.

Exemple de plus petit changement justifié

Supposons que vous découvriez que votre serveur Hop de production exécute la version 2.0.0, mais que les exemples documentés nécessitent des fonctionnalités de la version 2.1.0. Avant de mettre à niveau, capturez l'état actuel :

# Enregistrer les plugins installés
hop-conf --plugins > hop_plugins_avant.txt

# Enregistrer la configuration actuelle du serveur
cp /opt/hop/config/hop-server.xml /opt/hop/config/hop-server.xml.backup

Ensuite, mettez à niveau uniquement le binaire du serveur, en conservant la sauvegarde de configuration. Après la mise à niveau, vérifiez :

hop-conf --version
# Attendu : 2.1.0

# Vérifier que les plugins requis sont toujours présents
hop-conf --plugins | grep "Apache Hop Transform"

Si la vérification de version échoue ou qu'un plugin est manquant, restaurez à partir de la sauvegarde et examinez la procédure de mise à niveau.

Chemin de configuration sûr

Fichiers de configuration principaux

La configuration de Hop se trouve dans plusieurs fichiers XML :

• config/hop-config.xml : Propriétés globales, paramètres de journalisation.
• config/hop-server.xml : Paramètres du serveur distant (hôte, port, authentification).
• config/environments.xml : Définit les variables spécifiques à l'environnement.
• config/projects.xml : Répertoires d'accueil des projets.

Un concept avancé est la séparation des environnements. Ne codez jamais en dur les identifiants de base de données ou les chemins de fichiers dans les pipelines. Définissez-les plutôt comme des variables dans un environnement et référencez-les avec ${NOM_VARIABLE}.

Exemple : Connexion de base de données sûre pour l'environnement

Créez un nouvel environnement appelé production :

hop-conf --environment-create production

Modifiez le fichier d'environnement (généralement config/environments/production.json) et ajoutez des variables :

{
  "DB_HOST": "db.internal.example",
  "DB_PORT": "5432",
  "DB_NAME": "warehouse",
  "DB_USER": "etl_user",
  "DB_PASSWORD": "remplacer_par_un_espace_reserve_secret"
}

Dans votre pipeline, créez une connexion PostgreSQL avec ces paramètres :

• Hôte : ${DB_HOST}
• Port : ${DB_PORT}
• Base de données : ${DB_NAME}
• Nom d'utilisateur : ${DB_USER}
• Mot de passe : ${DB_PASSWORD}

Lorsque vous exécutez le pipeline, activez l'environnement :

hop-run -e production -f /chemin/vers/pipeline.hpl

Cela empêche le déploiement accidentel d'identifiants de développement en production. Utilisez toujours un gestionnaire de secrets ou une injection de variables d'environnement pour les mots de passe réels ; ne validez pas le fichier d'environnement dans le contrôle de version s'il contient des secrets en texte clair.

Tester les modifications de configuration

Avant de modifier un fichier de configuration de production, testez-le sur une instance copiée. Par exemple, pour tester un nouveau niveau de journalisation :

# Copier la configuration d'origine
cp config/hop-config.xml config/hop-config.xml.backup
# Modifier le niveau de journalisation dans la copie (par exemple, de INFO à DEBUG)
# Exécuter Hop avec la configuration modifiée
hop-run -c config/hop-config-test.xml -f /chemin/vers/pipeline_test.hpl
# Vérifier la sortie du journal
hop-log-viewer

Si le test se comporte comme prévu, promouvez la configuration. Sinon, restaurez la sauvegarde.

Vérification et diagnostics

Métriques de pipeline et journaux

Hop enregistre les métriques d'exécution dans sa base de données ou ses fichiers journaux. Pour diagnostiquer une transformation lente, vous devez voir des métriques telles que les lignes lues, écrites et les compteurs d'erreurs par étape.

Activez les métriques d'étape dans votre pipeline :

1. Cliquez avec le bouton droit sur une étape de transformation et sélectionnez Métriques.
2. Choisissez les métriques dont vous avez besoin (par exemple, LinesInput, LinesOutput, LinesRejected, Errors).
3. Enregistrez et exécutez le pipeline.
4. Après l'exécution, ouvrez l'onglet Métriques dans l'interface graphique de Hop pour voir les chiffres par étape.

Vous pouvez également utiliser la ligne de commande pour capturer les métriques :

hop-run -f /chemin/vers/pipeline.hpl -l /chemin/vers/metrics.log

Le fichier journal contient des lignes comme :

2023/09/01 12:00:01 - Table output.0 - Finished processing (I=1000, O=1000, R=0, W=1000, U=0, E=0)

Ici, I, O, R, W, U, E représentent respectivement les lignes en entrée, en sortie, rejetées, écrites, mises à jour et en erreur. Si E (erreurs) est supérieur à zéro, inspectez les lignes en erreur via l'étape de gestion des erreurs.

Utilisation de Hop Server pour les diagnostics à distance

Si les pipelines s'exécutent à distance, activez les diagnostics de hop-server :

hop-server -h localhost -p 8080 -u cluster -p secret -l /chemin/vers/server.log

Ensuite, interrogez le serveur via son API REST :

# Obtenir le statut du serveur
curl -u cluster:secret http://localhost:8080/hop/status/
# Sortie attendue : JSON avec le statut "running" et la liste des pipelines

# Obtenir les détails de la dernière exécution
curl -u cluster:secret http://localhost:8080/hop/executions/?name=mon_pipeline

Utilisez ces points de terminaison en lecture seule avant de modifier un pipeline en cours d'exécution.

Diagnostic des erreurs courantes

Erreur : Transformation introuvable

Vérifiez le chemin du fichier et son extension. Hop attend .hpl pour les pipelines et .hwf pour les workflows.

ls -l /chemin/vers/votre_pipeline.hpl
# Si le fichier existe, vérifiez les références du projet
hop-conf --projects
# Assurez-vous que le projet pointe vers le bon répertoire

Erreur : Échec de connexion à la base de données

Testez la connectivité à l'aide de l'explorateur de base de données de Hop :

hop-db-explorer -j jdbc:postgresql://db.example:5432/warehouse -u etl_user -p secret -t "SELECT 1"

Si cela échoue, vérifiez l'accès réseau et les identifiants. Ne modifiez pas les paramètres de connexion du pipeline avant d'avoir confirmé que la base de données est accessible.

Modes de défaillance et récupération

Comprendre l'architecture de gestion des erreurs de Hop

Hop distingue les erreurs de pipeline (une transformation ne parvient pas à traiter les lignes) des erreurs de workflow (une action de tâche échoue). Comprendre cela est essentiel pour concevoir la récupération.

Dans un pipeline, vous pouvez attacher une étape de gestion des erreurs à n'importe quelle transformation. Lorsque la transformation rencontre une erreur, les lignes problématiques sont envoyées à l'étape de gestion des erreurs au lieu d'arrêter tout le pipeline.

Exemple : Une étape Table Input lit depuis une base de données. Nous attachons une étape Text File Output comme gestionnaire d'erreurs pour écrire les lignes rejetées.

Configuration :

1. Sélectionnez l'étape Table Input.
2. Dans ses propriétés, allez dans l'onglet Gestion des erreurs.
3. Définissez l'étape cible sur l'étape Text File Output.
4. Définissez éventuellement la limite d'erreurs (par exemple, arrêter après 100 erreurs).
5. Dans l'étape Text File Output, définissez les champs pour le message d'erreur, le code d'erreur et les données de ligne d'origine.

Lorsque vous exécutez le pipeline, les lignes qui échouent aux contraintes de base de données ou aux conversions de types de données sont détournées vers le fichier texte. Le pipeline continue de traiter les autres lignes.

Gestion des erreurs de workflow

Les workflows exécutent des actions en séquence ou en parallèle. Par défaut, une action échouée arrête le workflow. Pour exécuter des actions de récupération, utilisez des étapes Hop Action comme Abort, Mail ou Write To Log.

Exemple de workflow :

• Démarrer -> Exécuter le pipeline (ETL) -> Succès : Envoyer un e-mail -> Terminé
• Si l'exécution du pipeline échoue -> Écrire dans le journal (détails de l'erreur) -> Abandonner

Pour implémenter une exécution conditionnelle, cliquez avec le bouton droit sur la connexion et définissez la condition Résultat (par exemple, Success, Failure, Always).

Nouvelle tentative automatique

Certaines actions prennent en charge la nouvelle tentative. Pour une connexion de base de données, vous pouvez définir un nombre de tentatives et un intervalle d'attente dans les propriétés de l'action. Cependant, les nouvelles tentatives ne remplacent pas une gestion des erreurs appropriée ; concevez toujours pour un échec gracieux et une notification.

Commandes de récupération

Si un pipeline échoue en cours d'exécution, récupérez en vérifiant son journal :

hop-log-viewer -f /chemin/vers/pipeline.log

Identifiez l'étape défaillante et le message d'erreur. Corrections courantes :

• Mémoire insuffisante : Augmentez le tas Java dans hop-config.xml (par exemple, -Xmx4g).
• Lignes de base de données verrouillées : Attendez ou tuez la session bloquante.
• Table déjà existante : Supprimez ou renommez la table cible, ou modifiez le pipeline pour utiliser la troncature ou la mise à jour.

Redémarrez le pipeline après la correction. Utilisez les points de contrôle pour les très grands pipelines : ajoutez une étape Checkpoint entre les sections principales. Si le pipeline échoue après le point de contrôle, vous pouvez reprendre à partir des fichiers de point de contrôle au lieu de recommencer à zéro.

Pièges courants et comment les éviter

1. Exécution avec le mauvais environnement

Pourquoi cela arrive : Les développeurs ont souvent plusieurs environnements (développement, test, production). Oublier de spécifier -e ou sélectionner le mauvais environnement dans l'interface graphique conduit à écrire des données dans la mauvaise base de données.

Comment éviter : Dans l'interface graphique de Hop, vérifiez l'indicateur d'environnement dans la barre supérieure avant d'exécuter. Dans les scripts, passez toujours -e <environnement> explicitement. Envisagez d'utiliser des installations ou des projets Hop distincts pour chaque environnement.

Récupération : Arrêtez immédiatement le pipeline. Vérifiez la base de données cible pour les lignes insérées dans le mauvais environnement. Utilisez la sauvegarde ou les journaux de transactions pour les supprimer ou les corriger si possible.

2. Ignorer la portée des variables

Pourquoi cela arrive : Les variables peuvent être définies aux niveaux système, environnement, pipeline et workflow. Les règles de précédence ne sont pas toujours évidentes ; une variable de niveau pipeline peut remplacer une variable d'environnement involontairement.

Comment éviter : Documentez clairement les variables et utilisez une convention de nommage comme ENV_DB_HOST. Dans les propriétés du pipeline, examinez les variables et les paramètres avant l'exécution. Utilisez l'étape Set Variables avec prudence, car elle modifie l'espace des variables pour tout le pipeline.

Récupération : Si des variables inattendues provoquent une corruption des données, arrêtez l'exécution et vérifiez le journal pour les valeurs des variables au démarrage. Corrigez la définition de la variable et réexécutez.

3. Négliger la complexité de l'injection de métadonnées

Pourquoi cela arrive : L'injection de métadonnées est puissante mais peut produire des erreurs déroutantes lorsque les métadonnées injectées ne correspondent pas aux attentes de l'étape cible. Par exemple, injecter un nom de champ qui n'existe pas dans l'étape cible.

Comment éviter : Commencez avec une étape modèle simple et n'injectez que les champs nécessaires. Testez avec un petit ensemble de données. Utilisez l'onglet Métadonnées pour voir les métadonnées réellement transmises.

Récupération : Si l'injection échoue, examinez le journal des erreurs pour voir quel élément de métadonnées a causé l'échec. Ajustez le mappage d'injection et réessayez.

4. Négliger la configuration de la journalisation

Pourquoi cela arrive : La journalisation par défaut peut ne pas capturer suffisamment de détails pour une analyse post-mortem, ou elle peut capturer trop de données sensibles et remplir l'espace disque.

Comment éviter : Définissez des niveaux de journalisation appropriés par package dans hop-config.xml. Par exemple, définissez org.apache.hop sur INFO, mais votre propre package sur DEBUG. Utilisez la rotation des journaux.

Récupération : Si les journaux sont insuffisants, augmentez temporairement la journalisation à DEBUG et réexécutez le pipeline défaillant. Soyez conscient de l'impact sur les performances et de l'exposition des données sensibles.

5. Modifier les pipelines de production sans contrôle de version

Pourquoi cela arrive : Les pipelines Hop sont des fichiers XML. Sans contrôle de version, les modifications sont perdues et le retour en arrière est impossible.

Comment éviter : Stockez tous les fichiers .hpl, .hwf et d'environnement dans un dépôt Git. Utilisez des branches pour les modifications et exigez une révision avant la fusion en production. Hop peut s'intégrer à Git via des plugins ou des scripts externes.

Récupération : Si une mauvaise modification est déployée, extrayez la version précédente du fichier de pipeline et rechargez-la dans Hop.

Liste de vérification des opérations

Utilisez cette liste de vérification avant et après toute opération sur une installation ou un pipeline Hop. Attribuez un responsable unique pour chaque élément ; le responsable doit être un ingénieur qui comprend le domaine spécifique. Révisez cette liste au moins mensuellement, ou immédiatement après un incident.

Chaque responsable est chargé d'exécuter la vérification et de lancer l'action de récupération si le résultat attendu n'est pas atteint. La liste de vérification doit être intégrée à votre système de surveillance lorsque cela est possible (par exemple, via des tâches cron ou des workflows Hop).

Conclusion

Apache Hop offre un riche ensemble de fonctionnalités pour construire des pipelines de données robustes. Les concepts avancés abordés ici — contrôle de version, séparation des environnements, injection de métadonnées, gestion des erreurs et récupération — sont essentiels pour la fiabilité en production. En suivant une approche disciplinée consistant à observer avant de modifier, à limiter le rayon d'impact et à vérifier chaque étape, vous pouvez éviter les pièges courants et maintenir vos flux de données fluides.

Commencez par une seule action à faible risque : exécutez hop-conf --version et hop-conf --environment sur votre serveur de production. Enregistrez la sortie. Choisissez ensuite un pipeline et vérifiez qu'il dispose d'une gestion des erreurs appropriée. Utilisez la liste de vérification pour attribuer les responsabilités et suivre les améliorations. Au fil du temps, ces habitudes construiront une base opérationnelle solide pour vos déploiements Hop.