Cortex Framework 可觀測性

如要順利執行及運作企業級資料平台，瞭解管道執行情況、資料品質和作業錯誤至關重要。

Cortex Framework 會根據兩個不同的生命週期，將可觀測性分類：

  1. 部署時可觀測性：在執行 CLI 工具時，追蹤設定載入、範本編譯、驗證檢查、部署動作和 API 遙測。
  2. 執行階段可觀測性：追蹤在 Google Cloud中執行的已部署資料管道，包括執行作業、管道進度、查詢效能、資料品質斷言，以及自動警報。

部署期間觀測功能

部署時可觀測性著重於 CLI 工具的執行情況 (例如 uv run cortex-build、uv run cortex-deploy、uv run cortex-build-and-deploy、uv run cortex-demo、uv run cortex-kc-sync)。

本機控制台記錄

執行 CLI 指令時，Cortex Framework 會直接在控制台 (stdout) 中記錄進度。

  • 記錄層級：依預設，系統會輸出 INFO 層級的記錄。
  • 視覺重點：系統會以顏色標示訊息，動態醒目顯示錯誤和警告：
    • ❌ 錯誤 (紅色)：表示導致執行作業停止的重大失敗。
    • ⚠️ 警告 (橘色)：表示可能出現設定異常或非阻礙性問題。
  • 時間戳記和來源：每行記錄都會顯示執行時間，以及用於精確追蹤的有效 Python 類別或模組名稱。

永久本機記錄檔

每次執行指令時，Python 協調器都會自動將完整的執行記錄串流至系統暫時目錄中的暫時記錄檔：

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

啟動 CLI 工具時，主控台會列印確切路徑。這些檔案包含完整的記錄詳細資料 (包括非預期錯誤的堆疊追蹤)，對於偵錯 CLI 工具執行期間或附加至支援要求時遇到的問題，非常有價值。

Google Cloud 環境驗證

執行建構、部署或同步處理動作之前，自動化調度管理引擎會執行 GcpEnvironmentChecker 公用程式。這項檢查會驗證：

  1. 必要 API：確認已啟用重要 Google Cloud API (例如 bigquery.googleapis.com、dataform.googleapis.com)。
  2. 資料集存在：驗證必要的原始和目標資料集是否存在，或是否可建立。
  3. 位置和區域：確保目標資料集與來源資料集的地理區域相符。
  4. 容量和設定：驗證預訂設定和目錄設定。

如果出現任何不符情況，系統會將其記錄為錯誤，並提供建議提示，說明如何在發出 Google Cloud 服務呼叫前解決問題。

遙測

在部署和同步處理程序期間，Cortex Framework 會將匿名採用、變體和架構版本遙測資料記錄到 Google Cloud。如要瞭解這項功能的運作方式，以及如何停用，請參閱「遙測」。

執行階段觀測

建構及部署完成後，Cortex Framework 相容的資料層和資料產品就會完全在 Dataform 和 BigQuery 中執行。因此，執行階段可觀測性會直接與 Google Cloud 作業套件整合。

管道執行記錄

所有已部署的管道都會使用 Cloud Logging 和執行工具追蹤：

  • Dataform 執行記錄：Dataform 會記錄每個編譯和執行事件。您可以在 Google Cloud 控制台中存取這些詳細資料，也可以使用 Dataform API 以程式輔助方式存取。
  • BigQuery 工作記錄：Dataform pipeline 具體化的每個資料表和檢視區塊，都會在 BigQuery 內執行 SQL 查詢。詳細的資源用量、查詢效能、處理的位元組和執行時間戳記，都會記錄在 BigQuery 工作記錄中。

管道監控

您可以透過視覺化或程式輔助方式，監控管道健康狀態、發布設定和執行記錄：

  1. Dataform 網頁版 UI：前往 Dataform 控制台，即可：
    • 檢查已編譯的資料模型，並以視覺化方式呈現已編譯的圖表。
    • 確認發布設定、已編譯範本和有效環境的狀態。
    • 監控目前和過去的工作流程執行記錄和詳細資料。
  2. 整合 Cloud Monitoring：透過自訂資訊主頁面板，追蹤 Dataform 管道指標，例如執行時間、有效編譯和工作流程工作失敗率。

快訊與資料品質

如要確保資料完整性並自動標記管道失敗，請使用下列機制設定快訊：

資料品質斷言

您可以建立.sqlx斷言檔案，定義自訂資料驗證規則 (例如確保資料欄永不為空值、檢查主鍵是否為唯一值，或驗證數值範圍)。

  • 您可以使用 --assertions 參數提供自訂斷言檔案： bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
  • 在管道執行期間，Dataform 會執行這些驗證查詢。如果斷言查詢傳回一或多個資料列，驗證就會失敗，且管道執行作業會立即標示為失敗。
  • 如要進一步瞭解如何編寫資料驗證規則，請參閱 Dataform 斷言官方說明文件。

範例聲明檔案 (assertions.sqlx)

以下是 Dataform 判斷提示查詢範例，可檢查 NULL 值和重複的顧客記錄。如果這項查詢傳回任何資料列，就會導致判斷結果為失敗，並停止執行工作流程：

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 政策

設定標準Google Cloud 快訊政策，在發生問題時通知工程或營運團隊：

  • 以記錄為基礎的快訊：在 Cloud Logging 中建立快訊，在記錄中偵測到錯誤事件、工作流程執行失敗或編譯器問題時觸發。
  • 以指標為準的快訊：在 Cloud Monitoring 中，根據執行時間或編譯失敗次數定義門檻。
  • 通知管道：設定這些快訊，將問題傳送至團隊偏好的通訊管道