Quais são os alertas do SQL do Databricks?

Artigo
07/11/2024

Os alertas do SQL do Databricks executam consultas periodicamente, avaliam condições definidas e enviam notificações se uma condição é atendida. Você pode configurar alertas para monitorar sua empresa e enviar notificações quando os dados relatados estiverem fora dos limites esperados. O agendamento de um alerta executa sua consulta subjacente e verifica os critérios de alerta. Isso é independente de qualquer agendamento que possa existir na consulta subjacente.

Importante

Alertas que aproveitam as consultas com parâmetros usam o valor padrão especificado no editor de SQL para cada parâmetro.

Exibir e organizar alertas

Use uma das seguintes opções para acessar alertas:

Clique em Workspace na barra lateral para exibir os alertas na pasta Início, onde eles são armazenados por padrão. Os usuários podem organizar os alertas em pastas no navegador de workspace acompanhado de outros objetos do Databricks.
Clique em Alertas na barra lateral para exibir a página de listagem de alertas.

Por padrão, os objetos são classificados em ordem cronológica inversa. Reordene a lista clicando nos títulos das colunas. Clique na guia Todos os alertas próxima à parte superior da tela para visualizar todos os alertas na espaço de trabalho. Clique na guia Meus alertas para visualizar alertas dos quais você é o proprietário.

A coluna Nome mostra o nome da cadeia de caracteres de cada alerta.
A coluna Estado mostra se o status do alerta é TRIGGERED, OK ou UNKNOWN.
Última Atualização mostra a hora ou a data da última atualização.
Criado em mostra a data e a hora em que o alerta foi criado.
- TRIGGERED significa que, na execução mais recente, a coluna Valor da consulta de destino atendeu à condição e ao limite configurados. Se o alerta verificar que “gatos” está acima de 1.500, ele será disparado, desde que “gatos” esteja acima de 1.500.
- OK significa que, na execução de consulta mais recente, a coluna Valor não atendeu à condição e ao limite configurados. Isso não significa que o alerta não foi disparado anteriormente. Se o valor de “cats” agora for 1.470, o alerta será exibido como OK.
- UNKNOWN significa que o Databricks SQL não tem dados suficientes para avaliar os critérios do alerta. Você verá esse status imediatamente após a criação do alerta e até que a consulta seja executada. Você também verá esse status se não houver dados no resultado da consulta ou se o resultado da consulta mais recente não incluir a Coluna Valor configurada.

Criar um alerta

Veja como criar um alerta em apenas uma coluna de uma consulta.

Realize um dos seguintes procedimentos:
- Clique em Novo na barra lateral e selecione Alerta.
- Clique em Alertas na barra lateral e clique no botão + Novo Alerta.
- Clique em Workspace na barra lateral e clique em + Criar alerta.
- Clique no menu kebab no canto superior direito de uma consulta salva e clique em + Criar Alerta.
No campo Consulta, pesquise uma consulta de destino.

Para alertar sobre várias colunas, você precisa modificar a consulta. Confira Agregações de alerta.
No campo Disparar condição, configure o alerta.
- O menu suspenso da coluna Valor controla qual campo do resultado da consulta é avaliado. As condições de alerta podem ser definidas no primeiro valor de uma coluna no resultado da consulta ou você pode optar por definir uma agregação em todas as linhas de uma única coluna, como SUM ou AVERAGE.
- O menu suspenso de Operador controla a operação lógica a ser aplicada.
- A entrada de texto Valor de limite é comparada com a coluna Valor usando a Condição especificada.
Clique em Visualizar alerta para visualizar o alerta e testar se o alerta seria disparado com os dados atuais.
No campo Quando o alerta é disparado, enviar notificação, selecione quantas notificações serão enviadas quando o alerta for disparado:
- Apenas uma vez: envia uma notificação quando o status do alerta mudar de OK para TRIGGERED.
- Toda vez que o alerta for avaliado: envia uma notificação sempre que o status do alerta for TRIGGERED, independentemente do status na avaliação anterior.
- No máximo a cada: envia uma notificação sempre que o status do alerta TRIGGERED estiver em um intervalo específico. Essa opção permite evitar a notificação de spam para alertas que são disparados com frequência.
Independentemente da configuração de notificação escolhida, você receberá uma notificação sempre que o status for de OK para TRIGGERED ou de TRIGGERED para OK. As configurações de agendamento afetam a quantidade de notificações que você receberá se o status permanecer TRIGGERED de uma execução para outra. Para saber detalhes, confira Frequência de notificação.
No menu suspenso Modelo, escolha um modelo:
- Usar modelo padrão: a notificação de alerta é uma mensagem com links para a tela Configuração de alertas e a tela Consulta.
- Usar modelo personalizado: a notificação de alertas inclui informações mais específicas sobre o alerta.
  1. Uma caixa composta de campos de entrada para o assunto e o corpo é exibida. Qualquer conteúdo estático é válido e você pode incorporar variáveis de modelo internas:
    - ALERT_STATUS: o status do alerta avaliado (cadeia de caracteres).
    - ALERT_CONDITION: o operador de condição de alerta (cadeia de caracteres).
    - ALERT_THRESHOLD: o limite de alertas (cadeia de caracteres ou número).
    - ALERT_COLUMN: o nome da coluna do alerta (cadeia de caracteres).
    - ALERT_NAME: o nome do alerta (cadeia de caracteres).
    - ALERT_URL: a URL da página de alerta (cadeia de caracteres).
    - QUERY_NAME: o nome da consulta associada (cadeia de caracteres).
    - QUERY_URL: a URL da página de consulta associada (cadeia de caracteres).
    - QUERY_RESULT_TABLE: a tabela HTML do resultado da consulta (cadeia de caracteres).
    - QUERY_RESULT_VALUE: o valor do resultado da consulta (cadeia de caracteres ou número).
    - QUERY_RESULT_ROWS: as linhas de resultado da consulta (matriz de valores).
    - QUERY_RESULT_COLS: as colunas de resultado da consulta (matriz de cadeia de caracteres).
    Um assunto de exemplo, por exemplo, poderia ser: Alert "{{ALERT_NAME}}" changed status to {{ALERT_STATUS}}.
  2. Você pode usar HTML para formatar mensagens em um modelo personalizado. As seguintes marcas e atributos são permitidos em modelos:
    - Marcas: <a>, <abbr>, <acronym>, <b>, <blockquote>, <body>, <br>, <code>, <div>, <em>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <head>, <hr>, <html>, <i>, <li>, <ol>, <p>, <span>, <strong>, <table>, <tbody>, <td>, <th>, <tr>, <ul>
    - Atributos: href (para <a>), title (para <a>, <abbr>, <acronym>)
  3. Selecione o botão de alternância Visualização para ver o resultado renderizado.
    
    Importante
    
    A visualização é útil para verificar se as variáveis de modelo foram renderizadas corretamente. Não é uma representação precisa do conteúdo de notificação eventual, pois cada destino de notificação pode exibir notificações de maneira diferente.
  4. Selecione Salvar alterações.
Clique em Criar alerta.
Clique em Adicionar Agenda.
- Use os seletores suspensos para especificar a frequência, o período, a hora de início e o fuso horário. Opcionalmente, marque a caixa de seleção Mostrar sintaxe cron para editar o agendamento na Sintaxe Quartz Cron.
- Escolha Mais opções para mostrar as configurações opcionais. Você também pode escolher:
  - Um nome para o agendamento.
  - Um SQL warehouse para potencializar a consulta. Por padrão, o SQL warehouse usado para execução de consulta ad hoc também é usado para um trabalho agendado. Use essa configuração opcional para selecionar um warehouse diferente para executar a consulta agendada.
Clique na guia Destinos na caixa de diálogo Adicionar agendamento.
- Use a lista suspensa para selecionar um destino de notificação disponível. Ou comece a digitar um nome de usuário para adicionar indivíduos.
Importante

Se pular essa etapa, você não será notificado quando o alerta for disparado.
Clique em Criar. Os detalhes salvos do alerta e da notificação aparecem na tela.
Compartilhe o agendamento.
- À direita do agendamento listado, escolha o menu kebab e selecione Editar permissões de agendamento.
- Escolha um usuário ou grupo no menu suspenso da caixa de diálogo.
- Escolha entre as seguintes permissões de agendamento:
  - SEM PERMISSÕES: nenhuma permissão foi concedida. Os usuários sem permissões não podem ver que o agendamento existe, mesmo se forem assinantes ou incluídos nos destinos de notificação listados.
  - PODE EXIBIR: concede permissões de acesso para exibir resultados de execuções agendadas.
  - PODE GERENCIAR EXECUÇÃO: concede permissão de acesso para exibição dos resultados de execuções agendadas.
  - PODE GERENCIAR: concede permissão para exibir, modificar e excluir agendas. Essa permissão é necessária para fazer alterações no intervalo de execução, atualizar a lista de execuções e pausar ou retomar o agendamento.
  - É PROPRIETÁRIO: concede todas as permissões de acesso ao PODE GERENCIAR. Além disso, as credenciais do proprietário do agendamento serão usadas para executar as consultas do painel. Somente um administrador do espaço de trabalho pode alterar o proprietário.
Importante

As permissões para alertas e agendamentos são separadas. Conceda acesso a usuários e grupos na lista de destinos de notificações para que eles possam exibir os resultados das execuções agendadas.
Compartilhe o alerta.
- Clique em próximo à parte superior direita da página.
- Adicione usuários ou grupos que devem ter acesso ao alerta.
- Escolha o nível de permissão apropriado e clique em Adicionar.

Importante

PODE GERENCIAR concede permissão para visualizar, modificar e excluir programações. Essa permissão é necessária para fazer alterações no intervalo de execução, atualizar a lista de destino de notificação e pausar ou retomar o agendamento.

Para obter mais informações sobre os níveis de permissão de alerta, consulte ACLs de alertas.

Agregações de alerta

Uma agregação em um alerta funciona modificando o SQL original da consulta SQL do Databricks anexada ao alerta. O alerta encapsula o texto da consulta original em uma CTE (expressão de tabela comum) e executa uma consulta de agregação de encapsulamento nela para agregar o resultado da consulta.

Por exemplo, uma agregação SUM em um alerta anexado a uma consulta com texto SELECT 1 AS column_name significa que sempre que o alerta é atualizado, o SQL modificado executado seria: WITH q AS (SELECT 1 AS column_name) SELECT SUM(column_name) FROM q.

Isso significa que o resultado da consulta original (pré-agregado) não pode ser mostrado em um corpo personalizado de alerta (com parâmetros como QUERY_RESULT_ROWS e QUERY_RESULT_COLS) sempre que houver uma agregação em um alerta. Em vez disso, essas variáveis exibirão apenas o resultado final da consulta pós-agregação.

Observação

Todas as condições de gatilho relacionadas a agregações não são compatíveis com a API.

Alerta em várias colunas

Para definir um alerta com base em várias colunas de uma consulta, sua consulta pode implementar a lógica de alerta e retornar um valor booliano para o alerta disparar. Por exemplo:

SELECT CASE WHEN drafts_count > 10000 AND archived_count > 5000 THEN 1 ELSE 0 END
FROM (
SELECT sum(CASE WHEN is_archived THEN 1 ELSE 0 END) AS archived_count,
sum(CASE WHEN is_draft THEN 1 ELSE 0 END) AS drafts_count
FROM queries) data

A consulta retorna 1 quando drafts_count > 10000 and archived_count > 5000. Em seguida, você pode configurar o alerta para disparar quando o valor for 1.

Frequência de notificação

O Databricks SQL envia notificações para os destinos de notificação escolhidos sempre que detecta que a status de Alerta foi alterada de OK para TRIGGERED ou vice-versa. Considere este exemplo em que um Alerta é configurado em uma consulta agendada para ser executado uma vez por dia. O status diário do Alerta aparece na tabela a seguir. Antes da segunda-feira, o status do alerta era OK.

Dia	Status do alerta
Monday	OK
Terça-feira	OK
Quarta-feira	DISPARADO
Quinta-feira	DISPARADO
Friday	DISPARADO
Sábado	DISPARADO
Sunday	OK

Se a frequência de notificação for definida como Just Once, o SQL do Databricks enviará uma notificação na quarta-feira quando o status for alterado de OK para TRIGGERED e novamente no domingo quando ele voltar a alterar. Ele não envia alertas na quinta-feira, na sexta-feira ou no sábado, a menos que você o configure especificamente para fazer isso porque o status do alerta não foi alterado entre as execuções nesses dias.

Configurar permissões de acesso ao alerta e transferir a propriedade do alerta

Você deve ter pelo menos a permissão GERENCIAR em uma consulta para compartilhar consultas. Para obter níveis de permissão de alerta, consulte ACLs de alertas.

Na barra lateral, clique em Alertas.
Clique em um alerta.
Clique no botão no canto superior direito para abrir a caixa de diálogo Compartilhamento.
Procure e selecione os grupos e os usuários e atribua o nível de permissão.
Clique em Adicionar.

Transferir a propriedade de um alerta

Ao salvar um alerta, você se torna o proprietário dele. Se o proprietário de um alerta for removido de um workspace, o alerta deixará de ter um proprietário. Um usuário administrador de workspace pode transferir a propriedade de um alerta para um usuário diferente. As entidades de serviço e os grupos não podem receber a atribuição de propriedade de um alerta. Você também pode transferir a propriedade usando a API de Permissões.

Como administrador do workspace, faça logon no workspace do Azure Databricks.
Na barra lateral, clique em Alertas.
Clique em um alerta.
Clique no botão Compartilhar no canto superior direito para abrir a caixa de diálogo Compartilhamento.
Clique no ícone de engrenagem no canto superior direito e clique em Atribuir novo proprietário.
Selecione o usuário ao qual a propriedade será atribuída.
Clique em Confirmar.

Compartilhar via