Compartir a través de

Creación de un monitor mediante la API

  • Artículo

En esta página se describe cómo crear un monitor en Databricks mediante el SDK de Databricks y se describen todos los parámetros usados en las llamadas API. También puede crear y administrar monitores mediante la API de REST. Para obtener información de referencia, vea la referencia del SDK de supervisión de Lakehouse y la referencia de la API de REST.

Es posible crear un monitor en cualquier tabla Delta administrada o externa registrada en el catálogo de Unity. Solo se puede crear un monitor en un metastore del catálogo de Unity para cualquier tabla.

Requisitos

La API de supervisión de Lakehouse está integrada en databricks-sdk 0.28.0 y versiones posteriores. Para usar la versión más reciente de la API, use el siguiente comando al principio del cuaderno para instalar el cliente de Python:

%pip install "databricks-sdk>=0.28.0"

Para autenticarse para usar el SDK de Databricks en su entorno, consulte Autenticación.

Tipos de perfil

Al crear un monitor, seleccione uno de los siguientes tipos de perfil: TimeSeries, InferenceLog o Snapshot. En esta sección se describe brevemente cada opción. Para más información, consulte la Referencia de API o la Referencia de la API de REST.

Nota:

  • Cuando se crea por primera vez una serie temporal o un perfil de inferencia, el monitor solo analiza los datos de los 30 días anteriores a su creación. Una vez creado el monitor, se procesan todos los datos nuevos.
  • Los monitores definidos en vistas materializadas y tablas de streaming no admiten el procesamiento incremental.

Sugerencia

En el caso de los perfiles TimeSeries y Inference, se recomienda habilitar la fuente de distribución de datos modificados (CDF) en la tabla. Cuando CDF está habilitado, solo se procesan los datos anexados recientemente, en lugar de volver a procesar toda la tabla en cada actualización. Esto hace que la ejecución sea más eficaz y reduzca los costos a medida que se escala la supervisión en muchas tablas.

Perfil TimeSeries

Un perfil TimeSeries compara las distribuciones de datos entre ventanas de tiempo. Para un perfil TimeSeries, se necesita proporcionar lo siguiente:

  • Columna de marca de tiempo (timestamp_col). El tipo de datos de columna Marca de tiempo debe ser TIMESTAMP o un tipo que se pueda convertir en marcas de tiempo mediante la to_timestampfunción PySpark.
  • Conjunto de granularities sobre el que se calcularán las métricas. Las granularidades disponibles son "5 minutos", "30 minutos", "1 hora", "1 día", "1 semana", "2 semanas", "3 semanas", "4 semanas", "1 mes", "1 año".
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"])
)

Perfil InferenceLog

Un perfil InferenceLog es similar a un perfil TimeSeries, pero también incluye métricas de calidad del modelo. Para un InferenceLog perfil, se necesitan los parámetros siguientes:

Parámetro Descripción
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION o MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col Columna que contiene los valores predichos del modelo.
timestamp_col Columna que contiene la marca de tiempo de la solicitud de inferencia.
model_id_col Columna que contiene el identificador del modelo usado para la predicción.
granularities Determina cómo crear particiones de los datos en ventanas a lo largo del tiempo. Valores posibles: "5 minutos", "30 minutos", "1 hora", "1 día", "1 semana", "2 semanas", "3 semanas", "4 semanas", "1 mes", "1 año".

También hay un parámetro opcional:

Parámetro opcional Descripción
label_col Columna que contiene la verdad básica para las predicciones del modelo. 
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
  )
)

En el caso de los perfiles de InferenceLog, los segmentos se crean automáticamente en función de los valores distintos de model_id_col.

Perfil Snapshot

A diferencia de TimeSeries, un perfil Snapshot supervisa cómo cambia todo el contenido de las tablas a lo largo del tiempo. Las métricas se calculan sobre todos los datos de la tabla y supervisan el estado de la misma cada vez que se actualice el monitor.

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

Actualizar y ver los resultados de la supervisión

Para actualizar las tablas de métricas, use run_refresh. Por ejemplo:

from databricks.sdk import WorkspaceClient

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

Al llamar a run_refresh desde un cuaderno, las tablas de métricas de supervisión se crean o actualizan. Este cálculo se ejecuta en un proceso sin servidor, no en el clúster al que está asociado el cuaderno. Puede seguir ejecutando comandos en el cuaderno mientras se actualizan las estadísticas de supervisión.

Para obtener información sobre las estadísticas almacenadas en tablas de métricas, consulte Supervisión de tablas de métricas Las tablas de métricas son tablas del catálogo de Unity. Puede consultarlas en cuadernos o en el explorador de consultas SQL, y verlos en el Explorador de catálogos.

Para mostrar el historial de todas las actualizaciones asociadas a una supervisión, use list_refreshes.

from databricks.sdk import WorkspaceClient

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

Para obtener el estado de una ejecución específica que se haya puesto en cola, en ejecución o finalizado, use 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
)

Para cancelar una actualización en cola o en ejecución, use 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
)

Visualización de la configuración de la supervisión

Puede revisar la configuración de supervisión mediante la API get_monitor.

from databricks.sdk import WorkspaceClient

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

Programación

Para configurar una supervisión que se ejecute de forma programada, use el parámetro schedule de 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",
    )
)

Consulte expresiones cron para obtener más información.

Notificaciones

Para configurar notificaciones para un monitor, use el notifications parámetro de 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"]
        )
    )
)

Se admite un máximo de 5 direcciones de correo electrónico por tipo de evento (por ejemplo, “on_failure”).

Control del acceso a las tablas de métricas

Las tablas de métricas y el panel creados por un monitor son propiedad del usuario que ha creado el monitor. Puede usar privilegios de Unity Catalog para controlar el acceso a las tablas de métricas. Para compartir paneles dentro de un área de trabajo, use el botón Compartir situado en la esquina superior derecha del panel.

Eliminación de un monitor

Para eliminar un monitor:

from databricks.sdk import WorkspaceClient

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

Este comando no elimina las tablas de perfil ni el panel creado por la supervisión. Debe eliminar esos recursos en un paso independiente o guardarlos en otra ubicación.

Cuadernos de ejemplo

En los cuadernos de ejemplo siguientes se muestra cómo crear una supervisión, actualizarla y examinar las tablas de métricas que crea.

Ejemplo de cuaderno: perfil de serie temporal

En este cuaderno se muestra cómo crear una supervisión de tipo TimeSeries.

Cuaderno de ejemplo de supervisión de TimeSeries Lakehouse

Obtener el cuaderno

Ejemplo de cuaderno: perfil de inferencia (regresión)

En este cuaderno se muestra cómo crear una supervisión de tipo InferenceLog para un problema de regresión.

Cuaderno de ejemplo de regresión de supervisión de Inference Lakehouse

Obtener el cuaderno

Ejemplo de cuaderno: perfil de inferencia (clasificación)

En este cuaderno se muestra cómo crear una supervisión de tipo InferenceLog para un problema de clasificación.

Cuaderno de ejemplo de clasificación de supervisión de Inference Lakehouse

Obtener el cuaderno

Ejemplo de cuaderno: perfil de instantánea

En este cuaderno se muestra cómo crear una supervisión de tipo Snapshot.

Cuaderno de ejemplo de la supervisión de Snapshot Lakehouse

Obtener el cuaderno