API を使用してモニターを作成する

  • [アーティクル]

このページでは、Databricks SDK を使用して Databricks 内でモニターを作成する方法と、API 呼び出しで使用されるすべてのパラメーターについて説明します。 REST API を使用してモニターを作成および管理することもできます。 リファレンス情報については、「レイクハウス監視 SDK リファレンス」と「REST API リファレンス」をご参照ください。

Unity Catalog に登録されているマネージドまたは外部 Delta テーブルにモニターを作成できます。 任意のテーブルの Unity Catalog メタストアに作成できるモニターは 1 つだけです。

要件

レイクハウス監視 API は、databricks-sdk 0.28.0 以降に組み込まれています。 最新バージョンの API を使用するには、ノートブックの先頭で次のコマンドを使用して Python クライアントをインストールします。

%pip install "databricks-sdk>=0.28.0"

お使いの環境で Databricks SDK を使用するように認証するには、「認証」を参照してください。

プロファイルの種類

モニターを作成するときは、TimeSeries、InferenceLog、または Snapshot のいずれかのプロファイルの種類を選択します。 このセクションでは、各オプションについて簡単に説明します。 詳細については、API リファレンスまたは REST API リファレンスを参照してください。

Note

  • 時系列または推論プロファイルを初めて作成するとき、モニターは作成以前の 30 日間のデータのみを分析します。 モニターが作成された後は、すべての新しいデータが処理されます。
  • 具体化されたビューとストリーミング テーブルで定義されたモニターでは、増分処理はサポートされません。

ヒント

TimeSeries プロファイルと Inference プロファイルの場合は、テーブルで変更データ フィード (CDF) を有効にすることをお勧めします。 CDF を有効にすると、更新のたびにテーブル全体を再処理するのではなく、新しく追加されたデータのみが処理されます。 これにより、多くのテーブルで監視をスケーリングする際の実行効率が向上し、コストが削減されます。

TimeSeries プロファイル

TimeSeries プロファイルでは、時間枠間のデータ分布を比較します。 TimeSeries プロファイルの場合は、次の情報を指定する必要があります。

  • タイムスタンプ列 (timestamp_col)。 タイムスタンプ列のデータ型は、TIMESTAMP、または to_timestamp PySpark 関数を使用してタイムスタンプに変換できる型である必要があります。
  • メトリックの計算に使用する granularities のセット。 使用可能な細分性は、"5 分"、"30 分"、"1 時間"、"1 日"、"n 週"、"1 か月"、"1 年" です。
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"])
)

InferenceLog プロファイル

InferenceLog プロファイルは TimeSeries プロファイルに似ていますが、モデル品質メトリックも含まれます。 InferenceLog プロファイルの場合は、次のパラメーターが必要です。

パラメーター 説明
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION または MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col モデルの予測値を含む列。
timestamp_col 推論要求のタイムスタンプを含む列。
model_id_col 予測に使用されるモデルの ID を含む列。
granularities 時間をまたいでウィンドウ内のデータをパーティション分割する方法を決定します。 使用可能な値: "5 分"、"30 分"、"1 時間"、"1 日"、"n 週"、"1 か月"、"1 年"。

省略可能なパラメーターは以下のとおりです。

省略可能なパラメーター 説明
label_col モデル予測の実測値を含む列。 
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorInferenceLog, MonitorInferenceLogProblemType

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  inference_log=MonitorInferenceLog(
        problem_type=MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION,
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
  )
)

InferenceLog プロファイルの場合、スライスは model_id_col の個別の値に基づいて自動的に作成されます。

Snapshot プロファイル

TimeSeries とは対照的に、Snapshot プロファイルでは、テーブルの完全な内容が時間の経過とどのように変化するかを監視します。 メトリックは、テーブル内のすべてのデータに対して計算され、モニターが更新されるたびにテーブルの状態を監視します。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorSnapshot

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  snapshot=MonitorSnapshot()
)

モニターの結果を更新して表示する

メトリック テーブルを更新するには、run_refresh を使用します。 次に例を示します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

ノートブックから run_refresh を呼び出すと、モニター メトリック テーブルが作成または更新されます。 この計算は、ノートブックがアタッチされているクラスターではなく、サーバーレス コンピューティングで実行されます。 モニター統計の更新中は、引き続きノートブックでコマンドを実行できます。

メトリック テーブルに格納される統計の詳細については、「メトリック テーブルを監視する」「メトリック テーブルが Unity Catalog テーブルである」を参照してください。 ノートブックまたは SQL クエリ エクスプローラーでクエリを実行すると、Catalog Explorer に表示できます。

モニターに関連付けられているすべての更新の履歴を表示するには、list_refreshes を使用します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

キューに登録、実行、または完了した特定の実行の状態を取得するには、get_refresh を使用します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.get_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id = run_info.refresh_id
)

キューに挿入済みまたは実行中の更新を取り消すには、cancel_refresh を使用します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.cancel_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id=run_info.refresh_id
)

モニターの設定を表示する

API get_monitor を使用してモニターの設定を確認できます。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.get(f"{catalog}.{schema}.{table_name}")

スケジュール

スケジュールに基づいて実行するモニターを設定するには、create_monitor のうち schedule 個のパラメーターを使用します。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorCronSchedule

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  schedule=MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    )
)

詳細については、CRON 式を参照してください。

通知

モニターの通知を設定するには、create_monitor の notifications パラメーターを使用します。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorNotifications, MonitorDestination

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  notifications=MonitorNotifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=MonitorDestination(
            email_addresses=["your_email@domain.com"]
        )
    )
)

イベントの種類 (たとえば、"on_failure") ごとに最大 5 つのメール アドレスがサポートされます。

メトリック テーブルへのアクセスの制御

モニターで作成されたメトリック テーブルとダッシュボードは、モニターを作成したユーザーが所有します。 Unity Catalog 特権を使用して、メトリック テーブルへのアクセスを制御できます。 ワークスペース内でダッシュボードを共有するには、ダッシュボードの右上にある [共有] ボタンをクリックします。

モニターを削除する

モニターを削除するには、次のようにします。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{table_name}")

このコマンドでは、モニターで作成されたプロファイル テーブルとダッシュボードは削除されません。 これらの資産は、別の手順で削除するか、別の場所に保存する必要があります。

ノートブックの例

次のノートブック例では、モニターを作成し、モニターを更新し、作成するメトリック テーブルを調べる方法を示しています。

ノートブックの例l: 時系列プロファイル

このノートブックは、TimeSeries の種類のモニターを作成する方法を示しています。

TimeSeries Lakehouse Monitor ノートブックの例

ノートブックを入手

ノートブックの例: 推論プロファイル (回帰)

このノートブックは、回帰問題の InferenceLog の種類のモニターを作成する方法を示しています。

Inference Lakehouse Monitor 回帰のノートブックの例

ノートブックを入手

ノートブックの例: 推論プロファイル (分類)

このノートブックは、分類問題の InferenceLog の種類のモニターを作成する方法を示しています。

Inference Lakehouse Monitor 分類のノートブックの例

ノートブックを入手

ノートブックの例: スナップショット プロファイル

このノートブックは、Snapshot の種類のモニターを作成する方法を示しています。

Snapshot Lakehouse Monitor ノートブックの例

ノートブックを入手