Compartilhar via

Criar um monitor usando a API

  • Artigo

Esta página descreve como criar um monitor no Databricks usando o SDK do Databricks, além de todos os parâmetros usados ​​em chamadas de API. Você também pode criar e gerenciar monitores usando a API REST. Para obter informações de referência, confira a Referência do SDK de monitoramento de lakehouse e a Referência da API REST.

Você pode criar um monitor em qualquer tabela Delta gerenciada ou externa registrada no Catálogo do Unity. Somente um único monitor pode ser criado em um metastore do Catálogo do Unity para qualquer tabela.

Requisitos

A API de monitoramento de lakehouse está integrada ao databricks-sdk versão 0.28.0 e a versões posteriores. Para usar a versão mais recente da API, inclua o seguinte comando no início do notebook para instalar o cliente Python:

%pip install "databricks-sdk>=0.28.0"

Para autenticar-se e usar o SDK do Databricks no ambiente, confira Autenticação.

Tipos de perfil

Ao criar um monitor, você seleciona um dos seguintes tipos de perfil: TimeSeries, InferenceLog ou Snapshot. Esta seção descreve brevemente cada opção. Para obter detalhes, confira a referência da API ou a referência da API REST.

Observação

  • Quando você cria pela primeira vez um perfil de série temporal ou inferência, o monitor analisa apenas os dados dos 30 dias anteriores à sua criação. Depois que o monitor é criado, todos os novos dados são processados.
  • Monitores definidos em exibições materializadas e tabelas de streaming não dão suporte ao processamento incremental.

Dica

Para os perfis TimeSeries e Inference, é prática recomendada habilitar o feed de dados de alteração (CDF) em sua tabela. Quando o CDF está habilitado, apenas os dados recém-acrescentados são processados, em vez de reprocessar a tabela inteira a cada atualização. Isso torna a execução mais eficiente e reduz os custos à medida que você dimensiona o monitoramento em várias tabelas.

Perfil de TimeSeries

Um perfil de TimeSeries compara distribuições de dados entre janelas de tempo. Para um perfil de TimeSeries, você deve fornecer o seguinte:

  • A coluna de carimbo de data/hora (timestamp_col). O tipo de dados da coluna de carimbo de data/hora deve ser TIMESTAMP ou um tipo que possa ser convertido em carimbos de data/hora usando a to_timestamp função PySpark.
  • O conjunto de granularities sobre o qual calcular métricas. As granularidades disponíveis são "5 minutos", "30 minutos", "1 hora", "1 dia", "1 semana", "2 semanas", "3 semanas", "4 semanas", "1 mês", "1 ano".
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 de InferenceLog

Um perfil de InferenceLog é semelhante a um perfil de TimeSeries, mas também inclui métricas de qualidade do modelo. Para um perfil de InferenceLog, s seguintes parâmetros são necessários:

Parâmetro Descrição
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION ou MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col Coluna que contém os valores previstos do modelo.
timestamp_col Coluna que contém o carimbo de data/hora da solicitação de inferência.
model_id_col Coluna que contém a ID do modelo usado para previsão.
granularities Determina como particionar os dados em janelas ao longo do tempo. Valores possíveis: "5 minutos", "30 minutos", "1 hora", "1 dia", "1 semana", "2 semanas", "3 semanas", "4 semanas", "1 mês", "1 ano".

Também há um parâmetro opcional:

Parâmetro opcional Descrição
label_col Coluna que contém a verdade básica para previsões de 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
  )
)

Para perfis InferenceLog, as fatias são criadas automaticamente com base nos valores distintos de model_id_col.

Perfil de Snapshot

Em contraste com o de TimeSeries, um perfil de Snapshot monitora como o conteúdo completo da tabela é alterado ao longo do tempo. As métricas são calculadas sobre todos os dados na tabela e monitoram o estado da tabela sempre que o monitoramento é atualizado.

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

Atualizar e exibir os resultados do monitor

Para atualizar tabelas de métricas, use run_refresh. Por exemplo:

from databricks.sdk import WorkspaceClient

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

Quando você chama run_refresh de um notebook, as tabelas de métricas do monitor são criadas ou atualizadas. Esse cálculo é executado na computação sem servidor, não no cluster ao qual o notebook está anexado. Você pode continuar a executar comandos no notebook enquanto as estatísticas do monitor são atualizadas.

Para obter informações sobre as estatísticas armazenadas em tabelas de métricas, consulte Monitorar tabelas de métricas Tabelas de métricas são tabelas do Catálogo do Unity. Você pode consultá-las em notebooks ou no gerenciador de consultas SQL e exibi-las no Catalog Explorer.

Para exibir o histórico de todas as atualizações associadas a um monitor, use list_refreshes.

from databricks.sdk import WorkspaceClient

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

Para obter o status de uma execução específica que foi enfileirada, em execução ou concluída, 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 uma atualização enfileirada ou em execução, 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
)

Exibir configurações do monitor

Você pode examinar as configurações do monitor usando a API get_monitor.

from databricks.sdk import WorkspaceClient

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

Agenda

Para configurar um monitor para ser executado de acordo com um agendamento, use o schedule parâmetro 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 expressões cron para obter mais informações.

Notificações

Para configurar notificações para um monitor, use o parâmetro notifications 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"]
        )
    )
)

Há suporte para no máximo 5 endereços de email por tipo de evento (por exemplo, "on_failure").

Controlar o acesso às tabelas de métricas

As tabelas de métricas e o painel criados por um monitor pertencem ao usuário que criou o monitor. Você pode usar privilégios do Catálogo do Unity para controlar o acesso a tabelas de métricas. Para compartilhar painéis em um workspace, clique no botão Compartilhar no lado superior direito do painel.

Excluir um monitor

Para excluir um monitor:

from databricks.sdk import WorkspaceClient

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

Esse comando não exclui as tabelas de perfil e os painéis criados pelo monitor. Você deve excluir esses ativos em uma etapa separada ou salvá-los em um local diferente.

Blocos de anotações de exemplo

Os notebooks de exemplo a seguir ilustram como criar um monitor, atualizá-lo e examinar as tabelas de métricas que ele cria.

Exemplo de notebook: perfil de série temporal

Este notebook ilustra como criar um tipo TimeSeries de monitor.

Notebook de exemplo do Monitor Lakehouse de Série Temporal

Obter notebook

Exemplo de notebook: perfil de inferência (regressão)

Este notebook ilustra como criar um monitor do tipo InferenceLog para um problema de regressão.

Notebook de exemplo de regressão do Monitor Lakehouse de Inferência

Obter notebook

Exemplo de notebook: perfil de inferência (classificação)

Este notebook ilustra como criar um monitor do tipo InferenceLog para um problema de regressão.

Notebook de exemplo de classificação do Monitor Lakehouse de inferência

Obter notebook

Exemplo de notebook: perfil de instantâneo

Este notebook ilustra como criar um monitor do tipo Snapshot.

Notebook de exemplo do Monitor Lakehouse de Instantâneo

Obter notebook