Osservabilità di Cortex Framework
Per eseguire e gestire correttamente piattaforme di dati di livello aziendale, è fondamentale avere visibilità sull'esecuzione delle pipeline, sulla qualità dei dati e sugli errori operativi.
Cortex Framework classifica l'osservabilità in base ai suoi due cicli di vita distinti:
- Osservabilità in fase di deployment: monitoraggio del caricamento della configurazione, della compilazione dei modelli, dei controlli di convalida, delle azioni di deployment e della telemetria delle API durante l'esecuzione degli strumenti CLI.
- Osservabilità in fase di runtime: monitoraggio dell'esecuzione, dell'avanzamento della pipeline, delle prestazioni delle query, delle asserzioni sulla qualità dei dati e degli avvisi automatici per le pipeline di dati di cui è stato eseguito il deployment in Google Cloud.
Osservabilità in fase di deployment
L'osservabilità in fase di deployment si concentra sull'esecuzione degli strumenti CLI (ad es. uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync).
Logging della console locale
Quando esegui i comandi CLI, Cortex Framework registra l'avanzamento direttamente nella console (stdout).
- Livello di log: per impostazione predefinita, i log vengono generati a livello
INFO. - Evidenziazioni visive: i messaggi sono codificati a colori per evidenziare dinamicamente errori e avvisi:
- ❌ Errori (rosso) che indicano errori critici che interrompono l'esecuzione.
- ⚠️ Avvisi (arancione) che indicano potenziali anomalie di configurazione o problemi non bloccanti.
- Timestamp e origine: ogni riga di log mostra l'ora di esecuzione e i nomi delle classi o dei moduli Python attivi per una tracciabilità precisa.
File di log locali permanenti
A ogni esecuzione del comando, l'orchestratore Python trasmette automaticamente il log di esecuzione completo a un file di log temporaneo nella directory temporanea del sistema:
/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log
Il percorso esatto viene stampato nella console durante l'avvio degli strumenti CLI. Questi file contengono dettagli completi dei log (inclusi gli stack trace per gli errori imprevisti) e sono preziosi per il debug dei problemi riscontrati durante l'esecuzione degli strumenti CLI o quando li alleghi alle richieste di assistenza.
Google Cloud Convalida dell'ambiente
Prima di eseguire azioni di build, deployment o sincronizzazione, il motore di orchestrazione esegue l'utilità GcpEnvironmentChecker. Questo controllo convalida:
- API richieste: conferma che le API cruciali siano abilitate (ad es.
bigquery.googleapis.com,dataform.googleapis.com). Google Cloud - Esistenza del set di dati: verifica che i set di dati grezzi e di destinazione richiesti esistano o possano essere creati.
- Località e regioni: garantisce che i set di dati di destinazione corrispondano alle regioni geografiche dei set di dati di origine.
- Capacità e impostazioni: convalida le impostazioni di prenotazione e le configurazioni del catalogo.
Qualsiasi mancata corrispondenza viene registrata come errore con suggerimenti su come risolverla prima di effettuare Google Cloud chiamate di servizio.
Telemetria
Durante i processi di deployment e sincronizzazione, Cortex Framework registra la telemetria anonima di adozione, variante e versione del framework in Google Cloud. Per informazioni dettagliate su come funziona e istruzioni su come disattivare la funzionalità, consulta Telemetria.
Osservabilità in fase di runtime
Una volta creati e di cui è stato eseguito il deployment, i livelli di dati e i prodotti di dati conformi a Cortex Framework vengono eseguiti interamente in Dataform e BigQuery. Di conseguenza, l'osservabilità in fase di runtime si integra direttamente con le suite operative. Google Cloud
Logging dell'esecuzione della pipeline
Tutte le pipeline di cui è stato eseguito il deployment vengono monitorate utilizzando Cloud Logging e gli strumenti di esecuzione:
- Log di esecuzione di Dataform: Dataform registra ogni evento di compilazione ed esecuzione. Puoi accedere a questi dettagli nella Google Cloud console o a livello di programmazione utilizzando l'API Dataform.
- Cronologia dei job di BigQuery: ogni tabella e visualizzazione materializzata dalle pipeline Dataform esegue query SQL all'interno di BigQuery. L'utilizzo dettagliato delle risorse, le prestazioni delle query, i byte elaborati e i timestamp di esecuzione vengono registrati nella cronologia dei job di BigQuery.
Monitoraggio della pipeline
Puoi monitorare l'integrità della pipeline, le configurazioni di release e la cronologia di esecuzione visivamente o a livello di programmazione:
- Interfaccia utente web di Dataform: vai alla console Dataform per:
- Ispezionare i modelli di dati compilati e visualizzare il grafico compilato.
- Verificare lo stato delle configurazioni di release, dei modelli compilati e degli ambienti attivi.
- Monitorare la cronologia e i dettagli delle esecuzioni del flusso di lavoro attuali e passate.
- Integrazione di Cloud Monitoring: monitora le metriche della pipeline Dataform, come le durate di esecuzione, le compilazioni attive e le percentuali di errore dei job del flusso di lavoro, tramite i riquadri della dashboard personalizzata.
Avvisi e qualità dei dati
Per garantire l'integrità dei dati e segnalare automaticamente gli errori della pipeline, configura gli avvisi utilizzando i seguenti meccanismi:
Asserzioni sulla qualità dei dati
Puoi definire regole di convalida dei dati personalizzate (ad es. assicurandoti che una colonna non sia mai nulla, verificando che le chiavi primarie siano univoche o convalidando gli intervalli numerici) creando file di asserzione .sqlx.
- Puoi fornire un file di asserzioni personalizzato utilizzando il parametro
--assertions:bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx - Durante l'esecuzione della pipeline, Dataform esegue queste query di convalida. Se una query di asserzione restituisce una o più righe, la convalida non riesce e l'esecuzione della pipeline viene immediatamente contrassegnata come non riuscita.
- Per ulteriori informazioni sulla scrittura delle regole di convalida dei dati, consulta la documentazione ufficiale sulle asserzioni di Dataform.
File di asserzione di esempio (assertions.sqlx)
Esempio di una query di asserzione Dataform che verifica la presenza di valori NULL e record cliente duplicati. Se questa query restituisce righe, l'asserzione non riesce e interrompe il flusso di lavoro di esecuzione:
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
)
Policy di avviso di Cloud Alerting
Configura le policy di avviso standard Google Cloud per inviare una notifica ai team di progettazione o operativi quando si verificano problemi:
- Avvisi basati sui log: crea avvisi in Cloud Logging che vengono attivati quando nei log vengono rilevati eventi di errore, esecuzioni del flusso di lavoro non riuscite o problemi del compilatore.
- Avvisi basati sulle metriche: definisci le soglie in Cloud Monitoring in base alla durata dell'esecuzione o agli errori di compilazione.
- Canali di notifica: configura questi avvisi per indirizzare i problemi ai canali di comunicazione preferiti del tuo team.