共用方式為

使用 API 建立監視器

  • 發行項

此頁面描述如何使用 Databricks SDK 在 Databricks 中建立監視器，並描述 API 呼叫中使用的所有參數。 您也可以使用 REST API 來建立和管理監視器。 如需參考資訊，請參閱 Lakehouse 監視 SDK 參考和 REST API 參考。

您可以在 Unity 目錄中註冊的任何 Managed 或外部 Delta 數據表上建立監視器。 在任何數據表的 Unity 目錄中繼存放區中只能建立單一監視器。

需求

Lakehouse Monitoring API 建置於 databricks-sdk 0.28.0 和更高版本中。 若要使用最新版本的 API，請在筆記本的開頭使用下列命令來安裝 Python 用戶端：

%pip install "databricks-sdk>=0.28.0"

若要進行驗證以在您的環境中使用 Databricks SDK，請參閱驗證。

設定檔類型

當您建立監視器時，您可以選取下列其中一種配置檔類型：TimeSeries、InferenceLog 或 Snapshot。 本節簡短說明每個選項。 如需詳細資訊，請參閱 API 參考或 REST API 參考。

注意

  • 當您第一次建立時間序列或推斷設定檔時，監視器只會分析其建立前 30 天的資料。 建立監視器之後，就會處理所有新資料。
  • 具體化檢視和串流數據表上定義的監視器不支援累加處理。

提示

針對 TimeSeries 和 Inference 配置檔，最佳做法是在您的數據表上啟用變更數據摘要 （CDF）。 啟用CDF時，只會處理新附加的數據，而不是每次重新整理重新處理整個數據表。 如此一來，當您跨多個數據表調整監視規模時，執行會更有效率並降低成本。

TimeSeries 設定檔

TimeSeries 設定檔會比較跨時間範圍的資料分佈。 對於 TimeSeries 設定檔，必須提供下列內容：

  • 時間戳欄位（timestamp_col）。 timestamp 時間戳欄位的資料類型必須是 TIMESTAMP，或是可以使用 PySpark 函式 to_timestamp轉換成時間戳的類型。
  • 用來計算指標的 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 包含用於預測之模型標識碼的數據行。
granularities 決定如何在時段之間分割數據。 可能的值：「5 分鐘」、“30 分鐘”、“1 小時”、“1 天”、“1 周”、“2 周”、“3 周”、“4 周”、“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 目錄數據表。 您可以在筆記本或 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 目錄權限來控制計量資料表的存取權。 若要在工作區內共用儀表板，請使用儀表板右上角的 [共用] 按鈕。

刪除監視器

若要刪除監視器：

from databricks.sdk import WorkspaceClient

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

此命令不會刪除監視器所建立的配置檔數據表和儀錶板。 您必須在單獨的步驟中刪除這些資產，或者可以將它們儲存在不同位置。

筆記本範例

下列範例筆記本說明如何建立監視器、重新整理監視器，以及檢查它所建立的計量數據表。

筆記本範例：時間序列設定檔

此筆記本說明如何建立 TimeSeries 類型監視器。

TimeSeries Lakehouse 監視器範例筆記本

取得筆記本

筆記本範例：推斷設定檔 (迴歸)

此筆記本說明如何建立迴歸問題的 InferenceLog 類型監視器。

推斷 Lakehouse 監視器迴歸範例筆記本

取得筆記本

筆記本範例：推斷設定檔 (分類)

此筆記本說明如何建立分類問題的 InferenceLog 類型監視器。

推斷 Lakehouse 監視器分類範例筆記本

取得筆記本

筆記本範例：快照設定檔

此筆記本說明如何建立 Snapshot 類型監視器。

Snapshot Lakehouse 監視器範例筆記本

取得筆記本