Criar um monitor usando a API

Visualização

Este recurso está em visualização pública.

Esta página descreve como criar um monitor no Databricks usando a API do Python e descreve todos os parâmetros usados na chamada da API. O senhor 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 da Lakehouse e a referência da API REST.

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

Requisitos

O Lakehouse Monitoring API está incorporado ao Databricks Runtime 14.3 LTS e acima. Para usar a versão mais recente do API, ou para usá-lo com versões anteriores do Databricks Runtime, use o seguinte comando no início do seu Notebook 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 parâmetro profile_type determina a classe de métricas que o monitoramento calcula para a tabela. Há 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.

Observação

  • Quando o senhor cria uma série temporal ou um perfil de inferência, o monitor analisa um máximo de 30 dias a partir do momento em que o monitor é criado. Os dados com mais de 30 dias não estão incluídos.

  • Os monitores definidos na exibição materializada e nas tabelas de transmissão não são compatíveis com o processamento incremental.

TimeSeries perfil

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

  • Uma coluna de carimbo de data/hora (timestamp_col). O tipo de dados da coluna carimbo de data/hora deve ser TIMESTAMP ou um tipo que possa ser convertido em carimbos de data/hora usando a função to_timestamp 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”, “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 perfil InferenceLog é semelhante a um perfil TimeSeries , mas também inclui métricas de qualidade de modelo. Para um perfil InferenceLog , os seguintes parâmetros são necessários:

Parâmetro

Descrição

problem_type

“classificação” ou “regressão”.

prediction_col

Coluna contendo os valores previstos do modelo.

timestamp_col

Coluna contendo o timestamp da solicitação de inferência.

model_id_col

Coluna contendo o 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”, “n semana(s)”, “1 mês”, “1 ano”.

Há também um parâmetro opcional:

Parâmetro opcional

Descrição

label_col

Coluna contendo a verdade básica para as previsões do modelo.

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 TimeSeries, um perfil Snapshot 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}"
)

Atualize e visualize os resultados do monitor

Para refresh as 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 Notebook, as tabelas de métricas do monitor são criadas ou atualizadas. Esta execução de cálculo na compute serverless, não nos clusters aos quais o Notebook está conectado. Você pode continuar executando 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 Unity Catalog. Você pode query -los no Notebook ou no SQL query Explorer e view -los no Catalog Explorer.

Para exibir o histórico de todas refresh 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, em execução 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 um refresh que esteja na 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
)

Exibir configuraçõ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)

programar

Para configurar um monitor para execução programada, use o parâmetro schedule 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}"
)

Veja expressões cron para mais informações.

Notificações

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

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

Controle 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 os privilégios do Unity Catalog para controlar o acesso às tabelas de métricas. Para compartilhar painéis em um workspace, 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 perfis e o painel criado pelo monitor. Você deve excluir esses ativos em um passo separado ou salvá-los em um local diferente.

Notebook de Exemplo

O Notebook de exemplo a seguir ilustra como criar um monitor, refresh -lo e examinar as tabelas de métricas que ele cria.

Exemplo Notebook : perfil de série temporal

Este Notebook ilustra como criar um monitor do tipo TimeSeries.

Notebookde exemplo do monitor TimeSeries Lakehouse

Abra o bloco de anotações em outra guia

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

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

Exemplo de regressão do Inference Lakehouse Monitor Notebook

Abra o bloco de anotações em outra guia

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

Este Notebook ilustra como criar um monitor do tipo InferenceLog para um problema de classificação.

Exemplo de classificação do Inference Lakehouse Monitor Notebook

Abra o bloco de anotações em outra guia

Exemplo Notebook : perfil Snapshot

Este Notebook ilustra como criar um monitor do tipo Snapshot.

Notebook de exemplo do Snapshot Lakehouse Monitor

Abra o bloco de anotações em outra guia