Criar um monitor usando a API

Esta página descreve como criar um monitor no Databricks usando o SDK do Databricks e descreve todos os parâmetros usados nas chamadas de 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 do monitoramento da Lakehouse SDK e a referência doREST API.

O senhor pode criar um monitor em qualquer tabela gerenciar ou externa Delta registrada em Unity Catalog. Somente um único monitor pode ser criado em um metastore do Unity Catalog para qualquer tabela.

Requisitos

O monitoramento do Lakehouse API está incorporado no databricks-sdk 0.28.0 e acima. Para usar a versão mais recente do API, use o seguinte comando no início do Notebook para instalar o cliente Python:

Python
%pip install "databricks-sdk>=0.28.0"

Para se autenticar para usar o SDK da Databricks em seu ambiente, consulte Autenticação.

Tipos de perfil

Ao criar um monitor, o senhor seleciona um dos seguintes tipos de perfil: TimeSeries, InferenceLog ou Snapshot. Esta seção descreve brevemente cada opção. 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 somente os dados dos 30 dias anteriores à sua criação. Depois que o monitor é criado, todos os novos dados são processados.
Os monitores definidos na exibição materializada e nas tabelas de transmissão não são compatíveis com o processamento incremental.

dica

Para perfis TimeSeries e Inference, é uma prática recomendada ativar o feed de dados de alteração (CDF) em sua tabela. Quando o CDF está ativado, somente os dados recém-anexados são processados, em vez de reprocessar a tabela inteira a cada refresh. Isso torna a execução mais eficiente e reduz os custos, pois o senhor escala o monitoramento em várias tabelas.

Perfil`TimeSeries`

Um perfil TimeSeries compara as 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 timestamp deve ser TIMESTAMP ou um tipo que possa ser convertido em timestamps usando a to_timestamp função do PySpark.
O conjunto de granularities sobre o qual calcular as 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”.

Python
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`

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`	`MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION` ou `MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION`
`prediction_col`	Coluna contendo os valores previstos do modelo.
`timestamp_col`	Coluna contendo a data e hora da solicitação de inferência.
`model_id_col`	Coluna contendo o id do modelo usado para predição.
`granularities`	Determina como particionar os dados no Windows 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 contendo a verdade fundamental para as previsões do modelo.

Python
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`Snapshot`

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

Python
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 view monitorar os resultados

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

Python
from databricks.sdk import WorkspaceClient

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

Quando o senhor chama run_refresh de um Notebook, as tabelas métricas do monitor são criadas ou atualizadas. Esse cálculo é executado em serverless compute, e não no cluster ao qual o Notebook está vinculado. O senhor pode continuar a executar o comando no Notebook enquanto as estatísticas do monitor são atualizadas.

Para obter informações sobre as estatísticas que são armazenadas nas tabelas métricas, consulte Monitorar tabelas mé tricas As tabelas métricas são Unity Catalog tabelas. O senhor pode consultá-los no Notebook ou no explorador de consultas SQL e view no Catalog Explorer.

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

Python
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 esteja na fila, em execução ou concluída, use get_refresh.

Python
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 um refresh que esteja na fila ou em execução, use cancel_refresh.

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

visualizar as configurações do monitor

O senhor pode revisar as configurações do monitor usando a API get_monitor.

Python
from databricks.sdk import WorkspaceClient

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

programar

Para configurar um monitor para execução em uma base programada, use o parâmetro schedule de create_monitor:

Python
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:

Python
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 um máximo de 5 endereços email por tipo de evento (por exemplo, "on_failure").

Controle o acesso às tabelas métricas

As tabelas de métricas e o painel criados por um monitor são de propriedade do usuário que criou o monitor. O senhor pode usar os privilégios do Unity Catalog para controlar o acesso às tabelas métricas. Para compartilhar painéis em um workspace, use o botão Share (Compartilhar ) no canto superior direito do painel.

Excluir um monitor

Para excluir um monitor:

Python
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 o painel de controle criados pelo monitor. O senhor deve excluir esses ativos em uma etapa separada ou pode salvá-los em um local diferente.

Exemplo de notebook

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

Notebook exemplo: Perfil de série temporal

Este Notebook ilustra como criar um monitor do tipo TimeSeries.

Exemplo do TimeSeries lakehouse Monitor Notebook

Open notebook in new tab

Notebook exemplo: Perfil de inferência (regressão)

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

Inferência lakehouse Monitor regressão exemplo Notebook

Open notebook in new tab

Notebook exemplo: Perfil de inferência (classificação)

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

Inferência lakehouse Monitor classification example Notebook

Open notebook in new tab

Notebook Exemplo: profile Snapshot

Este Notebook ilustra como criar um monitor do tipo Snapshot.

Snapshot lakehouse Monitor exemplo Notebook

Open notebook in new tab

Requisitos​

Tipos de perfil​

PerfilTimeSeries​

PerfilInferenceLog​

PerfilSnapshot​

Atualizar e view monitorar os resultados​

visualizar as configurações do monitor​

programar​

Notificações​

Controle o acesso às tabelas métricas​

Excluir um monitor​

Exemplo de notebook​

Notebook exemplo: Perfil de série temporal​

Exemplo do TimeSeries lakehouse Monitor Notebook

Notebook exemplo: Perfil de inferência (regressão)​

Inferência lakehouse Monitor regressão exemplo Notebook

Notebook exemplo: Perfil de inferência (classificação)​

Inferência lakehouse Monitor classification example Notebook

Notebook Exemplo: profile Snapshot​

Snapshot lakehouse Monitor exemplo Notebook

Requisitos

Tipos de perfil

Perfil`TimeSeries`

Perfil`InferenceLog`

Perfil`Snapshot`

Atualizar e view monitorar os resultados

visualizar as configurações do monitor

programar

Notificações

Controle o acesso às tabelas métricas

Excluir um monitor

Exemplo de notebook

Notebook exemplo: Perfil de série temporal

Notebook exemplo: Perfil de inferência (regressão)

Notebook exemplo: Perfil de inferência (classificação)

Notebook Exemplo: profile Snapshot