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

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

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

必要条件

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

Python

%pip install "databricks-sdk>=0.28.0"

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

プロファイルの種類

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

注記

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

ヒント

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

TimeSeries プロファイル

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

• タイムスタンプ列 (timestamp_col)。 タイムスタンプ列のデータ型は、 TIMESTAMP であるか、 to_timestamp PySpark 関数を使用してタイムスタンプに変換できる型である必要があります。
• メトリクスを計算する granularities のセット。 使用可能な粒度は、「5分」、「30分」、「1時間」、「1日」、「1週間」、「2週間」、「3週間」、「4週間」、「1か月」、「1年」です。

Python

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 minutes"、"30 minutes"、"1 hour"、"1 day"、"1 week"、"2 weeks"、"3 weeks"、"4 weeks"、"1 month"、"1 year"。

オプションのパラメーターもあります。

省略可能なパラメーター	説明
label_col	モデル予測のグラウンド トゥルースを含む列。

Python

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 プロファイルは、テーブルの完全な内容が時間の経過と共にどのように変化するかを監視します。メトリクスは、テーブル内のすべてのデータに対して計算され、モニターが更新されるたびにテーブルの状態をモニターします。

Python

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を使用します。 例えば：

Python

from databricks.sdk import WorkspaceClient

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

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

メトリクステーブルに保存されている統計に関する情報については、「 メトリクステーブルのモニタリング メトリクステーブルは Unity Catalog テーブルです」を参照してください。 ノートブックまたは SQL クエリ エクスプローラーでクエリを実行し、カタログ エクスプローラーで表示できます。

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

Python

from databricks.sdk import WorkspaceClient

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

キューに登録された、実行中、または完了した特定の実行のステータスを取得するには、 get_refreshを使用します。

Python

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を使用します。

Python

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を使用して確認できます。

Python

from databricks.sdk import WorkspaceClient

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

計画

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

Python

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 パラメーターを使用します。

Python

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"]
        )
    )
)

イベントタイプごとに最大 5 つの Eメール アドレスがサポートされています (例: 「on_failure」)。

メトリクステーブルへのアクセスを制御する

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

モニターを削除する

モニターを削除するには:

Python

from databricks.sdk import WorkspaceClient

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

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

ノートブックの例

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

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

このノートブックでは、 TimeSeries タイプのモニターを作成する方法を示します。

TimeSeries レイクハウス Monitor example ノートブック

Open notebook in new tab

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

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

推論レイクハウス モニター回帰サンプル ノートブック

Open notebook in new tab

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

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

推論レイクハウスモニター分類例ノートブック

Open notebook in new tab

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

このノートブックでは、 Snapshot タイプのモニターを作成する方法を示します。

スナップショット レイクハウス Monitor example ノートブック

Open notebook in new tab