Analyse des sorties de tests dbt pour la surveillance automatisée

La sortie brute de dbt test contient tout ce qu’il faut pour comprendre un échec. Elle nécessite aussi une interprétation réelle avant de devenir utile. « Le test unique sur mrt__sales__customers.customer__id a échoué avec 3 lignes » n’est pas la même chose que de comprendre qu’il s’agit d’une violation de clé primaire sur un modèle mart avec sept dépendants en aval, dont trois alimentent des tableaux de bord orientés clients.

Passer de la sortie brute à cette deuxième version nécessite un parsing délibéré. Que vous fournissiez cette sortie à un agent IA via un fichier de skill ou que vous écriviez vous-même des scripts post-exécution, la logique de parsing est la même — et vaut la peine d’être bien faite avant d’ajouter quoi que ce soit d’autre par-dessus.

Ce qu’il faut extraire par échec

Pour chaque test en échec, les informations souhaitées sont :

• Nom du test — l’identifiant complet, par ex. unique_mrt__sales__customers_customer__id
• Type de test — générique intégré, générique personnalisé, singulier ou fraîcheur source
• Modèle testé — dérivé du chemin du nœud de test
• Colonne testée — présente dans la configuration du test pour les tests au niveau colonne
• Nombre d’échecs — combien de lignes ont violé la condition du test
• Exemples de lignes en échec — des exemples concrets qui orientent vers la cause racine

Le nom du test encode le type si vous le parsez correctement. Les tests génériques comme unique, not_null, accepted_values et relationships apparaissent comme préfixes dans le nom du nœud de test. Un test nommé unique_mrt__sales__customers_customer__id est un test générique unique sur la colonne customer__id de mrt__sales__customers. Un test nommé assert_no_orphaned_orders est un test singulier avec un nom personnalisé. Les tests basés sur des packages comme ceux de dbt_expectations apparaissent avec le préfixe du package : expect_column_values_to_be_between_mrt__sales__orders_order__amount.

Si vous instruisez un agent IA, donnez-lui ceci explicitement :

## Parser les noms de tests

Pour chaque résultat de test, extraire :
1. Nom du test et type (chercher `unique`, `not_null`, `accepted_values`,
   `relationships` ou `dbt_expectations` dans le nom du test)
2. Le modèle testé (depuis le chemin du nœud de test)
3. La colonne testée (depuis la configuration du test)
4. Le nombre de lignes en échec
5. Si --store-failures est activé, interroger la table d'échecs pour obtenir
   3 à 5 exemples de lignes en échec pour le contexte

Montrer à l’agent une liste d’instructions fonctionne mieux que de décrire abstraitement les règles de parsing. La structure numérotée lui donne un protocole à suivre, pas des principes à interpréter.

Obtenir des exemples de lignes en échec

Savoir qu’un test unique a échoué avec 3 lignes vous indique qu’il y a un problème de duplication. Voir ces 3 lignes vous indique où chercher. Il y a deux façons de les obtenir.

--store-failures indique à dbt d’écrire les lignes en échec dans une table de votre entrepôt. Exécutez dbt test --store-failures et dbt crée des tables comme dbt_test__audit.unique_mrt__sales__customers_customer__id dans un schéma dédié. Vous pouvez alors interroger cette table pour récupérer des exemples de lignes.

dbt show est une alternative plus légère pour explorer des modèles en échec spécifiques après une exécution. Cela ne nécessite pas --store-failures et fonctionne sur n’importe quel modèle :

dbt show --select unique_mrt__sales__customers_customer__id --limit 5

Pour la surveillance automatisée, --store-failures est le meilleur choix parce que l’agent peut interroger la table d’échecs automatiquement sans configuration supplémentaire par échec. Ajoutez ceci à votre fichier de skill :

## Obtenir des exemples de lignes

Après avoir exécuté `dbt test --store-failures` :
- Pour chaque test en échec, vérifier si une table d'échecs existe dans dbt_test__audit
- Si c'est le cas, l'interroger : SELECT * FROM dbt_test__audit.[nom_test] LIMIT 5
- Inclure les exemples de lignes dans le rapport d'échec
- Si aucune table d'échecs n'existe (certains types de tests ne stockent pas les échecs), omettre cette étape

Distinguer les types d’échec

La taxonomie des tests dbt compte cinq mécanismes, mais en pratique, les types d’échec les plus importants pour la surveillance automatisée sont ces trois :

Échecs de données (FAIL) — le test s’est exécuté avec succès et a trouvé des lignes qui violent la condition. Cela signifie que le pipeline a tourné ; les données sont incorrectes. Un échec not_null signifie que des lignes nulles existent dans la sortie. Un échec unique signifie que des lignes en double existent. Un échec relationships signifie que des clés étrangères orphelines existent. La réponse appropriée est d’investiguer les données et leurs sources en amont.

Échecs de pipeline (ERROR) — le test n’a pas pu s’exécuter du tout. Les erreurs de compilation, les modèles manquants, les échecs de connexion et les références de sources non définies produisent tous des ERRORs. Les données peuvent être parfaitement correctes ; quelque chose dans l’infrastructure ou la définition du modèle est cassé. La réponse appropriée est de regarder le projet dbt lui-même, pas les données.

Violations douces (WARN) — les tests configurés avec severity: warn signalent les problèmes mais ne font pas échouer l’exécution. Ce sont des conditions que l’équipe a décidé d’être tolérables en production mais qui méritent d’être connues. La réponse appropriée est de les noter et de les revoir pendant les heures normales de travail, pas de réveiller quelqu’un.

Ces trois catégories nécessitent des réponses différentes, des niveaux d’urgence différents et des investigations différentes. Un système automatisé qui les traite de manière identique produira rapidement de la fatigue d’alertes. Intégrez cette distinction dès le début :

## Classification du type d'échec

Quand vous voyez FAIL :
- Les données ont violé une condition de test
- Rapporter : nom du test, modèle, nombre de lignes en échec, exemples de lignes si disponibles
- Investiguer : vérifier la fraîcheur de la source en amont, la logique de déduplication ou les changements de règles métier

Quand vous voyez ERROR :
- Le test n'a pas pu s'exécuter
- Rapporter : message d'erreur verbatim, quel modèle n'a pas réussi à compiler
- Investiguer : erreurs de compilation dbt, modèles manquants, problèmes de connexion

Quand vous voyez WARN :
- Un seuil souple a été dépassé
- Rapporter : quel test, quel modèle, le comptage
- Signaler : « mérite investigation mais non bloquant »

Tous les types d’échec ne s’appliquent pas également à tous les types de tests. Les échecs de fraîcheur source apparaissent toujours comme des entrées séparées avec leur propre format : raw_shopify.orders avec un décalage de fraîcheur mesuré en heures. Traitez-les comme une quatrième catégorie qui indique des problèmes de timing plutôt que des problèmes de qualité des données — un échec not_null à 6h du matin peut être causé par un échec de fraîcheur source que vous devez voir en premier.

Gérer les exécutions partielles

La plupart des exécutions dbt test en production renvoient un mélange de réussites, d’échecs, d’avertissements et d’erreurs. La surveillance automatisée doit gérer ces quatre états sans se perdre en présence de l’un d’eux.

Une erreur de compilation sur un test ne doit pas empêcher le reporting sur les 140 tests qui ont bien tourné. Un échec de fraîcheur ne doit pas masquer les échecs de qualité des données qui peuvent ou non en être causés. Des instructions explicites empêchent la logique de parsing de court-circuiter sur le premier problème rencontré :

## Gérer les résultats mixtes

Si certains tests échouent et d'autres réussissent :
- Toujours rapporter le total : « 142/147 tests réussis, 3 échoués, 2 avertissements »
- Lister les échecs et avertissements individuellement avec tous les détails
- Ne pas omettre les tests réussis du comptage
- Si un test a une ERROR de compilation (pas un FAIL de données), le rapporter
  séparément comme problème de pipeline, pas de qualité des données

Ne pas arrêter le parsing après le premier échec. Traiter tous les résultats.

Le comptage total importe parce que le contexte façonne l’urgence. « 3 tests ont échoué » a un ressenti différent quand 144 autres ont réussi par rapport à quand 20 autres ont aussi échoué. Incluez-le toujours.

Le flag --target prod

Lors de l’exécution de la surveillance automatisée sur des données de production, spécifiez toujours la cible explicitement. Sans cela, dbt utilise la cible par défaut dans votre profiles.yml, qui est typiquement un environnement de développement.

dbt test --target prod --store-failures

Cela semble évident mais est une source courante de confusion lors de la première configuration de la surveillance automatisée. L’agent exécute la commande, voit zéro échec, et vous passez du temps à vous demander pourquoi — jusqu’à ce que vous réalisiez qu’il testait un schéma de développement vide.

Ce qui vient après le parsing

Un bon parsing de sortie est le fondement. Une fois que vous avez des informations d’échec structurées, les étapes suivantes sont l’évaluation de sévérité (quels échecs nécessitent une attention en premier ?) et le croisement avec la documentation (que représente réellement cette colonne, et qu’est-ce qui se casse si elle est incorrecte ?). Les deux dépendent d’un parsing propre et structuré comme entrée.

Pour le pattern complet d’assemblage dans un résumé matinal, consultez la note Pattern de rapport matinal de qualité dbt. Pour la mécanique de livraison via un agent IA sur un calendrier, commencez par Mécanique du planificateur cron OpenClaw.