Surveillance et alertes Apache Hop : guide pratique d'implémentation

Apache Hop fait circuler les données à travers des pipelines et des workflows. Lorsqu'une exécution échoue ou ralentit, vous avez besoin d'un retour rapide et précis pour corriger ou annuler en toute sécurité. Ce guide montre comment surveiller Hop avec une approche minimale et à faible risque : commencez par des logs basés sur des fichiers, extrayez quelques métriques à fort signal, configurez des alertes simples, construisez un tableau de bord compact et vérifiez le tout avec des tests contrôlés. Vous obtiendrez des commandes pratiques, des exemples concrets et des étapes de récupération adaptables à votre environnement.

Idées clés que vous appliquerez :

• Concentrez-vous sur un petit pilote mesurable que vous pouvez inspecter localement avant d'étendre.
• Séparez la configuration, la collecte et l'alerte pour que chaque changement soit réversible.
• Surveillez la correction (succès/échec), la ponctualité (durée et respect de l'horaire) et la pression sur les ressources (débit de lignes, réessais, indices mémoire) avant d'ajouter des métriques exotiques.

Inventaire des versions et de l'environnement

Avant de modifier quoi que ce soit, capturez une base de référence pour que tous parlent du même système.

Prérequis

• Confirmez que vous pouvez exécuter des pipelines/workflows Hop depuis votre interface graphique Hop ou en ligne de commande sur l'hôte cible.
• Assurez-vous d'avoir un accès shell à l'hôte où Hop s'exécute et un accès en lecture à son répertoire de logs.
• Assurez-vous de pouvoir créer un nouveau répertoire pour les artefacts de surveillance (scripts, métriques analysées, logs de test).

Enregistrez les versions et la topologie

• Version de Hop et source de distribution (par exemple, l'archive tarball ou le paquet système installé).
• Version du runtime Java sur l'hôte qui exécute Hop.
• Système d'exploitation et version.
• Où Hop exécute les pipelines : hôte local uniquement, plusieurs hôtes avec un planificateur, ou via un serveur Hop.
• Emplacement(s) des logs : chemin de fichier utilisé par vos exécutions Hop ou wrappers de service.

Exemples de commandes de base (adaptez à votre système) :

# Version Java
java -version

# Détails de l'OS
uname -a

# Créer les répertoires pour les artefacts de surveillance
sudo mkdir -p /var/log/hop
sudo mkdir -p /opt/hop-monitoring/bin /opt/hop-monitoring/state
sudo chown -R "$USER" /opt/hop-monitoring

Définissez un périmètre pilote

• Choisissez un pipeline critique quotidien et un workflow de support. C'est suffisant pour valider l'approche et affiner les seuils.
• Décidez où stocker les métriques analysées pendant le pilote (par exemple, un fichier CSV local dans /opt/hop-monitoring/state). Vous pourrez l'alimenter dans n'importe quel outil de tableau de bord plus tard.

Quoi surveiller dans Apache Hop

Vous n'avez pas besoin de dizaines de métriques. Commencez avec un ensemble court à fort signal et ajustez au fil du temps.

Chemin de configuration sûr

Un chemin d'implémentation sûr garde le premier changement petit, visible et réversible.

1. Pilote sur seulement deux exécutables

• Choisissez un pipeline (par exemple, daily_load.hpl) et un workflow (par exemple, nightly_compact.hwf). Utilisez leurs vrais noms et chemins sur votre système.

1. Utilisez d'abord des logs basés sur des fichiers

• Assurez-vous que chaque exécution ajoute à un fichier de log daté dans /var/log/hop. Vous pouvez configurer vos scripts d'exécution ou wrappers de service pour rediriger stdout/stderr vers ce dossier. Conservez 14 jours de logs pour faciliter le dépannage.

1. Capturez quelques champs

• De chaque exécution, extrayez : statut (succès/échec), horodatages début/fin, durée en secondes, lignes entrantes/sortantes par transform clé, nombre de lignes ERROR, et compteurs de réessais (si présents dans le texte du log).

1. Gardez les seuils conservateurs au début

• Commencez avec des seuils d'alerte larges. Resserez-les seulement après avoir collecté au moins une semaine de données.

1. Rendez les changements réversibles

• Chaque nouvelle règle vit dans son propre fichier ou bloc pour pouvoir la désactiver sans toucher au reste du système.

1. Validez localement, puis planifiez

• Testez les scripts en exécutant un pipeline manuellement et en confirmant les métriques analysées. Ensuite seulement, appliquez à votre planificateur ou wrapper de service.

Collecte et alertes : exemples pratiques

Cette section utilise des exemples construits pour illustrer des motifs que vous pouvez adapter quel que soit votre format de log exact.

Exemple : motifs de log à analyser (construits)

Une exécution Hop typique expose des messages de cycle de vie clairs et des compteurs par transform. Votre formulation exacte peut différer, mais l'idée est constante.

2026/08/01 02:15:30 - pipeline - Pipeline daily_load started
2026/08/01 02:16:40 - transform OrdersInput - read: 120345 written: 120345
2026/08/01 02:16:50 - transform FilterBadRows - read: 120345 written: 120200 rejected: 145
2026/08/01 02:17:07 - pipeline - Pipeline daily_load finished (duration: 97 s)

Exemple d'échec (construit) :

2026/08/01 02:15:30 - pipeline - Pipeline daily_load started
2026/08/01 02:17:07 - transform OrdersOutput - ERROR: failed to write batch: timeout
2026/08/01 02:17:07 - pipeline - ERROR: Pipeline failed after 97 s (1 errors)

Analysez les signaux essentiels avec des outils shell

Utilisez des outils portables pour prouver le concept. Plus tard, vous pourrez les remplacer par vos collecteurs préférés.

Extrayez le statut global et la durée (chemin et motifs construits) :

#!/usr/bin/env bash
# /opt/hop-monitoring/bin/parse_hop_log.sh
# Usage: parse_hop_log.sh /var/log/hop/daily_load_2026-08-01.log

set -euo pipefail
LOG_FILE="$1"
NAME=$(basename "$LOG_FILE" .log)
START_TS=$(grep -m1 -E "Pipeline .* started|Workflow .* started" "$LOG_FILE" | awk '{print $1" "$2}')
END_OK=$(grep -m1 -E "Pipeline .* finished|Workflow .* finished" "$LOG_FILE" || true)
END_ERR=$(grep -m1 -E "ERROR: Pipeline failed|ERROR: Workflow failed" "$LOG_FILE" || true)
ERROR_COUNT=$(grep -E " ERROR: " "$LOG_FILE" | wc -l | tr -d ' ')
DURATION_SEC=$(grep -m1 -E "duration: [0-9]+ s|after [0-9]+ s" "$LOG_FILE" | grep -oE "[0-9]+" | head -1)

STATUS="unknown"
if [ -n "$END_ERR" ]; then STATUS="failed\); fi
if [ -n "$END_OK" ]; then STATUS="success\); fi

# Extrayez un indice simple de lignes traitées depuis un transform clé si présent
ROWS=$(grep -E "transform .* - read: [0-9]+" "$LOG_FILE" | tail -1 | grep -oE "read: [0-9]+" | awk '{print $2}')
: "${ROWS:=0}"""

# Émettez une ligne CSV pour les tableaux de bord
OUT="$(date +%Y-%m-%dT%H:%M:%S%z),$NAME,$STATUS,${DURATION_SEC:-0},$ERROR_COUNT,$ROWS"
echo "$OUT" | tee -a /opt/hop-monitoring/state/hop_runs.csv

# Émettez des signaux pour alertes via codes de sortie et stdout (consommés par le planificateur)
if [ "$STATUS" = "failed" ]; then
 echo "ALERT: $NAME failed in ${DURATION_SEC:-0}s with $ERROR_COUNT error lines"
 exit 2
fi
if [ "${DURATION_SEC:-0}" -gt 900 ]; then
 echo "ALERT: $NAME duration ${DURATION_SEC}s exceeds 15m threshold"
 exit 3
fi
if [ "$ROWS" = "0" ]; then
 echo "WARN: $NAME processed 0 rows"
 exit 0
fi

Notes

• Les motifs utilisent une formulation générique des exemples construits ci-dessus. Adaptez-les à vos lignes de log réelles.
• Le script ajoute un CSV à /opt/hop-monitoring/state/hop_runs.csv et imprime des messages d'alerte que votre planificateur ou wrapper peut récupérer.
• Les codes de sortie peuvent être mappés à différentes sévérités dans votre planificateur.

Branchez l'analyseur à vos exécutions

Si vous exécutez déjà les pipelines via un script wrapper, ajoutez une étape d'analyse après chaque exécution :

#!/usr/bin/env bash
# /usr/local/bin/run_daily_load.sh (exemple construit)
set -euo pipefail
LOG=/var/log/hop/daily_load_$(date +%F).log

# Exécutez Hop (remplacez par votre invocation réelle)
# Assurez-vous qu'il loggue vers "$LOG" et retourne non-zéro en cas d'échec
/path/to/hop-run.sh \
 --file=/opt/hop/projects/pipelines/daily_load.hpl \
 --logFile="$LOG" --logLevel=Detailed || true

# Analysez et émettez des alertes
/opt/hop-monitoring/bin/parse_hop_log.sh "$LOG"

Pour un planificateur qui supporte des hooks post-exécution, appelez l'analyseur dans ce hook avec le chemin du fichier de log spécifique.

Règles d'alerte qui fonctionnent dès le premier jour

Commencez avec trois catégories :

• Correction : toute exécution échouée.
• Ponctualité : exécution qui dépasse un seuil fixe ou dépasse significativement le P95 (percentile 95) sur 7 jours glissants.
• Exhaustivité : exécution qui traite zéro ligne alors qu'elle en traite normalement plus.

Tableaux de bord et KPIs

Les tableaux de bord rendent les alertes actionnables en ajoutant le contexte de tendance. Comme l'analyseur écrit en CSV, vous pouvez le grapher dans n'importe quel outil de visualisation.

Panneaux recommandés pour commencer

• Taux de succès (7 jours et 30 jours) par pipeline/workflow.
• Tendance de durée par exécution, avec lignes de référence pour médiane et P95.
• Lignes traitées par exécution, signalant les valeurs sous un plancher.
• Nombre d'alertes par type dans le temps (échec, lent, zéro ligne).

Panneaux optionnels à mesure que vous mûrissez

• Compteurs lu/écrit par transform pour les 3 transforms les plus volumineux.
• Compteurs de réessai/backoff par système cible (par exemple, entrepôt de données, objet store, API).
• Respect de l'horaire : nuage de points horaire planifié vs réel.

Guidance KPI (nombres construits; ajustez après une semaine de données)

• Taux de succès : maintenez >= 99 % pour les exécutions quotidiennes critiques.
• Durée : cible médiane dans les 10 % semaine sur semaine; alerte sur > 25 % au-dessus du P95.
• Tolérance zéro ligne : 0 occurrences en jours ouvrés pour sources critiques; exceptions documentées le week-end.

Vérification et diagnostics

La vérification prouve que votre surveillance fonctionne et isole les lacunes avant d'en dépendre.

1. Vérification du chemin nominal

• Exécutez votre pipeline pilote une fois. Confirmez que :
• Un nouveau fichier de log apparaît dans /var/log/hop.
• L'analyseur ajoute une ligne CSV à /opt/hop-monitoring/state/hop_runs.csv.
• Aucune alerte ne se déclenche pour une exécution réussie et ponctuelle.

1. Vérification du chemin d'échec (construit)

• Injectez un échec contrôlé (par exemple, mal configurez temporairement un chemin cible) et relancez.
• Confirmez que :
• Le log contient une ligne ERROR.
• L'analyseur imprime une ligne ALERT et sort avec le code 2.
• Votre planificateur ou wrapper enregistre la sortie non-zéro et route le message d'alerte.

1. Vérification du chemin lent (construit)

• Insérez un sleep artificiel dans un transform ou entre étapes pour dépasser le seuil de 15 minutes.
• Confirmez qu'une alerte de durée s'imprime et que le code de sortie est 3.

1. Vérification du chemin exhaustivité

• Configurez une exécution avec un filtre d'entrée qui ne correspond à aucune ligne.
• Confirmez que l'analyseur imprime une ligne WARN avec ROWS==0.

1. Diagnostics si les vérifications échouent

• Si le CSV est vide : vérifiez les permissions sur /opt/hop-monitoring/state et assurez-vous que le chemin de l'analyseur est correct.
• Si les logs manquent : assurez-vous que votre invocation d'exécution écrit dans le fichier et répertoire de log attendus.
• Si les durées sont à zéro : ajustez la regex dans l'analyseur pour correspondre à votre formulation de log réelle.

Modes de défaillance et récupération

Planifiez pour ces problèmes courants et gardez les étapes de restauration prêtes.

1. Alertes bruyantes

• Symptôme : rafales d'alertes pour la même cause racine.
• Causes probables : intervalles de réessai courts, règles d'alerte sur erreurs transitoires, seuils trop serrés.
• Récupération : implémentez une limite de taux de 30 minutes, élargissez les seuils de 20 %, désactivez la règle la plus bruyante pendant 24h en investiguant la cause racine.

1. Dérive d'analyse

• Symptôme : l'analyseur arrête d'extraire la durée ou les lignes après une mise à jour Hop ou un changement de format de log.
• Causes probables : la formulation des messages a changé.
• Récupération : capturez un échantillon de log frais, mettez à jour les regex dans parse_hop_log.sh, et redéployez. Gardez le script précédent comme parse_hop_log.sh.bak pour restauration.

1. Logs manquants ou rotatifs

• Symptôme : l'analyseur s'exécute mais ne trouve aucune ligne; les alertes ne se déclenchent pas.
• Causes probables : chemin de log changé; rotation a déplacé les fichiers avant analyse.
• Récupération : alignez l'analyseur sur le nouveau chemin; analysez les logs à la fin plutôt qu'en tail; augmentez la rétention à 14 jours; validez la propriété et les permissions.

1. Exécutions longues ou bloquées

• Symptôme : la durée augmente sans erreurs; aucune ligne de fin n'apparaît dans les logs.
• Causes probables : lenteur amont, deadlock, ou attente d'entrée.
• Récupération : introduisez une alerte de durée maximale (par exemple, 2x P95); capturez des indices de thread ou d'activité depuis les dernières lignes du log; mettez en pause les dépendants en aval; si sûr, arrêtez l'exécution et redémarrez depuis le dernier point idempotent.

1. Pression sur les ressources de l'environnement

• Symptôme : échecs sporadiques; erreurs référençant la mémoire, les descripteurs de fichiers, ou les timeouts.
• Causes probables : contention sur hôte partagé; mémoire JVM insuffisante; limites de descripteurs basses.
• Récupération : planifiez les exécutions lourdes en hors pointe; augmentez la mémoire prudemment et testez; augmentez les limites de descripteurs; ajoutez un backoff entre transforms lourds.

1. Mauvais paramètres ou horaires

• Symptôme : zéro ligne ou sorties vides inattendues.
• Causes probables : mauvais paramètre de date; décalage d'horaire avec la disponibilité de la source.
• Récupération : recoupez les valeurs de paramètres loguées au début; alignez l'horaire sur la fin du système source; ajoutez une clause de garde pour annuler quand la source est connue vide.

Guidance de restauration

• Restauration de l'analyseur : gardez le script précédent et un lien symbolique. Si un changement casse l'analyse, remettez le lien symbolique et relancez les étapes de vérification.
• Restauration des règles d'alerte : stockez chaque seuil dans un fichier séparé ou bloc clairement étiqueté pour pouvoir le désactiver d'un seul changement. Documentez les valeurs de base par défaut et quand elles ont été modifiées pour la dernière fois.
• Restauration du pipeline : maintenez des fichiers pipeline/workflow versionnés; si une release introduit du bruit ou des échecs, revenez à la dernière version connue bonne et relancez la vérification.

Liste de contrôle opérationnelle

Utilisez cette liste concise chaque semaine et pendant les incidents.

Hygiène quotidienne/hebdomadaire

• Revoyez les panneaux du tableau de bord pour les régressions de durée et anomalies zéro ligne.
• Scannez le volume d'alertes; limitez le taux des alertes répétitives et ajustez les seuils qui causent du bruit.
• Confirmez que la rétention /var/log/hop et l'utilisation disque sont dans les limites.
• Validez que /opt/hop-monitoring/state/hop_runs.csv se met à jour quotidiennement.

Avant de changer les seuils

• Notez les valeurs de base actuelles et le P95 récent.
• Appliquez les changements à un seul pipeline d'abord; gardez une note de restauration.
• Revérifiez avec une exécution contrôlée.

Pendant un incident

• Lisez le premier ERROR et les 50 dernières lignes du log pour l'exécution en échec.
• Classifiez : correction (échec), ponctualité (lent), exhaustivité (lignes vides), ou pression ressources.
• Choisissez correction en avant vs restauration; si restauration, identifiez la dernière version connue bonne et revenez-y.
• Après résolution, mettez à jour les annotations du tableau de bord et les notes d'alerte.

Revue mensuelle

• Recaculiez les durées typiques et planchers de lignes traitées; ajustez les seuils par petits incréments.
• Retirez les règles qui ne se déclenchent jamais; ajoutez au maximum une nouvelle métrique par mois pour éviter la complexité rampante.

Conclusion

Vous avez maintenant une façon pragmatique et à faible risque de surveiller Apache Hop :

• Un pilote étroit utilisant des logs basés sur fichiers et un petit ensemble de métriques à fort signal.
• Un analyseur simple qui extrait le statut, la durée, les lignes d'erreur et les lignes traitées.
• Des règles d'alerte de base pour la correction, la ponctualité et l'exhaustivité.
• Des tableaux de bord qui suivent les taux de succès, les durées et les tendances de volume.
• Des étapes de vérification et des playbooks de récupération pour les modes de défaillance courants.

Étendez cette fondation avec soin : intégrez avec vos plateformes d'alerte et de tableau de bord préférées, ajoutez des métriques par transform pour les chemins critiques, et resserrez les seuils seulement après avoir rassemblé des données de tendance. Gardez les changements réversibles, validez toujours localement d'abord, et documentez les exceptions pour que les équipes puissent répondre rapidement et en toute confiance.