Share via

Criar um monitor usando a API

  • Artigo

Importante

Esta funcionalidade está em Pré-visualização Pública.

Esta página descreve como criar um monitor no Databricks usando a API Python e descreve todos os parâmetros usados na chamada de API. Você também pode criar e gerenciar monitores usando a API REST. Para obter informações de referência, consulte a referência da API Python de monitoramento do Lakehouse e a referência da API REST.

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

Requisitos

A Lakehouse Monitoring API está integrada ao Databricks Runtime 14.3 LTS e superior. Para usar a versão mais recente da API ou para usá-la com versões anteriores do Databricks Runtime, use o seguinte comando no início do seu bloco de anotações para instalar o cliente Python:

%pip install "https://ml-team-public-read.s3.amazonaws.com/wheels/data-monitoring/a4050ef7-b183-47a1-a145-e614628e3146/databricks_lakehouse_monitoring-0.4.14-py3-none-any.whl"

Parâmetro de tipo de perfil

O profile_type parâmetro determina a classe de métricas que o monitoramento calcula para a tabela. Existem três tipos: TimeSeries, InferenceLog e Snapshot. Esta seção descreve brevemente os parâmetros. Para obter detalhes, consulte a referência da API ou a referência da API REST.

Nota

  • Quando você cria pela primeira vez uma série temporal ou um perfil de 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.
  • Os monitores definidos em visualizações materializadas e tabelas de streaming não suportam processamento incremental.

TimeSeries perfil

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

  • Uma coluna de carimbo de data/hora (timestamp_col). O tipo de dados da coluna de carimbo de data/hora deve ser um TIMESTAMP ou um tipo que possa ser convertido em carimbos de data/hora usando a to_timestampfunção PySpark.
  • O conjunto sobre granularities o qual calcular métricas. As granularidades disponíveis são "5 minutos", "30 minutos", "1 hora", "1 dia", "n semana(s)", "1 mês", "1 ano".
from databricks import lakehouse_monitoring as lm

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.TimeSeries(
        timestamp_col="ts",
        granularities=["30 minutes"]
    ),
    output_schema_name=f"{catalog}.{schema}"
)

InferenceLog perfil

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

Parâmetro Description
problem_type "classificação" ou "regressão".
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 no Windows ao longo do tempo. Valores possíveis: "5 minutos", "30 minutos", "1 hora", "1 dia", "n semana(s)", "1 mês", "1 ano".

Há também um parâmetro opcional:

Parâmetro opcional Description
label_col Coluna que contém a verdade fundamental para previsões de modelos. 
from databricks import lakehouse_monitoring as lm

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.InferenceLog(
        problem_type="classification",
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
    ),
    output_schema_name=f"{catalog}.{schema}"
)

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

Snapshot perfil

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

from databricks import lakehouse_monitoring as lm

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.Snapshot(),
    output_schema_name=f"{catalog}.{schema}"
)

Atualizar e visualizar os resultados do monitor

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

from databricks import lakehouse_monitoring as lm

lm.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Quando você chama run_refresh de um bloco de anotações, as tabelas métricas do monitor são criadas ou atualizadas. Esse cálculo é executado em computação sem servidor, não no cluster ao qual o bloco de anotações está conectado. Pode continuar a executar comandos no bloco de notas enquanto as estatísticas do monitor são atualizadas.

Para obter informações sobre as estatísticas armazenadas em tabelas métricas, consulte Monitorar tabelas métricas As tabelas métricas são tabelas do Catálogo Unity. Você pode consultá-los em blocos de anotações ou no explorador de consultas SQL e exibi-los no Gerenciador de Catálogos.

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

from databricks import lakehouse_monitoring as lm

lm.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Para obter o status de uma execução específica que foi enfileirada, executada ou concluída, use get_refresh.

from databricks import lakehouse_monitoring as lm

run_info = lm.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

lm.get_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id = run_info.refresh_id
)

Para cancelar uma atualização em fila ou em execução, use cancel_refresh.

from databricks import lakehouse_monitoring as lm

run_info = lm.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

lm.cancel_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id=run_info.refresh_id
)

Ver definições do monitor

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

from databricks import lakehouse_monitoring as lm

lm.get_monitor(table_name=TABLE_NAME)

Agenda

Para configurar um monitor para ser executado de forma agendada, use o schedule parâmetro de create_monitor:

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.TimeSeries(
        timestamp_col="ts",
        granularities=["30 minutes"]
    ),
    schedule=lm.MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    ),
    output_schema_name=f"{catalog}.{schema}"
)

Consulte expressões cron para obter mais informações.

Notifications

Para configurar notificações para um monitor, use o notifications parâmetro de create_monitor:

lm.create_monitor(
    table_name=f"{catalog}.{schema}.{table_name}",
    profile_type=lm.TimeSeries(
        timestamp_col="ts",
        granularities=["30 minutes"]
    ),
    notifications=lm.Notifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=lm.Destination(
            email_addresses=["your_email@domain.com"]
        )
    )
    output_schema_name=f"{catalog}.{schema}"
)

É suportado um máximo de 5 endereços de e-mail por tipo de evento (por exemplo, "on_failure").

Controlar o acesso a tabelas métricas

As tabelas métricas e o painel criados por um monitor são de propriedade do usuário que criou o monitor. Você pode usar os privilégios do Catálogo Unity para controlar o acesso a tabelas métricas. Para compartilhar painéis em um espaço de trabalho, use o botão Compartilhar no canto superior direito do painel.

Excluir um monitor

Para excluir um monitor:

lm.delete_monitor(table_name=TABLE_NAME)

Este comando não exclui as tabelas de perfil e o painel criado pelo monitor. Você deve excluir esses ativos em uma etapa separada ou pode salvá-los em um local diferente.

Blocos de notas de exemplo

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

Exemplo de bloco de notas: Perfil de série temporal

Este bloco de anotações ilustra como criar um TimeSeries monitor de tipo.

Notebook de exemplo do TimeSeries Lakehouse Monitor

Obter o bloco de notas

Exemplo de bloco de notas: Perfil de inferência (regressão)

Este bloco de anotações ilustra como criar um InferenceLog monitor de tipo para um problema de regressão.

Bloco de anotações de exemplo de regressão do Inference Lakehouse Monitor

Obter o bloco de notas

Exemplo de bloco de notas: Perfil de inferência (classificação)

Este bloco de anotações ilustra como criar um monitor de InferenceLog tipo para um problema de classificação.

Caderno de exemplo de classificação do Inference Lakehouse Monitor

Obter o bloco de notas

Exemplo de bloco de notas: Perfil de instantâneo

Este bloco de anotações ilustra como criar um Snapshot monitor de tipo.

Bloco de anotações de exemplo do Snapshot Lakehouse Monitor

Obter o bloco de notas