Cadre de sévérité des échecs de tests dbt

Ce cadre attribue l’un des quatre paliers de sévérité à chaque échec de test dbt, basé sur le type de test, la couche du modèle, les dépendants en aval et le contexte historique. Il est conçu pour une application automatisée — soit par un agent IA suivant des instructions de skill, soit par un script post-traitement lisant run_results.json — pour produire une liste classée avant qu’un humain ne passe en revue le résumé matinal.

Le système à quatre paliers

Critique signifie agir immédiatement, avant toute autre chose. Les échecs à ce palier indiquent que les données sont déjà incorrectes dans des endroits qui importent aux parties prenantes en ce moment.

Échecs de clé primaire ou d’unicité sur les modèles de la couche mart
Fraîcheur source plus de 24 heures en retard par rapport au calendrier
Tout échec de test sur un modèle alimentant un tableau de bord orienté client ou dirigeants
Échecs not_null sur des clés étrangères qui se joignent aux dimensions de reporting principales

Le palier critique concerne les dommages actuels, pas les dommages potentiels. Si mrt__sales__customers.customer__id a des doublons, le revenu est compté en double dans le tableau de bord des ventes en ce moment. C’est une catégorie de problème différente d’un avertissement de fraîcheur sur un dataset qui alimente un rapport opérationnel interne.

Élevé signifie investiguer aujourd’hui, dans les heures ouvrables. Quelque chose ne va pas et ira de plus en plus mal si ignoré, mais cela ne cause pas actuellement de dommages visibles au niveau des parties prenantes.

Échecs d’intégrité référentielle (tests relationships) sur les modèles intermediate ou mart
Échecs not_null sur des colonnes de dimension clés dans les modèles intermediate
Fraîcheur source entre 6 et 24 heures en retard
Échecs de tests singuliers encodant des règles métier importantes

Moyen signifie investiguer cette semaine. Ces échecs sont de vrais problèmes, mais ils ne sont pas urgents.

Violations accepted_values sur les champs catégoriels
Anomalies de nombre de lignes sur les modèles intermediate — significativement plus ou moins de lignes qu’attendu
Échecs sur des modèles intermediate sans dépendants en aval au niveau mart
Échecs récurrents que vous avez déjà investigués et déterminés comme à faible risque

Faible signifie suivre et regrouper. Inclure dans les digests hebdomadaires plutôt que dans les alertes quotidiennes.

Avertissements de documentation
Changements de schéma mineurs qui ne cassent aucun modèle en aval
Échecs sur des cibles de développement ou sandbox qui apparaissent dans la surveillance en raison d’une mauvaise configuration de cible
Avertissements sur les modèles avec zéro dépendant en aval

Pondération par impact en aval

L’attribution de palier seule ne capture pas l’urgence. Un échec de palier moyen sur un modèle qui alimente dix marts est plus urgent qu’un échec critique sur un modèle qui n’alimente rien. L’impact en aval est un multiplicateur sur la sévérité de base.

La règle pratique : vérifiez combien de modèles de la couche mart se trouvent dans l’arbre de dépendances en aval du modèle en échec. Si le nombre est élevé, promouvez la sévérité d’un palier. Si le modèle n’a aucun dépendant, déclassez d’un palier.

## Ajustement de sévérité pour l'impact en aval

Après avoir attribué la sévérité initiale, vérifiez les dépendants en aval :
1. Exécuter : dbt ls --select +[nom_modèle_en_échec] --resource-type model
2. Compter combien de résultats sont des modèles de la couche mart (commencent par mrt__)
3. Si 3 modèles mart ou plus sont en aval : augmenter la sévérité d'un palier
4. Si aucun modèle en aval : diminuer la sévérité d'un palier

Un échec critique sans dépendants en aval devient élevé.
Un échec moyen avec 5 marts en aval devient critique.

Vous pouvez extraire les informations en aval de deux endroits. dbt ls --select +nom_modèle vous donne la liste à l’exécution, mais ajoute du temps au job de surveillance. manifest.json contient le graphe de dépendances complet et peut être pré-traité en un format compact que l’agent lit sans exécuter de commandes dbt. Pour les grands projets, le pré-traitement du manifest vaut le coût d’installation.

Le rôle du type de test dans la sévérité

Tous les types de tests ne méritent pas la même sévérité par défaut. La réponse appropriée à un échec de fraîcheur source est différente de la réponse appropriée à un échec d’unicité, même quand les deux sont classifiés comme critiques.

Les échecs de fraîcheur source sont des problèmes de timing, pas des problèmes de qualité des données. Les données sous-jacentes peuvent être parfaitement correctes — elles ne sont simplement pas encore arrivées. La réponse de première intention est toujours « attendre et revérifier » plutôt que « investiguer la logique de transformation ».

Les échecs d’unicité sur les clés primaires sont des problèmes d’intégrité des données. Des clients en double dans mrt__sales__customers signifient un revenu compté en double. La réponse est d’investiguer la logique de déduplication dans les modèles base en amont, pas d’attendre.

Les échecs not_null sur les modèles mart sont typiquement causés par l’une de deux choses : les données sources en amont contiennent genuinement des valeurs nulles (problème de qualité des données) ou les données sources ne sont pas encore chargées (problème de timing). Le contexte de fraîcheur source vous indique lequel. C’est pourquoi exécuter la fraîcheur source comme pré-vérification avant l’exécution principale des tests vaut la minute supplémentaire — cela vous donne le contexte pour interpréter correctement les échecs not_null.

Les échecs de tests singuliers sont les plus dépendants du contexte. Un test singulier encode une règle métier spécifique, et si un échec est critique ou faible dépend entièrement de ce qu’est cette règle. Si le test est assert_no_negative_revenue_orders, c’est critique. Si c’est assert_all_orders_have_a_utm_source, ce peut être moyen ou faible selon la centralité du tracking UTM dans votre reporting.

Intégrer le type de test dans la logique de sévérité :

## Modificateurs de sévérité par type de test

Pour les échecs de fraîcheur source :
- Défaut sur Élevé plutôt que Critique quelle que soit la récence
- Note : « Vérifier le connecteur en amont avant d'investiguer les modèles dbt »

Pour les échecs d'unicité sur les modèles mart :
- Défaut sur Critique
- Note : « Les enregistrements en double causent probablement un double comptage dans les rapports en aval »

Pour les échecs de tests singuliers :
- Attribuer la sévérité basée sur le nom du test : les tests avec 'revenue', 'customer' ou 'order'
  dans le nom ont Élevé par défaut ; les autres ont Moyen par défaut
- Signaler pour revue humaine si incertain

Le contexte historique comme modificateur de sévérité

Un test qui échoue pour la première fois mérite une urgence différente d’un test qui a échoué de façon intermittente depuis deux semaines. Les échecs de première occurrence sont plus susceptibles d’être de vrais problèmes nouveaux nécessitant une investigation immédiate. Les échecs récurrents peuvent être des problèmes connus en cours de suivi, des délais de données fournisseurs qui se produisent certains jours spécifiques, ou des tests qui devraient être mis à jour ou supprimés.

Quand une mémoire persistante est disponible — soit via le système de mémoire d’un agent IA, soit via une table d’historique des échecs structurée — annotez chaque échec avec un contexte temporel :

Première occurrence : urgence maximale, traiter comme nouveau et inconnu
Échec récurrent : noter le pattern (« échec 4 des 7 derniers jours »), urgence immédiate plus faible, signaler pour résolution structurelle
Précédemment investigué : inclure votre conclusion précédente (« noté le 18 mars : attendu le week-end en raison du timing batch du fournisseur »)
Nouveau test, jamais passé : signaler comme probable problème de configuration plutôt que problème de données

Ce contexte ne change pas le palier sous-jacent mais change ce que vous faites à ce sujet. Un échec d’unicité critique, de première occurrence, est investigué immédiatement. Un échec d’unicité critique et récurrent sur un modèle que vous avez trié mardi dernier est vérifié par rapport à vos notes précédentes avant de démarrer une nouvelle investigation.

Appliquer le cadre dans les instructions de skill

Si vous utilisez un agent IA pour appliquer ce cadre automatiquement, donnez-lui les règles explicitement. Les agents suivent les listes d’instructions de manière plus fiable qu’ils ne synthétisent des règles à partir de descriptions :

## Classification de sévérité

Pour chaque échec de test, attribuer un palier :

CRITIQUE (agir immédiatement) :
- Le type de test est `unique` ou `not_null` sur un modèle commençant par `mrt__`
- Fraîcheur source plus de 24 heures en retard
- Le nom du test fait référence à un tableau de bord ou un modèle orienté client (regarder dans le meta du modèle)

ÉLEVÉ (investiguer aujourd'hui) :
- Le type de test est `relationships` sur n'importe quelle couche
- `not_null` sur les modèles intermediate avec des dépendants mart
- Fraîcheur source entre 6 et 24 heures en retard

MOYEN (investiguer cette semaine) :
- Violations `accepted_values` sur n'importe quelle couche
- Anomalies de nombre de lignes
- Échecs sur les modèles intermediate sans dépendants mart

FAIBLE (digest hebdomadaire) :
- Avertissements
- Changements de schéma sur les modèles sans dépendants en aval
- Tests sur les cibles hors production

La spécificité ici est délibérée. « Échecs à fort impact » n’est pas une instruction utile pour un agent IA. « Le type de test est unique ou not_null sur un modèle commençant par mrt__ » l’est.

Ce que ce cadre n’est pas

Ce cadre sert au triage à l’exécution — classer les échecs d’une exécution dbt test spécifique. Il est distinct de la question de comment router ces échecs vers les bonnes personnes une fois classés, ce qui est géré par le routage des alertes de tests dbt et la propriété, et de la question de quels tests écrire en premier lieu, couverte par la stratégie de test dbt par couche.

Le cadre ne remplace pas le jugement humain pour les patterns d’échec nouveaux. Un agent appliquant ces règles aura parfois une mauvaise classification ; l’intention est de gérer le triage simple automatiquement pour que la revue humaine se concentre sur les cas genuinement ambigus.