APIを使用したモニターの作成
このページでは、Databricks SDK を使用して Databricks でモニターを作成する方法と、API 呼び出しで使用されるすべてのパラメーターについて説明します。 REST API を使用してモニターを作成および管理することもできます。 参考情報については、 レイクハウス モニタリングSDKリファレンスおよびREST APIリファレンスをご覧ください。
Unity Catalogに登録されている任意のマネージド Delta テーブルまたは外部 Delta テーブルにモニターを作成できます。どのテーブルに対しても、 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 日"、"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
プロファイルの場合、以下のパラメーターが必要です。
パラメーター |
説明 |
---|---|
|
|
|
モデルの予測値を含む列。 |
|
推論要求のタイムスタンプを含む列。 |
|
予測に使用されるモデルの id を含む列。 |
|
時間の経過に伴うウィンドウ内のデータのパーティション分割方法を決定します。 可能な値: "5 分"、"30 分"、"1 時間"、"1 日"、"n 週間"、"1 か月"、"1 年"。 |
オプションのパラメーターもあります。
省略可能なパラメーター |
説明 |
---|---|
|
モデル予測のグラウンドトゥルースを含む列。 |
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 つの電子メール アドレスがサポートされます (たとえば、「on_failure」)。
メトリクステーブルへのアクセスを制御する
モニターによって作成されたメトリクステーブルとダッシュボードは、モニターを作成したユーザーが所有します。 Unity Catalog 権限を使用して、メトリクステーブルへのアクセスを制御できます。ワークスペース内でダッシュボードを共有するには、ダッシュボードの右上にある [ 共有 ] ボタンを使用します。