Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Cortex Framework のオブザーバビリティ

エンタープライズグレードのデータプラットフォームを正常に実行して運用するには、パイプラインの実行、データ品質、運用エラーを可視化することが重要です。

Cortex Framework は、2 つの異なるライフサイクルにわたってオブザーバビリティを分類します。

デプロイ時のオブザーバビリティ: CLI ツールの実行中に、構成の読み込み、テンプレートのコンパイル、検証チェック、デプロイアクション、API テレメトリーを追跡します。
実行時のオブザーバビリティ: 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 オーケストレーターは完全な実行ログをシステムの temp ディレクトリにある一時ログファイルに自動的にストリーミングします。

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

正確なパスは、CLI ツールの起動時にコンソールに出力されます。これらのファイルには、包括的なログの詳細（予期しないエラーのスタックトレースを含む）が含まれており、CLI ツールの実行中に発生した問題のデバッグや、サポートリクエストへの添付に役立ちます。

Google Cloud 環境の検証

ビルド、デプロイ、同期のアクションを実行する前に、オーケストレーションエンジンは GcpEnvironmentChecker ユーティリティを実行します。このチェックでは、次のことを検証します。

必要な API: 重要な Google Cloud API（bigquery.googleapis.com、dataform.googleapis.com など）が有効になっていることを確認します。
データセットの存在: 必要な元データセットとターゲットデータセットが存在するか、作成可能であることを確認します。
ロケーションとリージョン: ターゲットデータセットがソースデータセットの地理的リージョンと一致していることを確認します。
容量と設定: 予約設定とカタログ構成を検証します。

不一致があった場合は、 Google Cloud サービスコールを行う前に不一致を解決する方法に関する推奨ヒントとともにエラーとして記録されます。

テレメトリー

デプロイプロセスと同期プロセス中に、Cortex Framework は匿名での導入、バリアント、フレームワークバージョンのテレメトリーを Google Cloudに記録します。この機能の仕組みとオプトアウトの手順については、テレメトリーをご覧ください。

ランタイムオブザーバビリティ

構築してデプロイすると、Cortex Framework に準拠したデータレイヤとデータプロダクトは、Dataform と BigQuery 内で完全に実行されます。その結果、ランタイムオブザーバビリティは Google Cloud オペレーションスイートと直接統合されます。

パイプライン実行のロギング

デプロイされたすべてのパイプラインは、Cloud Logging と実行ツールを使用して追跡されます。

Dataform 実行ログ: Dataform は、すべてのコンパイルイベントと実行イベントを記録します。これらの詳細は、 Google Cloud コンソールでアクセスするか、Dataform API を使用してプログラムでアクセスできます。
BigQuery ジョブ履歴: Dataform パイプラインによって実体化された各テーブルとビューは、BigQuery 内で SQL クエリを実行します。リソース使用率、クエリパフォーマンス、処理されたバイト数、実行タイムスタンプの詳細が BigQuery ジョブ履歴に記録されます。

パイプラインのモニタリング

パイプラインの健全性、リリース構成、実行履歴は、視覚的にまたはプログラムでモニタリングできます。

Dataform ウェブ UI: Dataform コンソールに移動して、次の操作を行います。
- コンパイルされたデータモデルを検査し、コンパイルされたグラフを可視化します。
- リリース構成、コンパイル済みテンプレート、アクティブな環境のステータスを確認します。
- 現在と過去のワークフロー実行の履歴と詳細をモニタリングします。
Cloud Monitoring の統合: カスタムダッシュボードパネルを使用して、実行時間、アクティブなコンパイル、ワークフロージョブの失敗率などの Dataform パイプライン指標を追跡します。

アラートとデータ品質

データの完全性を確保し、パイプラインの障害を自動的に検出するには、次のメカニズムを使用してアラートを構成します。

データ品質のアサーション

.sqlx アサーションファイルを作成することで、カスタムデータ検証ルール（列が null にならないようにする、主キーが一意であることを確認する、数値範囲を検証するなど）を定義できます。

--assertions パラメータを使用して、カスタムアサーションファイルを指定できます。 bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
パイプラインの実行中に、Dataform はこれらの検証クエリを実行します。アサーションクエリが 1 つ以上の行を返すと、検証は失敗し、パイプラインの実行は直ちに失敗としてマークされます。
データ検証ルールの作成の詳細については、Dataform アサーションの公式ドキュメントをご覧ください。

アサーションファイルの例（`assertions.sqlx`）

NULL 値と重複する顧客レコードをチェックする Dataform アサーションクエリの例。このクエリで行が返された場合、アサーションは失敗し、実行ワークフローが停止します。

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 でしきい値を定義します。
通知チャンネル: これらのアラートを設定して、チームが希望するコミュニケーションチャネルに問題を転送します。