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êncialakehouse monitoramento SDK e a referênciaREST API .
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 monitoramento 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 seu Notebook para instalar o cliente 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.
Observação
Quando o senhor 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 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.
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 serTIMESTAMP
ou um tipo que possa ser convertido em carimbos de data/hora usando a funçãoto_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.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"])
)
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 |
---|---|
|
|
|
Coluna contendo os valores previstos do modelo. |
|
Coluna contendo o timestamp da solicitação de inferência. |
|
Coluna contendo o id do modelo usado para previsão. |
|
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 |
---|---|
|
Coluna contendo a verdade básica para as previsões do 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
.
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.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()
)
Atualize e visualize os resultados do monitor
Para refresh as 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. 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.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 um refresh que esteja na fila 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 revisar 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}")
programar
Para configurar um monitor para execução programada, use o 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",
)
)
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
:
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 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:
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{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
.
Exemplo Notebook : perfil de inferência (regressão)
Este Notebook ilustra como criar um monitor do tipo InferenceLog
para um problema de regressão.