Erstellen eines Monitors mithilfe der API

  • Artikel

Auf dieser Seite wird beschrieben, wie Sie mithilfe des Databricks SDK einen Monitor in Databricks erstellen, und es werden alle Parameter beschrieben, die in API-Aufrufen verwendet werden. Sie können Monitore auch mithilfe der REST-API erstellen und verwalten. Referenzinformationen finden Sie in der SDK-Referenz zur Lakehouse-Überwachung und der REST-API-Referenz.

Sie können einen Monitor für jede verwaltete oder externe Delta-Tabelle erstellen, die in Unity Catalog registriert ist. Nur ein einzelner Monitor kann in einem Unity Catalog-Metastore für eine beliebige Tabelle erstellt werden.

Anforderungen

Die Lakehouse Monitoring API ist in databricks-sdk 0.28.0 und höher integriert. Wenn Sie die neueste Version der API verwenden, verwenden Sie den folgenden Befehl am Anfang Ihres Notebooks, um den Python-Client zu installieren:

%pip install "databricks-sdk>=0.28.0"

Informationen zur Authentifizierung zur Verwendung der Databricks SDK in Ihrer Umgebung finden Sie unter Authentifizierung.

Profiltypen

Wenn Sie einen Monitor erstellen, wählen Sie einen der folgenden Profiltypen aus: TimeSeries, InferenceLog oder Snapshot. In diesem Abschnitt werden die einzelnen Optionen kurz beschrieben. Ausführliche Informationen finden Sie in der API-Referenz oder in der REST-API-Referenz.

Hinweis

  • Wenn Sie zum ersten Mal eine Zeitreihe oder ein Rückschlussprofil erstellen, analysiert der Monitor nur Daten aus den 30 Tagen vor der Erstellung. Nachdem der Monitor erstellt wurde, werden alle neuen Daten verarbeitet.
  • Monitore, die für materialisierte Ansichten definiert sind, und Streamingtabellen unterstützen keine inkrementelle Verarbeitung.

Tipp

Für TimeSeries- und Inference-Profile ist es eine bewährte Praxis, den Änderungsdaten-Feed (CDF) auf Ihrer Tabelle zu aktivieren. Wenn CDF aktiviert ist, werden nur neu angefügte Daten verarbeitet, anstatt die gesamte Tabelle bei jeder Aktualisierung erneut zu verarbeiten. Dadurch wird die Ausführung effizienter und die Kosten reduziert, während Sie die Überwachung über viele Tabellen hinweg skalieren.

TimeSeries-Profile

EinTimeSeries-Profil vergleicht Datenverteilungen über Zeitfenster hinweg. Für ein TimeSeries-Profil müssen Sie Folgendes angeben:

  • Eine Zeitstempelspalte (timestamp_col). Beim Datentyp der Zeitstempelspalte muss es sich entweder um TIMESTAMP oder einen Typ handeln, der mithilfe der to_timestamp PySpark-Funktion in Zeitstempel konvertiert werden kann.
  • Das granularities-Set, für das Metriken berechnet werden sollen. Verfügbare Granularitäten sind „5 Minuten“, „30 Minuten“, „1 Stunde“, „1 Tag“, „n Woche(n)“, „1 Monat“, „1 Jahr“.
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-Profile

Ein InferenceLog-Profil ähnelt einem TimeSeries-Profil, enthält aber auch Metriken für die Modellqualität. Für ein InferenceLog-Profil sind die folgenden Parameter erforderlich:

Parameter Beschreibung
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION oder MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col Spalte mit den vorhergesagten Werten des Modells.
timestamp_col Spalte, die den Zeitstempel der Rückschlussanforderung enthält.
model_id_col Spalte mit der ID des Modells, das für die Vorhersage verwendet wird.
granularities Bestimmt, wie die Daten in Fenstern im Zeitrahmen partitioniert werden. Mögliche Werte: „5 Minuten“, „30 Minuten“, „1 Stunde“, „1 Tag“, „n Woche(n)“, „1 Monat“, „1 Jahr“.

Es gibt auch einen optionalen Parameter:

Optionaler Parameter: Beschreibung
label_col Spalte mit der Grundwahrheit für Modellvorhersagen. 
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
  )
)

Für InferenceLog-Profile werden basierend auf den unterschiedlichen Werten von model_id_col automatisch Slices erstellt.

Snapshot-Profile

Im Gegensatz zu TimeSeries überwacht ein Snapshot-Profil, wie sich der vollständige Inhalt der Tabelle im Laufe der Zeit ändert. Metriken werden für alle Daten in der Tabelle berechnet und überwachen den Tabellenzustand bei jeder Aktualisierung des Monitors.

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()
)

Aktualisieren und Anzeigen der Überwachungsergebnisse

Verwenden Sie run_refresh zum Aktualisieren von Metriktabellen. Beispiel:

from databricks.sdk import WorkspaceClient

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

Wenn Sie von einem Notebook aus run_refresh aufrufen, werden die Monitormetriktabellen erstellt oder aktualisiert. Diese Berechnung wird auf serverlosem Compute ausgeführt, nicht auf dem Cluster, an den das Notebook angefügt ist. Sie können weiterhin Befehle im Notebook ausführen, während die Monitorstatistiken aktualisiert werden.

Informationen zu den In Metriktabellen gespeicherten Statistiken finden Sie unter Monitormetriktabellen. Metriktabellen sind Unity Catalog-Tabellen. Sie können sie in Notebooks oder im SQL-Abfrage-Explorer abfragen und im Katalog-Explorer anzeigen.

Verwenden Sie list_refreshes, um den Verlauf aller Aktualisierungen anzuzeigen, die einem Monitor zugeordnet sind.

from databricks.sdk import WorkspaceClient

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

Verwenden Sie get_refresh zum Abrufen des Status einer bestimmten Ausführung, die in die Warteschlange eingereiht, ausgeführt oder beendet wurde.

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
)

Um eine Aktualisierung abzubrechen, die in die Warteschlange gestellt wurde oder ausgeführt wird, verwenden Sie 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
)

Anzeigen der Monitoreinstellungen

Sie können die Monitoreinstellungen mithilfe der API get_monitorüberprüfen.

from databricks.sdk import WorkspaceClient

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

Planen

Verwenden Sie den Parameter schedule von create_monitor, um einen Monitor für die geplante Ausführung einzurichten:

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

Weitere Informationen finden Sie unter Cron-Ausdrücke.

Benachrichtigungen

Verwenden Sie den notifications-Parameter von create_monitor, um Benachrichtigungen für die Überwachung einzurichten:

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

Pro Ereignistyp werden maximal fünf E-Mail-Adressen unterstützt (z. B. „on_failure“).

Steuern des Zugriffs auf Metriktabellen

Die Metriktabellen und Dashboard, die von einer Überwachung erstellt werden, gehören dem/r Benutzer*in, der/die die Überwachung erstellt hat. Sie können mit Unity Catalog-Berechtigungen den Zugriff auf Metriktabellen steuern. Wenn Sie Dashboards in einem Arbeitsbereich freigeben möchten, klicken Sie oben rechts im Dashboard auf die Schaltfläche Freigeben.

Löschen eines Monitors

So löschen Sie einen Monitor:

from databricks.sdk import WorkspaceClient

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

Mit diesem Befehl werden die vom Monitor erstellten Profiltabellen und das Dashboard nicht gelöscht. Sie müssen diese Ressourcen in einem separaten Schritt löschen, oder Sie können sie an einem anderen Speicherort speichern.

Beispielnotebooks

Die folgenden Beispielnotebooks veranschaulichen, wie Sie einen Monitor erstellen, den Monitor aktualisieren und die erstellten Metriktabellen untersuchen.

Notebookbeispiel: Zeitreihenprofil

Dieses Notebook veranschaulicht, wie ein Monitor des Typs TimeSeries erstellt wird.

Beispielnotebook für TimeSeries-Lakehouse Monitor

Notebook abrufen

Notebookbeispiel: Rückschlussprofil (Regression)

In diesem Notebook wird veranschaulicht, wie Sie einen Monitor des Typs InferenceLog für ein Regressionsproblem erstellen.

Beispielnotebook für die Inference-Lakehouse Monitor-Regression

Notebook abrufen

Notebookbeispiel: Rückschlussprofil (Klassifizierung)

In diesem Notebook wird veranschaulicht, wie Sie einen Monitor des Typs InferenceLog für ein Klassifizierungsproblem erstellen.

Beispielnotebook für die Inference-Lakehouse-Monitor-Klassifizierung

Notebook abrufen

Notebookbeispiel: Snapshotprofil

Dieses Notebook veranschaulicht, wie ein Monitor des Typs Snapshot erstellt wird.

Beispielnotebook für Snapshot-Lakehouse Monitor

Notebook abrufen