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 クライアントをインストールします。
%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年」です。
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 | モデル予測のグラウンド トゥルースを含む列。 |
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 クエリ エクスプローラーでクエリを実行し、カタログ エクスプローラーで表示できます。
モニターに関連付けられているすべての更新の履歴を表示するには、 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"]
)
)
)
イベントタイプごとに最大 5 つの Eメール アドレスがサポートされています (例: 「on_failure」)。
メトリクステーブルへのアクセスを制御する
モニターによって作成されたメトリクステーブルとダッシュボードは、モニターを作成したユーザーが所有しています。 Unity Catalog権限を使用して、メトリクステーブルへのアクセスを制御できます。ワークスペース内でダッシュボードを共有するには、ダッシュボードの右上にある [共有 ] ボタンを使用します。
モニターを削除する
モニターを削除するには:
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{table_name}")
このコマンドでは、モニターによって作成されたプロファイル テーブルとダッシュボードは削除されません。 これらのアセットは、別の手順で削除する必要があります。または、別の場所に保存することもできます。
ノートブックの例
次のノートブックの例は、モニターの作成方法、モニターの更新方法、およびモニターが作成するメトリクステーブルを調べる方法を示しています。
ノートブックの例: 時系列プロファイル
このノートブックでは、 TimeSeries
タイプのモニターを作成する方法を示します。
TimeSeries レイクハウス Monitor example ノートブック
ノートブックの例: 推論プロファイル (回帰)
このノートブックでは、回帰問題の InferenceLog
タイプ モニターを作成する方法を示します。
推論レイクハウス モニター回帰サンプル ノートブック
ノートブックの例: 推論プロファイル (分類)
このノートブックでは、分類問題の InferenceLog
型モニターを作成する方法を示します。
推論レイクハウスモニター分類例ノートブック
ノートブックの例: スナップショット プロファイル
このノートブックでは、 Snapshot
タイプのモニターを作成する方法を示します。