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 monitoraggi usando l'API REST. Per informazioni di riferimento, vedere le informazioni di riferimento sull'SDK di monitoraggio di Lakehouse e le informazioni di riferimento sull'API REST.

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

Requisiti

L'API di monitoraggio lakehouse è integrata in databricks-sdk 0.28.0 e versioni successive. Per usare la versione più recente dell'API, usare il comando seguente 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, vedere Autenticazione.

Tipi di profilo

Quando si crea un monitoraggio, si seleziona uno dei tipi di profilo seguenti: TimeSeries, InferenceLog o Snapshot. Questa sezione descrive brevemente ogni opzione. Per informazioni dettagliate, vedere le informazioni di riferimento sull'API o le informazioni di riferimento sull'API REST.

Nota

  • Quando si crea una serie temporale o un profilo di inferenza per la prima volta, il monitoraggio analizza solo i dati dei 30 giorni precedenti alla creazione. Dopo aver creato il monitoraggio, tutti i nuovi dati vengono elaborati.
  • I monitoraggi definiti nelle viste materializzate e nelle tabelle di streaming non supportano l'elaborazione incrementale.

Suggerimento

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

TimeSeries profilo

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

  • Colonna timestamp (timestamp_col). Il tipo di dati della colonna timestamp deve essere TIMESTAMP o un tipo che può essere convertito in timestamp usando la to_timestamp funzione PySpark.
  • Set di granularities su cui calcolare le metriche. Le granularità disponibili sono "5 minuti", "30 minuti", "1 ora", "1 giorno", "n 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"])
)

InferenceLog profilo

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

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", "n settimana/i", "1 mese", "1 anno".

Esiste anche un parametro facoltativo:

Parametro facoltativo Descrizione
label_col Colonna contenente la verità del terreno 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.

Snapshot profilo

A differenza di TimeSeries, un Snapshot profilo 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 monitoraggio 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 monitoraggio

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 di monitoraggio vengono create o aggiornate. Questo calcolo viene eseguito nel calcolo serverless, non nel cluster a cui è collegato il notebook. È possibile continuare a eseguire i comandi nel notebook mentre vengono aggiornate le statistiche di monitoraggio.

Per informazioni sulle statistiche archiviate nelle tabelle delle metriche, vedere Monitorare le tabelle delle metriche Le tabelle delle metriche sono tabelle del catalogo Unity. È possibile eseguire query nei notebook o in Esplora query SQL e visualizzarli in Esplora cataloghi.

Per visualizzare la cronologia di tutti gli aggiornamenti associati a un monitoraggio, 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 monitoraggio

È possibile esaminare le impostazioni di monitoraggio 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 schedule parametro 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, vedere Espressioni cron.

Notifications

Per configurare le notifiche per un monitoraggio, usare il notifications parametro 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"]
        )
    )
)

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

Controllare l'accesso alle tabelle delle metriche

Le tabelle delle metriche e il dashboard creati da un monitoraggio sono di proprietà dell'utente che ha creato il monitoraggio. È possibile usare i privilegi del catalogo Unity 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 monitoraggio

Per eliminare un monitoraggio:

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 monitoraggio. È necessario eliminare tali asset in un passaggio separato oppure salvarli in una posizione diversa.

Notebook di esempio

I notebook di esempio seguenti illustrano come creare un monitoraggio, aggiornare il monitoraggio ed esaminare le tabelle delle metriche create.

Esempio di notebook: Profilo serie temporale

Questo notebook illustra come creare un TimeSeries monitoraggio dei tipi.

Notebook di esempio timeSeries Lakehouse Monitor

Ottenere il notebook

Esempio di notebook: profilo di inferenza (regressione)

Questo notebook illustra come creare un InferenceLog monitoraggio dei tipi 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 InferenceLog monitoraggio dei tipi 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 Snapshot monitoraggio dei tipi.

Notebook di esempio di Snapshot Lakehouse Monitor

Ottenere il notebook