API を使用したモニターの作成

プレビュー

この機能はパブリックプレビュー段階です。

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

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

要件

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

%pip install "https://ml-team-public-read.s3.amazonaws.com/wheels/data-monitoring/a4050ef7-b183-47a1-a145-e614628e3146/databricks_lakehouse_monitoring-0.4.14-py3-none-any.whl"

Profile type パラメーター

profile_typeは、テーブルのコンピュートを監視するメトリクスのクラスを決定します。 TimeSeries、InferenceLog、スナップショットの 3 種類があります。 このセクションでは、問題について簡単に説明します。 詳細については、 API リファレンスまたはREST API リファレンス を参照してください。

注:

  • 時系列プロファイルまたは推論プロファイルを作成すると、モニターはモニターの作成時から最大 30 日をさかのぼります。 30日以上経過したデータは含みません。

  • マテリアライズド ビューおよびストリーミング テーブルで定義されたモニターは、増分処理をサポートしません。

TimeSeries プロフィール

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

  • タイムスタンプ列 (timestamp_col)。 タイムスタンプ列のデータ型は、 TIMESTAMP であるか、 to_timestamp PySpark 関数を使用してタイムスタンプに変換できる型である必要があります。

  • メトリクスを計算する granularities のセット。 使用可能な粒度は、"5 分"、"30 分"、"1 時間"、"1 日"、"n 週間"、"1 か月"、"1 年" です。

from databricks import lakehouse_monitoring as lm

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.TimeSeries(
        timestamp_col="ts",
        granularities=["30 minutes"]
    ),
    output_schema_name=f"{catalog}.{schema}"
)

InferenceLog プロフィール

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

パラメーター

説明

problem_type

「分類」または「回帰」。

prediction_col

モデルの予測値を含む列。

timestamp_col

推論要求のタイムスタンプを含む列。

model_id_col

予測に使用されるモデルの id を含む列。

granularities

時間の経過に伴うウィンドウ内のデータのパーティション分割方法を決定します。 可能な値: "5 分"、"30 分"、"1 時間"、"1 日"、"n 週間"、"1 か月"、"1 年"。

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

省略可能なパラメーター

説明

label_col

モデル予測のグラウンドトゥルースを含む列。

from databricks import lakehouse_monitoring as lm

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.InferenceLog(
        problem_type="classification",
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
    ),
    output_schema_name=f"{catalog}.{schema}"
)

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

Snapshot プロフィール

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

from databricks import lakehouse_monitoring as lm

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.Snapshot(),
    output_schema_name=f"{catalog}.{schema}"
)

モニター結果 の更新と表示

メトリクステーブルを更新するには、 run_refreshを使用します。 例えば:

from databricks import lakehouse_monitoring as lm

lm.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

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

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

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

from databricks import lakehouse_monitoring as lm

lm.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

キューに入れられた、実行中、または終了した特定の実行の状態を取得するには、 get_refreshを使用します。

from databricks import lakehouse_monitoring as lm

run_info = lm.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

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

キューに入れられている、または実行中の更新をキャンセルするには、 cancel_refreshを使用します。

from databricks import lakehouse_monitoring as lm

run_info = lm.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

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

モニター設定 の表示

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

from databricks import lakehouse_monitoring as lm

lm.get_monitor(table_name=TABLE_NAME)

計画

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

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.TimeSeries(
        timestamp_col="ts",
        granularities=["30 minutes"]
    ),
    schedule=lm.MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    ),
    output_schema_name=f"{catalog}.{schema}"
)

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

通知

モニターの通知を設定するには、 create_monitornotifications問題を使用します。

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.TimeSeries(
        timestamp_col="ts",
        granularities=["30 minutes"]
    ),
    notifications=lm.Notifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=lm.Destination(
            email_addresses=["your_email@domain.com"]
        )
    )
    output_schema_name=f"{catalog}.{schema}"
)

イベント タイプごとに最大 5 つの電子メール アドレスがサポートされます (たとえば、「on_failure」)。

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

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

モニター を削除する

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

lm.delete_monitor(table_name=TABLE_NAME)

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

ノートブック の例

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

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

このノートブックでは、 TimeSeries タイプのモニターを作成する方法について説明します。

時系列レイクハウスモニターのサンプルノートブック

ノートブックを新しいタブで開く

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

このノートブックでは、回帰問題の InferenceLog 型モニターを作成する方法について説明します。

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

ノートブックを新しいタブで開く

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

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

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

ノートブックを新しいタブで開く

ノートブックの例: Snapshot プロファイル

このノートブックでは、 Snapshot タイプのモニターを作成する方法について説明します。

スナップショットレイクハウスモニターサンプルノートブック

ノートブックを新しいタブで開く