Dépannage du déploiement Astro

Cette skill vous aide à diagnostiquer et dépanner les déploiements Astronomer en production en utilisant l'Astro CLI.

Pour la gestion des déploiements, voir la skill managing-astro-deployments. Pour le développement local, voir la skill managing-astro-local-env.

Vérification rapide de la santé

Commencez par ces commandes pour obtenir un aperçu :

# 1. Lister les déploiements pour trouver la cible
astro deployment list

# 2. Obtenir un aperçu du déploiement
astro deployment inspect <DEPLOYMENT_ID>

# 3. Vérifier les erreurs
astro deployment logs <DEPLOYMENT_ID> --error -c 50

Affichage des logs de déploiement

Utilisez -c pour contrôler le nombre de logs (par défaut : 500). Les drapeaux de log ne peuvent pas être combinés — utilisez un seul drapeau de composant ou de niveau par commande.

Logs spécifiques aux composants

Afficher les logs de composants Airflow spécifiques :

# Logs du scheduler (traitement des DAGs, planification des tâches)
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 50

# Logs des workers (exécution des tâches)
astro deployment logs <DEPLOYMENT_ID> --workers -c 30

# Logs du webserver (accès UI, vérifications de santé)
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30

# Logs du triggerer (opérateurs reportables)
astro deployment logs <DEPLOYMENT_ID> --triggerer -c 30

Filtrage par niveau de log

Filtrer par gravité :

# Logs d'erreur uniquement (plus utile pour le dépannage)
astro deployment logs <DEPLOYMENT_ID> --error -c 30

# Logs d'avertissement
astro deployment logs <DEPLOYMENT_ID> --warn -c 50

# Logs de niveau info
astro deployment logs <DEPLOYMENT_ID> --info -c 50

Recherche dans les logs

Rechercher des mots-clés spécifiques :

# Rechercher une erreur spécifique
astro deployment logs <DEPLOYMENT_ID> --keyword "ConnectionError"

# Rechercher un DAG spécifique
astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100

# Trouver les erreurs d'import
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"

# Trouver les défaillances de tâches
astro deployment logs <DEPLOYMENT_ID> --error --keyword "Task failed"

Flux d'investigation complet

Étape 1 : Identifier le problème

# Lister les déploiements avec le statut
astro deployment list

# Obtenir les détails du déploiement
astro deployment inspect <DEPLOYMENT_ID>

Rechercher :

• Statut : HEALTHY vs UNHEALTHY
• Compatibilité de la version runtime
• Limites de ressources (CPU, mémoire)
• Timestamp du déploiement récent

Étape 2 : Vérifier les logs d'erreur

# Commencer par les erreurs
astro deployment logs <DEPLOYMENT_ID> --error -c 50

Rechercher :

• Motifs d'erreur récurrents
• DAGs spécifiques défaillant régulièrement
• Erreurs d'import ou d'erreurs de syntaxe
• Erreurs de connexion ou d'authentification

Étape 3 : Examiner les logs du scheduler

# Vérifier le traitement des DAGs
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 30

Rechercher :

• Erreurs d'analyse des DAGs
• Retards de planification
• Problèmes de mise en queue des tâches

Étape 4 : Vérifier les logs des workers

# Vérifier l'exécution des tâches
astro deployment logs <DEPLOYMENT_ID> --workers -c 30

Rechercher :

• Défaillances d'exécution des tâches
• Épuisement des ressources
• Erreurs de timeout

Étape 5 : Vérifier la configuration

# Vérifier les variables d'environnement
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# Vérifier les paramètres du déploiement
astro deployment inspect <DEPLOYMENT_ID>

Rechercher :

• Variables d'environnement manquantes ou incorrectes
• Configuration des secrets (AIRFLOWSECRETSBACKEND)
• Configuration des connexions

Motifs d'investigation courants

Défaillances récurrentes de DAGs

Suivez le flux d'investigation complet ci-dessus, puis affinez le DAG spécifique :

astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100

Problèmes de ressources

# 1. Vérifier l'allocation de ressources du déploiement
astro deployment inspect <DEPLOYMENT_ID>
# Rechercher : resource_quota_cpu, resource_quota_memory
# Queue des workers : max_worker_count, worker_type

# 2. Vérifier les problèmes de mise à l'échelle des workers
astro deployment logs <DEPLOYMENT_ID> --workers -c 50

# 3. Rechercher les erreurs de mémoire insuffisante
astro deployment logs <DEPLOYMENT_ID> --error --keyword "memory"

Problèmes de configuration

# 1. Examiner les variables d'environnement
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# 2. Vérifier la configuration du backend de secrets
# Rechercher : AIRFLOW__SECRETS__BACKEND, AIRFLOW__SECRETS__BACKEND_KWARGS

# 3. Vérifier les paramètres du déploiement
astro deployment inspect <DEPLOYMENT_ID>

# 4. Vérifier les logs du webserver pour les problèmes d'authentification
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30

Erreurs d'import

# 1. Trouver les erreurs d'import
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"

# 2. Vérifier le scheduler pour les défaillances d'analyse
astro deployment logs <DEPLOYMENT_ID> --scheduler --keyword "Failed to import" -c 50

# 3. Vérifier que les dépendances ont été déployées
astro deployment inspect <DEPLOYMENT_ID>
# Vérifier : current_tag, timestamp du dernier déploiement

Gestion des variables d'environnement

Lister les variables

# Lister toutes les variables du déploiement
astro deployment variable list --deployment-id <DEPLOYMENT_ID>

# Trouver une variable spécifique
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --key AWS_REGION

# Exporter les variables dans un fichier
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --save --env .env.backup

Créer des variables

# Créer une variable régulière
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
  --key API_ENDPOINT \
  --value https://api.example.com

# Créer un secret (masqué dans l'UI et les logs)
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
  --key API_KEY \
  --value secret123 \
  --secret

Mettre à jour les variables

# Mettre à jour une variable existante
astro deployment variable update --deployment-id <DEPLOYMENT_ID> \
  --key API_KEY \
  --value newsecret

Supprimer les variables

# Supprimer une variable
astro deployment variable delete --deployment-id <DEPLOYMENT_ID> --key OLD_KEY

Remarque : Les variables sont disponibles pour les DAGs en tant que variables d'environnement. Les modifications ne nécessitent aucun redéploiement.

Métriques clés de deployment inspect

Concentrez-vous sur ces champs lors du dépannage :

• status : HEALTHY vs UNHEALTHY
• runtime_version : Compatibilité de la version Airflow
• scheduler_size/scheduler_count : Capacité du scheduler
• executor : CELERY, KUBERNETES, ou LOCAL
• worker_queues : Limites de mise à l'échelle et types de workers
  • min_worker_count, max_worker_count
  • worker_concurrency
  • worker_type (classe de ressources)
• resource_quota_cpu/memory : Limites globales des ressources
• dag_deploy_enabled : Si les déploiements DAG uniquement fonctionnent
• current_tag : Version du dernier déploiement
• is_high_availability : Redondance activée

Bonnes pratiques d'investigation

1. Toujours commencer par les logs d'erreur - Les défaillances les plus évidentes apparaissent ici
2. Vérifier les motifs dans les logs d'erreur - Même DAG défaillant régulièrement ? Motifs temporels ?
3. Dépannage spécifique aux composants :
   • Logs des workers → détails d'exécution des tâches
   • Logs du scheduler → traitement et planification des DAGs
   • Logs du webserver → problèmes UI et vérifications de santé
   • Logs du triggerer → problèmes d'opérateurs reportables
4. Utiliser --keyword pour les recherches ciblées - Plus efficace que de lire tous les logs
5. La commande inspect est votre tableau de bord de santé - La vérifier en premier
6. Variables d'environnement dans la sortie inspect - Peuvent révéler des problèmes de configuration
7. Le nombre de logs par défaut est 500 - Ajuster avec -c selon les besoins
8. N'oubliez pas de vérifier l'heure du déploiement - Un déploiement récent pourrait avoir introduit le problème

Référence rapide de dépannage

Skills associées

• managing-astro-deployments : Créer, mettre à jour, supprimer les déploiements, déployer le code
• managing-astro-local-env : Gérer l'environnement de développement Airflow local
• setting-up-astro-project : Initialiser et configurer les projets Astro