debugging-dags

Diagnostic complet des défaillances de DAG et analyse des causes profondes. À utiliser pour les demandes de débogage complexes nécessitant une investigation approfondie, comme « diagnostiquer et corriger le pipeline », « analyse complète des causes profondes », « pourquoi cela échoue et comment le prévenir ». Pour les déboguages simples (« pourquoi le DAG a-t-il échoué », « afficher les logs »), le skill entrypoint airflow gère cela directement. Ce skill fournit une investigation structurée et des recommandations de prévention.

npx skills add https://github.com/astronomer/agents --skill debugging-dags

Diagnostic DAG

Vous êtes un data engineer en train de déboguer un DAG Airflow défaillant. Suivez cette approche systématique pour identifier la cause première et proposer une correction opérationnelle.

Exécuter l'interface CLI

Ces commandes supposent que af est sur le PATH. Exécutez via astro otto pour l'obtenir automatiquement, ou installez en standalone avec uv tool install astro-airflow-mcp.

Étape 1 : Identifier la défaillance

Si un DAG spécifique a été mentionné :

  • Exécutez af runs diagnose <dag_id> <dag_run_id> (si run_id est fourni)
  • Si aucun run_id spécifié, exécutez af dags stats pour trouver les défaillances récentes

Si aucun DAG n'a été spécifié :

  • Exécutez af health pour trouver les défaillances récentes sur tous les DAGs
  • Vérifiez les erreurs d'import avec af dags errors
  • Affichez les DAGs avec défaillances récentes
  • Demandez quel DAG approfondir

Étape 2 : Obtenir les détails de l'erreur

Une fois qu'une tâche défaillante est identifiée :

  1. Récupérez les logs de la tâche via af tasks logs <dag_id> <dag_run_id> <task_id>
  2. Cherchez l'exception réelle — scrollez au-delà du boilerplate Airflow pour trouver la vraie erreur
  3. Catégorisez le type de défaillance :
    • Problème de données : Données manquantes, changement de schéma, valeurs nulles, violation de contrainte
    • Problème de code : Bug, erreur de syntaxe, échec d'import, erreur de type
    • Problème d'infrastructure : Timeout de connexion, épuisement des ressources, permission refusée
    • Problème de dépendance : Tâche amont défaillante, API externe down, limitation de débit

Étape 3 : Vérifier le contexte

Rassemblez du contexte supplémentaire pour comprendre POURQUOI cela s'est produit :

  1. Changements récents : Y a-t-il eu un déploiement de code ? Vérifiez l'historique git si disponible
  2. Volume de données : Le volume de données a-t-il augmenté ? Exécutez un comptage rapide sur les tables sources
  3. Santé des tâches amont : Les tâches amont ont-elles réussi mais produit des données inattendues ?
  4. Motif historique : Est-ce une défaillance récurrente ? Vérifiez si la même tâche a échoué avant
  5. Timing : A-t-elle échoué à un moment inhabituels ? (contention de ressources, fenêtres de maintenance)

Utilisez af runs get <dag_id> <dag_run_id> pour comparer l'exécution défaillante aux exécutions réussies récentes.

Sur Astro

Si vous exécutez sur Astro, ces outils supplémentaires peuvent aider au diagnostic :

  • Journal d'activité du déploiement : Vérifiez l'interface Astro pour les déploiements récents — un déploiement échoué ou un changement de code récent est souvent la cause des défaillances soudaines
  • Alertes Astro : Configurez des alertes dans l'interface Astro pour la surveillance proactive des défaillances (défaillance de DAG, durée de tâche, SLA manqué)
  • Observabilité : Utilisez le tableau de bord d'observabilité Astro pour suivre les tendances de santé des DAGs et détecter les problèmes récurrents

Sur OSS Airflow

  • Interface Airflow : Utilisez la page DAGs, la vue Graph et les logs de tâche pour inspecter les exécutions récentes et les défaillances

Étape 4 : Fournir une sortie opérationnelle

Structurez votre diagnostic comme :

Cause première

Qu'est-ce qui a vraiment cassé ? Soyez spécifique — pas « la tâche a échoué » mais « la tâche a échoué parce que la colonne X était nulle dans 15 % des lignes alors que le code s'attendait à 0 % ».

Évaluation d'impact

  • Quelles données sont affectées ? Quelles tables n'ont pas été mises à jour ?
  • Quels processus aval sont bloqués ?
  • Cela bloque-t-il les dashboards ou rapports de production ?

Correction immédiate

Étapes spécifiques pour résoudre MAINTENANT :

  1. Si c'est un problème de données : SQL pour corriger ou ignorer les mauvais enregistrements
  2. Si c'est un problème de code : Le changement de code exact nécessaire
  3. Si c'est de l'infra : Qui contacter ou quoi redémarrer

Prévention

Comment éviter que cela ne se reproduise :

  • Ajouter des vérifications de qualité des données ?
  • Ajouter une meilleure gestion d'erreurs ?
  • Ajouter des alertes pour les cas limites ?
  • Mettre à jour la documentation ?

Commandes rapides

Fournissez les commandes prêtes à utiliser :

  • Pour effacer et réexécuter l'exécution complète du DAG : af runs clear <dag_id> <run_id>
  • Pour effacer et réexécuter les tâches spécifiques défaillantes : af tasks clear <dag_id> <run_id> <task_ids> -D
  • Pour supprimer une exécution bloquée ou indésirée : af runs delete <dag_id> <run_id>