Condividi tramite

Creare un monitoraggio usando l'API

  • Articolo

Questa pagina descrive come creare un monitoraggio in Databricks usando Databricks SDK e descrive tutti i parametri usati nelle chiamate API. È anche possibile creare e gestire i monitor usando l'API REST. Per informazioni di riferimento, consultare la documentazione del SDK di monitoraggio del Lakehouse e la documentazione dell'API REST.

È possibile creare un monitor su qualsiasi tabella Delta gestita o esterna registrata nel Unity Catalog. È possibile creare un solo monitor in un metastore del Unity Catalog per qualsiasi tabella.

Requisiti

La Lakehouse Monitoring API è integrata nella databricks-sdk 0.28.0 e nelle versioni successive. Per usare la versione più recente dell'API, usare il seguente comando all'inizio del notebook per installare il client Python:

%pip install "databricks-sdk>=0.28.0"

Per eseguire l'autenticazione per usare Databricks SDK nell'ambiente in uso, consultare Autenticazione.

Tipi di profilo

Quando si crea un monitor, selezionare uno dei tipi di profilo seguenti: TimeSeries, InferenceLog o Snapshot. Questa sezione descrive brevemente ogni opzione. Per informazioni dettagliate, consultare la documentazione dell'API o la documentazione dell'API REST.

Nota

  • Quando si crea per la prima volta un profilo di serie temporali o di inferenze, il monitor analizza solo i dati dei 30 giorni precedenti alla sua creazione. Dopo aver creato il monitor, tutti i nuovi dati vengono elaborati.
  • I monitor definiti su viste materializzate e tabelle in streaming non supportano l'elaborazione incrementale.

Suggerimento

Per i profili TimeSeries e Inference è consigliabile abilitare il feed di dati (CDF) delle modifiche nella tabella. Quando il CDF è abilitato, invece di rielaborare l'intera tabella a ogni aggiornamento, vengono elaborati solo i dati recentemente aggiunti. In questo modo l'esecuzione risulta più efficiente e riduce i costi man mano che si ridimensiona il monitoraggio in molte tabelle.

Profilo TimeSeries

Un profilo TimeSeries confronta le distribuzioni dei dati tra le finestre temporali. Per un profilo TimeSeries, è necessario specificare quanto segue:

  • Colonne timestamp (timestamp_col). Il tipo di dati della colonna timestamp deve essere TIMESTAMP oppure un tipo che può essere convertito in timestamp utilizzando la to_timestamp funzione PySpark funzione.
  • Set di granularities su cui calcolare le metriche. Le granularità disponibili sono "5 minuti", "30 minuti", "1 ora", "1 giorno", "1 settimana", "2 settimane", "3 settimane", "4 settimane", "1 mese", "1 anno".
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"])
)

Profilo InferenceLog

Un profilo InferenceLog è simile a un profilo TimeSeries, ma include anche metriche di qualità del modello. Per un profilo InferenceLog sono necessari i seguenti parametri:

Parametro Descrizione
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION oppure MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col Colonna contenente i valori stimati del modello.
timestamp_col Colonna contenente il timestamp della richiesta di inferenza.
model_id_col Colonna contenente l'ID del modello usato per la stima.
granularities Determina come partizionare i dati nelle finestre nel tempo. Valori possibili: "5 minuti", "30 minuti", "1 ora", "1 giorno", "1 settimana", "2 settimane", "3 settimane", "4 settimane", "1 mese", "1 anno".

C’è anche un parametro facoltativo:

Parametro facoltativo Descrizione
label_col Colonna contenente la verità di base per le stime del modello. 
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
  )
)

Per i profili InferenceLog, le sezioni vengono create automaticamente in base ai valori distinti di model_id_col.

Profilo Snapshot

A differenza di TimeSeries, un profilo Snapshot monitora il modo in cui il contenuto completo della tabella cambia nel tempo. Le metriche vengono calcolate su tutti i dati nella tabella e monitorano lo stato della tabella ogni volta che il monitor viene aggiornato.

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

Aggiornare e visualizzare i risultati del monitor

Per aggiornare le tabelle delle metriche, usare run_refresh. Ad esempio:

from databricks.sdk import WorkspaceClient

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

Quando si chiama run_refresh da un notebook, le tabelle delle metriche del monitor vengono create o aggiornate. Questo calcolo viene eseguito nell’elaboraizone serverless, non nel cluster a cui è collegato il notebook. È possibile continuare a eseguire i comandi nel notebook mentre vengono aggiornate le statistiche del monitor.

Per informazioni sulle statistiche archiviate nelle tabelle delle metriche, consultare le tabelle delle metriche del monitor. Le tabelle delle metriche sono tabelle dello Unity Catalog. È possibile interrogare le tabelle nei notebook o in nell’esplora query SQL e visualizzarli nel Catalog Explorer.

Per visualizzare la cronologia di tutti gli aggiornamenti associati a un monitor, usare list_refreshes.

from databricks.sdk import WorkspaceClient

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

Per ottenere lo stato di un'esecuzione specifica che è stata accodata, in esecuzione o completata, usare 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
)

Per annullare un aggiornamento in coda o in esecuzione, usare 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
)

Visualizzare le impostazioni di monitor

È possibile esaminare le impostazioni di monitor usando l'API get_monitor.

from databricks.sdk import WorkspaceClient

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

Programmazione

Per configurare un monitoraggio per l'esecuzione su base pianificata, usare il parametro schedule di create_monitor:

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

Per altre informazioni, consultare le espressioni cron.

Notifications

Per configurare le notifiche per un monitor, usare il parametro notifications di create_monitor:

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

Per ogni tipo di evento, (ad esempio, "on_failure"), è supportato un massimo di 5 indirizzi di posta elettronica.

Controllare l'accesso alle tabelle delle metriche

Le tabelle delle metriche e il dashboard creati da un monitor sono di proprietà dell'utente che ha creato il monitoraggio. È possibile usare i privilegi dello Unity Catalog per controllare l'accesso alle tabelle delle metriche. Per condividere i dashboard all'interno di un'area di lavoro, usare il pulsante Condividi in alto a destra del dashboard.

Eliminare un monitor

Per eliminare un monitor:

from databricks.sdk import WorkspaceClient

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

Questo comando non elimina le tabelle del profilo e il dashboard creato dal monitor. È necessario eliminare tali asset in un passaggio separato oppure salvarli in una posizione diversa.

Notebook di esempio

I seguenti notebook di esempio illustrano come creare un monitor, aggiornarlo ed esaminare le tabelle delle metriche create da esso.

Esempio di notebook: Profilo serie temporale

Questo notebook illustra come creare un monitor di tipo TimeSeries.

Notebook di esempio TimeSeries Lakehouse Monitor

Ottenere il notebook

Esempio di notebook: profilo di inferenza (regressione)

Questo notebook illustra come creare un monitor di tipo InferenceLog per un problema di regressione.

Notebook di esempio di regressione di Inference Lakehouse Monitor

Ottenere il notebook

Esempio di notebook: profilo di inferenza (classificazione)

Questo notebook illustra come creare un monitor di tipo InferenceLog per un problema di classificazione.

Notebook di esempio di classificazione di Inference Lakehouse Monitor

Ottenere il notebook

Esempio di notebook: Profilo snapshot

Questo notebook illustra come creare un monitor di tipo Snapshot.

Notebook di esempio di Snapshot Lakehouse Monitor

Ottenere il notebook