Dépannage d'Apache Airflow : guide pratique de terrain avec commandes, journaux et récupération

Introduction

Lorsqu'un pipeline Apache Airflow tombe en panne à 2 heures du matin, la différence entre une résolution en 15 minutes et une intervention de 10 heures tient à une seule chose : avoir une approche structurée pour l'observation, le diagnostic et la récupération. Ce guide fournit des techniques de dépannage pratiques et concrètes pour Apache Airflow, couvrant à la fois la série 2.x héritée et la nouvelle architecture 3.x.

Nous nous concentrerons sur les points de défaillance les plus courants : le scheduler, les workers, la base de données de métadonnées, les fichiers DAG et la configuration d'Airflow. Pour chaque domaine, vous trouverez des commandes de diagnostic en lecture seule, des signatures d'erreur concrètes et des correctifs minimaux et réversibles. L'objectif n'est pas seulement de résoudre le problème actuel, mais de construire un flux de travail de diagnostic reproductible qui réduit le temps moyen de récupération (MTTR).

Airflow 3 a introduit des changements architecturaux significatifs, notamment un serveur API et un processeur de DAG séparés. Les commandes et les points de terminaison de santé diffèrent entre les versions, ce guide signale donc les différences spécifiques à chaque version lorsque cela est important. Nous supposons que vous avez un accès en ligne de commande à l'environnement Airflow et des autorisations suffisantes pour exécuter des commandes de diagnostic et consulter les journaux.

Inventaire des versions et de l'environnement

Avant de toucher à quoi que ce soit, établissez une image claire du déploiement. Connaître la version exacte, l'exécuteur et la topologie vous évite d'appliquer des conseils destinés à une configuration différente.

Commencez par l'inventaire de la version et des composants :

airflow version

Exemple de sortie :

3.1.0

Si vous êtes sur Airflow 3, notez que la sortie de airflow version ne vous indique que la version du cœur. Les fournisseurs ont leur propre version. Vérifiez les fournisseurs avec :

airflow providers list

Cette commande génère un tableau des fournisseurs installés et de leurs versions. Les versions de fournisseurs incompatibles sont une source fréquente d'erreurs énigmatiques, surtout après une mise à niveau du cœur d'Airflow.

Ensuite, déterminez l'exécuteur et la base de données de métadonnées :

airflow config get-value core executor
airflow config get-value database sql_alchemy_conn

Pour Airflow 3, la configuration de la base de données peut se trouver sous database plutôt que core. Vous pouvez également inspecter la configuration complète avec airflow config list, mais soyez prudent : cette commande peut exposer des secrets. Utilisez airflow config list --include-examples uniquement dans un environnement sûr, ou masquez les valeurs sensibles avant de les partager.

Documentez la topologie du déploiement : s'agit-il d'une configuration à nœud unique, d'un cluster multi-nœuds avec l'exécuteur Celery ou Kubernetes, ou d'un service géré comme Astronomer ou MWAA ? Notez comment le scheduler, les workers, le serveur web et le processeur de DAG sont déployés (bare metal, Docker, Kubernetes). Cet inventaire guidera vos étapes de dépannage.

Pour les mises à niveau, en particulier d'Airflow 2 à 3, consultez le guide de migration officiel. Les principaux changements cassants incluent la suppression du processeur de DAG autonome dans le scheduler, le nouveau serveur API et les modifications du schéma de configuration. Ne tentez jamais une mise à niveau sans une sauvegarde de la base de données de métadonnées :

airflow db backup

Airflow 2.7+ fournit cette commande. Pour les versions plus anciennes, utilisez l'outil de sauvegarde natif de votre base de données (par exemple, pg_dump pour PostgreSQL). Après la sauvegarde, testez la migration sur un environnement de pré-production avec des DAG représentatifs avant de toucher à la production.

Chemin de configuration sûr

Les erreurs de configuration sont parmi les plus faciles à introduire et les plus difficiles à repérer. Une simple faute de frappe dans airflow.cfg ou une variable d'environnement peut faire tomber le scheduler ou faire en sorte que les tâches se comportent silencieusement de manière incorrecte. Le chemin de configuration sûr est une discipline : observer, changer une chose, vérifier et savoir comment revenir en arrière.

Inspection de la configuration en lecture seule

Ne modifiez jamais aveuglément les fichiers de configuration. D'abord, voyez la configuration effective actuelle :

airflow config list

Cela imprime tous les paramètres de la configuration active, y compris les remplacements provenant de variables d'environnement. Pour vérifier un paramètre spécifique sans tout vider :

airflow config get-value core dags_folder

Pour Airflow 3, certaines sections ont été renommées. Par exemple, les paramètres du processeur de DAG sont passés de scheduler à dag_processor. Si get-value se plaint d'une section manquante, consultez la référence de configuration actuelle pour votre version.

Changements minimaux et justifiés

Lorsque vous devez modifier un paramètre, effectuez le plus petit changement possible et documentez-le. Par exemple, si le processeur de DAG ne récupère pas les nouveaux DAG, vous devrez peut-être ajuster dag_dir_list_interval. Au lieu de deviner, vérifiez la valeur actuelle :

airflow config get-value scheduler dag_dir_list_interval

Ensuite, définissez une nouvelle valeur uniquement si cela est justifié. Dans Airflow 3, ce paramètre est déplacé vers dag_processor :

airflow config get-value dag_processor dag_dir_list_interval

Si vous devez le modifier, utilisez une variable d'environnement limitée au composant concerné plutôt que de modifier le fichier global airflow.cfg. Par exemple :

export AIRFLOW__DAG_PROCESSOR__DAG_DIR_LIST_INTERVAL=60

Cela limite le rayon d'impact et rend le changement visible dans l'environnement.

Gestion des secrets

Ne mettez jamais de secrets dans airflow.cfg ou dans le code des DAG. Airflow prend en charge les backends de secrets et les variables d'environnement. Si vous voyez une chaîne de connexion avec des identifiants intégrés dans la configuration, remplacez-la par une référence à un backend de secrets. Par exemple, dans airflow.cfg :

[database]
sql_alchemy_conn = postgresql+psycopg2://airflow:${AIRFLOW_DB_PASSWORD}@postgres/airflow

Ensuite, définissez AIRFLOW_DB_PASSWORD dans l'environnement. Airflow développera la variable à l'exécution. Pour les connexions, utilisez le préfixe AIRFLOW_CONN_, par exemple, AIRFLOW_CONN_MY_DB=postgres://user:pass@host:5432/db. Cela évite de coder en dur les secrets.

Vérifier après le changement

Après tout changement de configuration, redémarrez uniquement le composant concerné et vérifiez qu'il est sain avant de crier victoire. Par exemple, si vous avez modifié un paramètre du scheduler, redémarrez le scheduler :

# Dans une configuration systemd
sudo systemctl restart airflow-scheduler

Ensuite, vérifiez :

airflow jobs check --job-type SchedulerJob --hostname $(hostname)

Dans Airflow 3, vous pouvez également interroger le point de terminaison de santé du serveur API. Plus à ce sujet dans la section suivante.

Vérification et diagnostics

Un dépannage efficace repose sur des contrôles de santé fiables et une analyse des journaux. Airflow expose plusieurs points de terminaison et commandes pour évaluer la santé des composants sans rien changer.

Contrôles de santé pour Airflow 3

Dans Airflow 3, le serveur API fournit un point de terminaison de santé détaillé :

curl -s http://localhost:8080/api/v2/monitor/health

Exemple de réponse (tronquée pour plus de clarté) :

{
  "metadatabase": {"status": "healthy"},
  "scheduler": {"status": "healthy", "latest_scheduler_heartbeat": "2025-01-15T10:30:00Z"},
  "triggerer": {"status": "healthy"},
  "dag_processor": {"status": "healthy"}
}

Ne vous fiez pas uniquement au code HTTP 200. Le corps de la réponse contient l'état de chaque sous-composant. Si metadatabase est malsain, le serveur API peut toujours renvoyer 200 car le processus du serveur API est en cours d'exécution.

Pour Airflow 2, le point de terminaison de santé équivalent est /health, qui renvoie un JSON simple avec l'état de metadatabase et scheduler. Cependant, le point de terminaison d'Airflow 3 est plus complet.

Contrôles de santé en ligne de commande

Airflow fournit des commandes ciblées pour vérifier des composants spécifiques :

airflow jobs check --job-type SchedulerJob --hostname $(hostname)

Cette commande se termine avec le code 0 si le scheduler a envoyé un battement de cœur récemment. Vous pouvez également vérifier le triggerer :

airflow jobs check --job-type TriggererJob --hostname $(hostname)

Pour la connectivité de la base de données de métadonnées :

airflow db check

Cela effectue une requête simple sur la base de données et signale le succès ou l'échec. En cas d'échec, vérifiez la chaîne de connexion à la base de données, l'accès réseau et les identifiants.

Principes fondamentaux de l'analyse des journaux

Les journaux Airflow sont votre principale ressource de diagnostic. Les journaux du scheduler se trouvent généralement dans $AIRFLOW_HOME/logs/scheduler/latest/. Les journaux du serveur web sont dans $AIRFLOW_HOME/logs/webserver/. Pour les déploiements Docker, utilisez docker logs <nom_du_conteneur>.

Les journaux des instances de tâche sont stockés dans $AIRFLOW_HOME/logs/dag_id=<dag_id>/run_id=<run_id>/task_id=<task_id>/attempt=<attempt>.log. Vous pouvez également les consulter depuis l'interface utilisateur. Lorsqu'une tâche échoue, regardez d'abord le journal de la tâche pour les traces Python ou les erreurs d'application. Si le journal est vide ou manquant, la tâche a peut-être échoué avant le début de la journalisation, ce qui indique un problème d'infrastructure (par exemple, un crash du worker, une mise à mort OOM).

Utilisez grep pour filtrer les gros journaux :

grep -i "error" $AIRFLOW_HOME/logs/scheduler/latest/*.log | tail -50

Pour la journalisation à distance (S3, GCS), assurez-vous que la configuration des journaux est correcte et que les identifiants sont valides. Les échecs de journalisation à distance apparaissent souvent comme Could not read remote logs dans l'interface utilisateur.

Problèmes d'analyse des DAG

Un DAG qui n'apparaît pas dans l'interface utilisateur ou qui ne planifie pas est souvent un problème d'analyse. Exécutez manuellement l'analyseur de DAG :

python -c "from airflow.models import DagBag; d = DagBag(); print(d.import_errors)"

S'il y a des erreurs d'importation, elles seront imprimées. Corrigez le code et réexécutez jusqu'à ce que ce soit propre. Dans Airflow 3, le processeur de DAG s'exécute séparément ; vous pouvez également vérifier ses journaux pour les erreurs d'analyse.

Modes de défaillance et récupération

Passons maintenant en revue des scénarios de défaillance spécifiques et comment s'en remettre.

Le scheduler ne planifie pas

Symptômes : les DAG apparaissent dans l'interface utilisateur mais les tâches ne sont pas planifiées ; les journaux du scheduler affichent des erreurs ; airflow jobs check --job-type SchedulerJob échoue.

Diagnostic :

1. Vérifiez le battement de cœur du scheduler :

   airflow jobs check --job-type SchedulerJob --hostname $(hostname)

1. Vérifiez les journaux du scheduler pour les exceptions. Causes courantes : épuisement du pool de connexions à la base de données, requêtes de longue durée ou processeur de DAG bloqué.
2. Vérifiez que la base de données de métadonnées est réactive :

   airflow db check

1. Dans Airflow 3, assurez-vous que le processeur de DAG est en cours d'exécution et sain. Le scheduler ne traite plus les DAG ; il délègue à un service de processeur de DAG séparé.

Récupération :

• Redémarrez le scheduler (et le processeur de DAG dans Airflow 3).
• Si l'épuisement du pool de base de données est suspecté, augmentez sql_alchemy_pool_size dans la section [database], mais vérifiez d'abord les limites de connexion de la base de données.
• Si un DAG spécifique fait planter le scheduler, mettez temporairement en pause ou supprimez le fichier DAG et redémarrez le scheduler pour isoler le problème.

Mises à mort OOM des workers

Symptômes : les tâches échouent avec le code de sortie 137 ou 143 (SIGKILL/SIGTERM) ; les journaux se terminent brusquement ; redémarrage du pod worker dans Kubernetes.

Diagnostic :

• Vérifiez l'utilisation des ressources du worker : free -m, top ou les métriques de pod Kubernetes.
• Examinez les journaux du noyau pour les messages du tueur OOM : dmesg | grep -i oom (nécessite root).
• Vérifiez les paramètres de mémoire des tâches : airflow config get-value celery worker_concurrency ou worker_container_memory_request d'Airflow pour l'exécuteur Kubernetes.

Récupération :

• Réduisez le parallélisme des tâches ou augmentez la mémoire du worker.
• Optimisez le DAG pour utiliser moins de mémoire (par exemple, évitez de charger de grandes données en mémoire).
• Pour les tâches Python, envisagez d'utiliser @task avec execution_timeout et retries pour limiter l'impact.
• Dans Kubernetes, ajustez les limites de ressources dans le modèle de pod.

Problèmes de connexion à la base de données de métadonnées

Symptômes : le scheduler et le serveur web ne démarrent pas ; les journaux affichent OperationalError: could not connect to server ; airflow db check échoue.

Diagnostic :

• Testez la connectivité de la base de données en utilisant la même chaîne de connexion :

  psql "$AIRFLOW__DATABASE__SQL_ALCHEMY_CONN" -c "SELECT 1"

(Adaptez à votre client de base de données.)

• Vérifiez la joignabilité réseau : telnet <db_host> 5432 ou nc -zv <db_host> 5432.
• Consultez les journaux du serveur de base de données pour les rejets de connexion.

Récupération :

• Si la base de données est en panne, restaurez-la à partir de la sauvegarde ou corrigez le problème sous-jacent.
• Si les identifiants sont incorrects, mettez à jour le secret dans le backend de secrets ou la variable d'environnement.
• Si la chaîne de connexion est mal formée, corrigez-la et redémarrez les composants concernés.

Erreurs d'importation de DAG

Symptômes : DAG non visible dans l'interface utilisateur ; erreurs d'importation DagBag ; les journaux du scheduler affichent ImportError ou ModuleNotFoundError.

Diagnostic :

• Exécutez python -c "from airflow.models import DagBag; d = DagBag(); print(d.import_errors)" pour voir l'erreur.
• Si l'erreur est un module manquant, installez le package requis dans l'environnement du scheduler/worker.
• Si l'erreur est une erreur de syntaxe, corrigez le fichier DAG.

Récupération :

• Corrigez le code, retéléversez ou modifiez le fichier DAG, et attendez le prochain cycle d'analyse des DAG (ou déclenchez manuellement : airflow dags reserialize dans Airflow 2, ou redémarrez le processeur de DAG dans Airflow 3).
• Assurez-vous que le fichier DAG est dans le bon dags_folder et dispose des autorisations appropriées.

Mise à niveau du schéma de la base de données

Après une mise à niveau d'Airflow, la base de données de métadonnées peut nécessiter une migration. Symptômes : le scheduler ou le serveur web signale une incompatibilité de version ; les journaux affichent Your database schema is not up to date.

Diagnostic :

• Exécutez airflow db check-migration (Airflow 2.7+) ou airflow db migrate --check pour voir si une migration est nécessaire.

Récupération :

• Sauvegardez la base de données.
• Exécutez airflow db migrate pour appliquer les changements de schéma.
• Redémarrez tous les composants.
• Vérifiez avec airflow db check et les points de terminaison de santé.

Pièges courants et comment les éviter

Même les opérateurs expérimentés tombent dans des pièges récurrents. Voici les pièges les plus courants et comment les éviter ou s'en remettre.

Piège 1 : Redémarrer comme panacée

Pourquoi cela arrive : Redémarrer le scheduler ou le serveur web est rapide et semble souvent résoudre les problèmes transitoires.

Comment éviter : Considérez le redémarrage comme un dernier recours après diagnostic. Un redémarrage peut masquer un problème plus profond qui réapparaîtra. Au lieu de cela, examinez les journaux et les contrôles de santé avant de redémarrer. Si vous redémarrez, faites-le composant par composant et vérifiez la santé ensuite.

Récupération : Si vous avez redémarré et que le problème persiste ou s'aggrave, rassemblez immédiatement les journaux d'avant le redémarrage (s'ils sont disponibles) et effectuez un diagnostic systématique.

Piège 2 : Ignorer les différences de version

Pourquoi cela arrive : De nombreux tutoriels et réponses en ligne concernent Airflow 2, mais les utilisateurs peuvent être sur Airflow 3. Les commandes et les clés de configuration ont changé.

Comment éviter : Vérifiez toujours airflow version et consultez la documentation officielle pour votre version spécifique. Utilisez airflow config get-value pour vérifier les noms de paramètres avant de les modifier.

Récupération : Si vous avez appliqué un changement basé sur une mauvaise version, revenez à la valeur précédente et consultez la bonne documentation.

Piège 3 : Coder en dur les secrets dans les DAG ou les configurations

Pourquoi cela arrive : C'est pratique pendant le développement, et les développeurs peuvent oublier de les supprimer avant la production.

Comment éviter : Utilisez les connexions et variables Airflow gérées via l'interface utilisateur ou les backends de secrets. Appliquez des revues de code et des vérifications statiques pour les secrets. Utilisez des variables d'environnement pour la configuration.

Récupération : Si un secret a fuité, faites-le tourner immédiatement, supprimez-le du DAG/de la configuration et envisagez d'utiliser un backend de secrets. Auditez les journaux pour vérifier les accès non autorisés.

Piège 4 : Négliger les sauvegardes de base de données avant les migrations

Pourquoi cela arrive : Les migrations sont souvent considérées comme routinières, et les sauvegardes prennent du temps et de l'espace de stockage.

Comment éviter : Faites des sauvegardes une étape obligatoire dans toute procédure de mise à niveau ou de migration. Automatisez les sauvegardes et testez régulièrement les procédures de restauration.

Récupération : Si une migration échoue, restaurez à partir de la sauvegarde et analysez l'échec dans un environnement de pré-production avant de réessayer.

Piège 5 : Ne pas surveiller après la récupération

Pourquoi cela arrive : Une fois l'incident résolu, les équipes passent à d'autres travaux.

Comment éviter : Mettez en place une surveillance et des alertes pour les battements de cœur du scheduler, la santé de la base de données et les taux d'échec des tâches. Examinez périodiquement les journaux pour les avertissements récurrents. Établissez une revue post-incident pour mettre à jour les procédures.

Récupération : Si le même problème se reproduit, la procédure doit être mise à jour. Capturez les nouvelles connaissances et partagez-les avec l'équipe.

Liste de contrôle des opérations

La liste de contrôle suivante consolide les étapes essentielles pour le dépannage d'Apache Airflow. Utilisez-la comme référence rapide pendant les incidents.

Note de responsabilité : L'ingénieur de garde est responsable du diagnostic initial et de l'intervention sûre. Le responsable technique doit approuver tout changement de configuration affectant plusieurs composants. Les revues post-incident sont la propriété du chef d'équipe et doivent avoir lieu dans les 24 heures, avec une revue de suivi hebdomadaire pour suivre les actions.

Conclusion

Apache Airflow est un orchestrateur puissant, mais sa nature distribuée signifie que les pannes peuvent être complexes. En suivant une approche structurée — en commençant par l'inventaire de l'environnement, en utilisant des contrôles de santé en lecture seule, en apportant des changements minimaux et en vérifiant la récupération — vous pouvez réduire les temps d'arrêt et prévenir les récidives.

Ce guide a couvert les diagnostics spécifiques aux versions, les pratiques de configuration sûres, les modes de défaillance courants et les pièges. Les points clés à retenir sont :

• Vérifiez toujours la version et la santé des composants avant d'intervenir.
• Utilisez des commandes en lecture seule pour observer, puis faites un petit changement à la fois.
• Protégez les secrets et sauvegardez la base de données avant les migrations.
• Traitez les journaux comme votre principale preuve et apprenez à les lire efficacement.
• Documentez chaque incident et itérez sur vos procédures.

Comme prochaine étape, choisissez une vérification à faible risque sur votre déploiement Airflow actuel : exécutez airflow version, vérifiez le point de terminaison de santé et inspectez les journaux du scheduler pour toute erreur silencieuse. Cette base vous préparera au prochain incident. Pour une intégration plus poussée, examinez comment Apache Airflow interagit avec les outils de données associés comme Apache Spark, NiFi ou Apache Hop, mais limitez toujours les changements au composant Airflow concerné.

Un flux de travail de dépannage fiable transforme le chaos en une série d'étapes vérifiables, réduit le temps moyen de récupération et renforce la confiance dans vos pipelines de données.