Observabilité de Cortex Framework
Pour exécuter et exploiter des plates-formes de données de niveau entreprise, il est essentiel de disposer d'une visibilité sur l'exécution des pipelines, la qualité des données et les erreurs opérationnelles.
Cortex Framework catégorise l'observabilité selon ses deux cycles de vie distincts :
- Observabilité lors du déploiement : suivi du chargement de la configuration, de la compilation des modèles, des vérifications de validation, des actions de déploiement et de la télémétrie de l'API lors de l'exécution des outils CLI.
- Observabilité lors de l'exécution : suivi de l'exécution, de la progression du pipeline, des performances des requêtes, des assertions de qualité des données et des alertes automatisées pour les pipelines de données déployés s'exécutant à l'intérieur Google Cloud.
Observabilité lors du déploiement
L'observabilité lors du déploiement se concentre sur l'exécution des outils CLI (par exemple, uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync).
Journalisation de la console locale
Lorsque vous exécutez des commandes CLI, Cortex Framework enregistre la progression directement dans la console (stdout).
- Niveau de journalisation : par défaut, les journaux sont générés au niveau
INFO. - Points clés visuels : les messages sont codés par couleur pour mettre en évidence les erreurs et les avertissements de manière dynamique :
- ❌ Erreurs (rouge) indiquant des échecs critiques qui interrompent l'exécution.
- ⚠️ Avertissements (orange) indiquant des anomalies de configuration potentielles ou des problèmes non bloquants.
- Code temporel et source : chaque ligne de journal affiche l'heure d'exécution et les noms de classe ou de module Python actifs pour un suivi précis.
Fichiers journaux locaux persistants
À chaque exécution de commande, l'orchestrateur Python diffuse automatiquement le journal d'exécution complet dans un fichier journal temporaire du répertoire temporaire de votre système :
/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log
Le chemin d'accès précis s'affiche dans la console au démarrage des outils CLI. Ces fichiers contiennent des informations de journal complètes (y compris des traces de pile pour les erreurs inattendues) et sont très utiles pour déboguer les problèmes rencontrés lors de l'exécution des outils CLI ou lorsque vous joignez des demandes d'assistance.
Google Cloud Validation de l'environnement
Avant d'effectuer des actions de compilation, de déploiement ou de synchronisation, le moteur d'orchestration exécute l'utilitaire GcpEnvironmentChecker. Cette vérification valide les points suivants :
- API requises : confirme que les API essentielles sont activées (par exemple,
bigquery.googleapis.com,dataform.googleapis.com). Google Cloud - Existence de l'ensemble de données : vérifie que les ensembles de données bruts et cibles requis existent ou peuvent être créés.
- Emplacements et régions : s'assure que les ensembles de données cibles correspondent aux régions géographiques des ensembles de données sources.
- Capacité et paramètres : valide les paramètres de réservation et les configurations de catalogue.
Toute non-concordance est enregistrée en tant qu'erreur avec des conseils recommandés sur la manière de les résoudre avant d'effectuer des appels de service Google Cloud .
Télémétrie
Lors des processus de déploiement et de synchronisation, Cortex Framework enregistre la télémétrie anonyme d'adoption, de variante et de version du framework dans Google Cloud. Pour en savoir plus sur son fonctionnement et sur la procédure de désactivation, consultez Télémétrie.
Observabilité lors de l'exécution
Une fois créées et déployées, les couches de données et les produits de données conformes de Cortex Framework s'exécutent entièrement dans Dataform et BigQuery. Par conséquent, l'observabilité lors de l'exécution s'intègre directement aux suites opérationnelles Google Cloud .
Journalisation de l'exécution du pipeline
Tous les pipelines déployés sont suivis à l'aide de Cloud Logging et d'outils d'exécution :
- Journaux d'exécution Dataform : Dataform enregistre chaque événement de compilation et d'exécution. Vous pouvez accéder à ces informations dans la Google Cloud console ou par programmation à l'aide de l'API Dataform.
- Historique des tâches BigQuery : chaque table et vue matérialisées par vos pipelines Dataform exécute des requêtes SQL dans BigQuery. L'utilisation détaillée des ressources, les performances des requêtes, les octets traités et les codes temporels d'exécution sont enregistrés dans l'historique des tâches BigQuery.
Surveillance des pipelines
Vous pouvez surveiller l'état des pipelines, les configurations de version et l'historique d'exécution de manière visuelle ou par programmation :
- Interface utilisateur Web Dataform : accédez à la console Dataform pour :
- inspecter les modèles de données compilés et visualiser le graphique compilé ;
- vérifier l'état des configurations de version, des modèles compilés et des environnements actifs ;
- surveiller l'historique et les détails des exécutions de workflow actuelles et passées.
- Intégration de Cloud Monitoring : suivez les métriques des pipelines Dataform, telles que les durées d'exécution, les compilations actives et les taux d'échec des tâches de workflow, via des panneaux de tableau de bord personnalisés.
Alertes et qualité des données
Pour garantir l'intégrité des données et signaler automatiquement les échecs de pipeline, configurez des alertes à l'aide des mécanismes suivants :
Assertions de qualité des données
Vous pouvez définir des règles de validation des données personnalisées (par exemple, vous assurer qu'une colonne n'est jamais nulle, vérifier que les clés primaires sont uniques ou valider des plages numériques) en créant des fichiers d'assertion .sqlx.
- Vous pouvez fournir un fichier d'assertions personnalisé à l'aide du paramètre
--assertions:bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx - Lors de l'exécution du pipeline, Dataform exécute ces requêtes de validation. Si une requête d'assertion renvoie une ou plusieurs lignes, la validation échoue et l'exécution du pipeline est immédiatement marquée comme ayant échoué.
- Pour en savoir plus sur l'écriture de règles de validation des données, consultez la documentation officielle sur les assertions Dataform.
Exemple de fichier d'assertion (assertions.sqlx)
Exemple de requête d'assertion Dataform qui recherche les valeurs NULL et les enregistrements client en double. Si cette requête renvoie des lignes, l'assertion échoue et arrête le workflow d'exécution :
config {
type: "assertion",
description: "Ensure customer_number_kunnr is not null and unique"
}
-- Check for NULL values
(
SELECT
"customer_number_kunnr is NULL" AS error_message
FROM
${ref("customers")}
WHERE
customer_number_kunnr IS NULL
)
UNION ALL
-- Check for duplicate keys
(
SELECT
CONCAT("Duplicate customer number found: ", customer_number_kunnr) AS error_message
FROM
${ref("customers")}
GROUP BY
customer_number_kunnr,
client_mandt
HAVING
COUNT(*) > 1
)
Règles d'alertes Cloud
Configurez des règles d'alertes standards Google Cloud pour avertir vos équipes d'ingénierie ou d'opérations en cas de problème :
- Alertes basées sur les journaux : créez des alertes dans Cloud Logging qui se déclenchent lorsque des événements d'erreur, des exécutions de workflow ayant échoué ou des problèmes de compilateur sont détectés dans vos journaux.
- Alertes basées sur les métriques : définissez des seuils dans Cloud Monitoring en fonction de la durée d'exécution ou des échecs de compilation.
- Canaux de notification : configurez ces alertes pour acheminer les problèmes vers les canaux de communication préférés de votre équipe.