Beobachtbarkeit des Cortex Framework

Für den erfolgreichen Betrieb von Datenplattformen der Enterprise-Klasse ist es entscheidend, Einblick in die Pipelineausführung, die Datenqualität und betriebliche Fehler zu haben.

Das Cortex Framework kategorisiert die Beobachtbarkeit in zwei verschiedene Lebenszyklen:

  1. Beobachtbarkeit bei der Bereitstellung: Nachverfolgung der Konfigurationslast, der Vorlagenkompilierung, der Validierungsprüfungen, der Bereitstellungsaktionen und der API-Telemetrie während der Ausführung von CLI-Tools.
  2. Beobachtbarkeit zur Laufzeit: Nachverfolgung der Ausführung, des Pipelinefortschritts, der Abfrageleistung, der Zusicherungen zur Datenqualität und der automatischen Benachrichtigungen für die bereitgestellten Datenpipelines, die in ausgeführt werden Google Cloud.

Beobachtbarkeit bei der Bereitstellung

Die Beobachtbarkeit bei der Bereitstellung konzentriert sich auf die Ausführung der CLI-Tools (z.B. uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync).

Lokales Konsolen-Logging

Wenn Sie CLI-Befehle ausführen, protokolliert das Cortex Framework den Fortschritt direkt in der Konsole (stdout).

  • Logebene: Standardmäßig werden Logs auf der Ebene INFO ausgegeben.
  • Visuelle Hervorhebungen: Nachrichten sind farblich gekennzeichnet, um Fehler und Warnungen dynamisch hervorzuheben:
    • ❌ Fehler (rot) weisen auf kritische Fehler hin, die die Ausführung anhalten.
    • ⚠️ Warnungen (orange) weisen auf potenzielle Konfigurationsanomalien oder nicht blockierende Probleme hin.
  • Zeitstempel und Quelle: In jeder Logzeile werden die Ausführungszeit und die Namen der aktiven Python-Klassen oder -Module für eine genaue Nachverfolgung angezeigt.

Permanente lokale Logdateien

Bei jeder Befehlsausführung streamt der Python-Orchestrator das vollständige Ausführungsprotokoll automatisch in eine temporäre Logdatei im temporären Verzeichnis Ihres Systems:

/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log

Der genaue Pfad wird beim Starten der CLI-Tools in der Konsole ausgegeben. Diese Dateien enthalten umfassende Logdetails (einschließlich Stacktraces für unerwartete Fehler) und sind bei der Fehlerbehebung von Problemen, die bei der Ausführung der CLI-Tools auftreten, oder beim Anhängen an Supportanfragen von unschätzbarem Wert.

Google Cloud Umgebungsvalidierung

Vor dem Ausführen von Build-, Bereitstellungs- oder Synchronisierungsaktionen führt die Orchestrierungs-Engine das Dienstprogramm GcpEnvironmentChecker aus. Bei dieser Prüfung wird Folgendes validiert:

  1. Erforderliche APIs: Bestätigt, dass wichtige Google Cloud APIs aktiviert sind (z.B. bigquery.googleapis.com, dataform.googleapis.com).
  2. Vorhandensein von Datasets: Prüft, ob die erforderlichen Rohdaten- und Zieldatasets vorhanden sind oder erstellt werden können.
  3. Standorte und Regionen: Stellt sicher, dass die Zieldatasets mit den geografischen Regionen der Quelldatasets übereinstimmen.
  4. Kapazität und Einstellungen: Validiert Reservierungseinstellungen und Katalogkonfigurationen.

Jede Abweichung wird als Fehler protokolliert und enthält empfohlene Hinweise zur Behebung, bevor Google Cloud Dienstaufrufe erfolgen.

Telemetrie

Während der Bereitstellungs- und Synchronisierungsprozesse protokolliert das Cortex Framework anonyme Telemetriedaten zu Einführung, Variante und Framework-Version in Google Cloud. Weitere Informationen zur Funktionsweise und Anleitungen zum Deaktivieren finden Sie unter Telemetrie.

Beobachtbarkeit zur Laufzeit

Nach dem Erstellen und Bereitstellen werden die konformen Datenschichten und Datenprodukte des Cortex Framework vollständig in Dataform und BigQuery ausgeführt. Daher ist die Beobachtbarkeit zur Laufzeit direkt in die Google Cloud Betriebssuiten integriert.

Logging der Pipelineausführung

Alle bereitgestellten Pipelines werden mit Cloud Logging und Ausführungstools nachverfolgt:

  • Dataform-Ausführungsprotokolle: Dataform protokolliert jedes Kompilierungs- und Ausführungsereignis. Diese Details können in der Google Cloud Konsole oder programmatisch über die Dataform API aufgerufen werden.
  • BigQuery-Jobverlauf: Für jede Tabelle und Ansicht, die von Ihren Dataform-Pipelines materialisiert wird, werden SQL-Abfragen in BigQuery ausgeführt. Die detaillierte Ressourcennutzung, die Abfrageleistung, die verarbeiteten Byte und die Zeitstempel der Ausführung werden im BigQuery-Jobverlauf protokolliert.

Pipeline-Monitoring

Sie können den Pipelinestatus, die Releasekonfigurationen und den Ausführungsverlauf visuell oder programmatisch überwachen:

  1. Dataform-Web-UI: Rufen Sie die Dataform-Konsole auf, um Folgendes zu tun:
    • Kompilierte Datenmodelle prüfen und das kompilierte Diagramm visualisieren.
    • Den Status von Releasekonfigurationen, kompilierten Vorlagen und aktiven Umgebungen prüfen.
    • Den Verlauf und die Details aktueller und vergangener Workflowausführungen überwachen.
  2. Cloud Monitoring-Integration: Dataform-Pipelinemesswerte wie Ausführungsdauer, aktive Kompilierungen und Fehlerraten von Workflowjobs über benutzerdefinierte Dashboard-Panels nachverfolgen.

Benachrichtigungen und Datenqualität

Um die Datenintegrität zu gewährleisten und Pipelinefehler automatisch zu kennzeichnen, konfigurieren Sie Benachrichtigungen mit den folgenden Mechanismen:

Zusicherungen zur Datenqualität

Sie können benutzerdefinierte Regeln zur Datenvalidierung definieren (z.B. sicherstellen, dass eine Spalte nie null ist, prüfen, ob Primärschlüssel eindeutig sind, oder numerische Bereiche validieren), indem Sie .sqlx-Zusicherungsdateien erstellen.

  • Sie können eine benutzerdefinierte Zusicherungsdatei mit dem --assertions Parameter angeben: bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
  • Während der Pipelineausführung führt Dataform diese Validierungsabfragen aus. Wenn eine Zusicherungsabfrage eine oder mehrere Zeilen zurückgibt, schlägt die Validierung fehl und die Pipelineausführung wird sofort als fehlgeschlagen markiert.
  • Weitere Informationen zum Schreiben von Regeln zur Datenvalidierung finden Sie in der offiziellen Dataform-Dokumentation zu Zusicherungen.

Beispiel für eine Zusicherungsdatei (assertions.sqlx)

Beispiel für eine Dataform-Zusicherungsabfrage, die nach NULL-Werten und doppelten Kundendatensätzen sucht. Wenn diese Abfrage Zeilen zurückgibt, schlägt die Zusicherung fehl und der Ausführungsworkflow wird beendet:

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
)

Cloud Alerting-Richtlinien

Richten Sie Standard-Google Cloud Benachrichtigungsrichtlinien ein, um Ihre Engineering- oder Betriebsteams zu benachrichtigen, wenn Probleme auftreten:

  • Logbasierte Benachrichtigungen: Erstellen Sie Benachrichtigungen in Cloud Logging, die ausgelöst werden, wenn in Ihren Logs Fehlerereignisse, fehlgeschlagene Workflowausführungen oder Compilerprobleme erkannt werden.
  • Messwertbasierte Benachrichtigungen: Definieren Sie in Cloud Monitoring Schwellenwerte basierend auf der Ausführungsdauer oder Kompilierungsfehlern.
  • Benachrichtigungskanäle: Konfigurieren Sie diese Benachrichtigungen so, dass Probleme an die bevorzugten Kommunikationskanäle Ihres Teams weitergeleitet werden.