Configuração de alertas com base em dados no Snowflake¶

Introdução¶

Em alguns casos, você pode querer ser notificado ou tomar medidas quando os dados no Snowflake atenderem a certas condições. Por exemplo, você pode querer receber uma notificação quando:

• O uso de crédito do warehouse aumenta em uma porcentagem especificada de sua cota atual.

• O consumo de recursos para suas pipelines, tarefas, exibições materializadas etc. aumenta além de uma quantidade especificada.

• Seus dados não cumprem uma regra comercial específica que você definiu.

Para fazer isso, você pode configurar um alerta do Snowflake. Um alerta do Snowflake é um objeto em nível de esquema que especifica:

• Uma condição que aciona o alerta (por exemplo, a presença de consultas que levam mais de um segundo para serem concluídas).

• A ação a ser executada quando a condição for atendida (por exemplo, enviar uma notificação por e-mail, capturar alguns dados em uma tabela etc.).

• Quando e com que freqüência a condição deve ser avaliada (por exemplo, a cada 24 horas, todos os domingos à meia-noite etc.).

Por exemplo, suponha que você queira enviar uma notificação por e-mail quando o consumo de crédito exceder um determinado limite para um warehouse. Suponha que você queira verificar isso a cada 30 minutos. Você pode criar um alerta com as seguintes propriedades:

• Condição: o consumo de crédito para um warehouse (a soma da coluna credits_used na exibição WAREHOUSE_METERING_HISTORY no esquema ACCOUNT_USAGE) excede um limite especificado.

• Ação: enviar um e-mail ao administrador.

• Frequência/programação: verifique esta condição a cada 30 minutos.

Concessão dos privilégios para criar alertas¶

A fim de criar um alerta, você deve usar uma função que tenha os seguintes privilégios:

• O privilégio EXECUTEALERT na conta.

  Nota

  Este privilégio só pode ser concedido por um usuário com a função ACCOUNTADMIN.

• Os privilégios USAGE e CREATE ALERT no esquema no qual se deseja criar o alerta.

• O privilégio USAGE no banco de dados contendo o esquema.

• O privilégio USAGE no warehouse usado para executar o alerta.

Para conceder estes privilégios a uma função, use o comando GRANT <privilégios>.

Por exemplo, suponha que você queira criar uma função personalizada chamada my_alert_role que tenha os privilégios de criar um alerta no esquema chamado my_schema. Você quer que o alerta use o warehouse my_warehouse.

Para fazer isso:

1. Para ter um usuário com a função ACCOUNTADMIN, faça o seguinte:

   1. Crie a função personalizada.

      Por exemplo:

      USE ROLE ACCOUNTADMIN;
      
      CREATE ROLE my_alert_role;
      

      Copy

   2. Conceda o privilégio global EXECUTE ALERT a essa função personalizada.

      Por exemplo:

      GRANT EXECUTE ALERT ON ACCOUNT TO ROLE my_alert_role;
      

      Copy

   3. Conceda a função personalizada a um usuário.

      Por exemplo:

      GRANT ROLE my_alert_role TO USER my_user;
      

      Copy

2. Fazer com que os proprietários do banco de dados, esquema e warehouse concedam os privilégios necessários para criar o alerta para a função personalizada:

   • O proprietário do esquema deve conceder os privilégios CREATE ALERT e USAGE no esquema:

     GRANT CREATE ALERT ON SCHEMA my_schema TO ROLE my_alert_role;
     GRANT USAGE ON SCHEMA my_schema TO ROLE my_alert_role;
     

     Copy

   • O proprietário do banco de dados deve conceder o privilégio USAGE no banco de dados:

     GRANT USAGE ON DATABASE my_database TO ROLE my_alert_role;
     

     Copy

   • O proprietário do warehouse deve conceder o privilégio USAGE no warehouse:

     GRANT USAGE ON WAREHOUSE my_warehouse TO ROLE my_alert_role;
     

     Copy

Como criar um alerta¶

Suponha que sempre que uma ou mais linhas em uma tabela chamada gauge tiver um valor na coluna gauge_value que exceda 200, você queira inserir o carimbo de data/hora atual em uma tabela chamada gauge_value_exceeded_history.

Você pode criar um alerta para isso:

• Avalia a condição que gauge_value excede 200.

• Insere o carimbo de data/hora em gauge_value_exceeded_history se esta condição for avaliada como verdadeira.

Para criar um alerta chamado my_alert que faz isso:

1. Verifique se você está usando uma função que tenha os privilégios para criar um alerta.

   Se você não estiver usando essa função, execute o comando USE ROLE para usar essa função.

2. Verifique se você está usando o banco de dados e o esquema no qual você planeja criar o alerta.

   Se você não estiver usando esse banco de dados e esquema, execute os comandos USE DATABASE e USE SCHEMA para usar esse banco de dados e esquema.

3. Execute o comando CREATE ALERT para criar o alerta:

   CREATE OR REPLACE ALERT my_alert
     WAREHOUSE = mywarehouse
     SCHEDULE = '1 minute'
     IF( EXISTS(
       SELECT gauge_value FROM gauge WHERE gauge_value>200))
     THEN
       INSERT INTO gauge_value_exceeded_history VALUES (current_timestamp());
   

   Copy

   Para a descrição completa do comando CREATE ALERT, consulte CREATE ALERT.

   Nota

   Quando você cria um alerta, o alerta é suspenso por padrão. Você deve retomar o alerta recém-criado para que o alerta possa ser executado.

4. Retomar o alerta executando o comando ALTER ALERT … RESUME. Por exemplo:

   ALTER ALERT my_alert RESUME;
   

   Copy

Especificação de carimbos de data/hora com base em cronogramas de alerta¶

Em alguns casos, talvez seja necessário definir uma condição ou ação com base no cronograma de alerta.

Por exemplo, suponha que uma tabela tenha uma coluna de carimbo de data/hora que represente quando uma linha foi adicionada, e você deseja enviar um alerta se alguma nova linha foi adicionada entre o último alerta que foi avaliado com sucesso e o alerta programado atual. Em outras palavras, você quer avaliar:

<now> - <last_execution_of_the_alert>

Se você usar CURRENT_TIMESTAMP e a hora programada do alerta para calcular este intervalo de tempo, o intervalo calculado não contabiliza a latência entre a hora que o alerta é programado e a hora em que a condição de alerta é realmente avaliada.

Em vez disso, quando você precisar dos carimbos de data/hora do alerta do horário atual e do último alerta que foi avaliado com sucesso, use as seguintes funções:

• SCHEDULED_TIME retorna o carimbo de data/hora que representa quando o alerta atual foi programado.

• LAST_SUCCESSFUL_SCHEDULED_TIME retorna o carimbo de data/hora que representa quando o último alerta avaliado com sucesso foi programado.

Estas funções estão definidas no esquema SNOWFLAKE.ALERT. Para chamar estas funções, você precisa usar uma função que tenha sido concedida à função SNOWFLAKE.ALERT_VIEWER do banco de dados. Para conceder esta função a outra função, use o comando GRANT DATABASE ROLE. Por exemplo, para conceder esta função à função personalizada alert_role, execute:

GRANT DATABASE ROLE SNOWFLAKE.ALERT_VIEWER TO ROLE alert_role;

O exemplo a seguir envia uma mensagem de e-mail se alguma nova linha for adicionada ao my_table entre a hora em que o último alerta avaliado com sucesso foi programado e a hora em que o alerta atual foi programado:

CREATE OR REPLACE ALERT alert_new_rows
  WAREHOUSE = my_warehouse
  SCHEDULE = '1 MINUTE'
  IF (EXISTS (
      SELECT *
      FROM my_table
      WHERE row_timestamp BETWEEN SNOWFLAKE.ALERT.LAST_SUCCESSFUL_SCHEDULED_TIME()
       AND SNOWFLAKE.ALERT.SCHEDULED_TIME()
  ))
  THEN CALL SYSTEM$SEND_EMAIL(...);

Verificação dos resultados da instrução SQL para a condição na ação de alerta¶

Dentro da ação de um alerta, se você precisar verificar os resultados da instrução SQL para a condição:

1. Chame a função GET_CONDITION_QUERY_UUID para obter o ID da consulta da instrução SQL da condição.

2. Passe o ID da consulta para a função RESULT_SCAN para obter os resultados da execução dessa instrução SQL.

Por exemplo:

CREATE ALERT my_alert
  WAREHOUSE = my_warehouse
  SCHEDULE = '1 MINUTE'
  IF (EXISTS (
    SELECT * FROM my_source_table))
  THEN
    BEGIN
      LET condition_result_set RESULTSET :=
        (SELECT * FROM TABLE(RESULT_SCAN(SNOWFLAKE.ALERT.GET_CONDITION_QUERY_UUID())));
      ...
    END;

Execução manual de alertas¶

Em alguns casos, pode ser necessário executar um alerta manualmente. Por exemplo:

• Se estiver criando um novo alerta, talvez você queira verificar se o alerta funciona conforme o esperado.

• Talvez você queira executar o alerta em um ponto específico do pipeline de dados. Por exemplo, talvez você queira executar o alerta no fim de uma chamada de procedimento armazenado.

Para executar um alerta manualmente, execute o comando EXECUTE ALERT:

EXECUTE ALERT my_alert;

O comando EXECUTE ALERT aciona manualmente uma única execução de um alerta, independentemente da programação definida para o alerta.

Você pode executar este comando interativamente. Você também pode executar este comando de dentro de um procedimento armazenado ou de um bloco do Script Snowflake.

Para obter detalhes sobre os privilégios necessários para executar esse comando e o efeito dele em alertas suspensos, em execução e programados, consulte EXECUTE ALERT.

Suspensão e retomada de um alerta¶

Se você precisar impedir que um alerta seja executado temporariamente, você pode suspender o alerta executando o comando ALTER ALERT … SUSPEND. Por exemplo:

ALTER ALERT my_alert SUSPEND;

Para retomar um alerta suspenso, execute o comando ALTER ALERT … RESUME. Por exemplo:

ALTER ALERT my_alert RESUME;

Modificação de um alerta¶

Para modificar as propriedades de um alerta, execute o comando ALTER ALERT. Por exemplo:

• Para mudar o warehouse para o alerta chamado my_alert para my_other_warehouse, execute:

  ALTER ALERT my_alert SET WAREHOUSE = my_other_warehouse;
  

  Copy

• Para mudar a programação do alerta chamado my_alert a ser avaliado a cada 2 minutos, execute:

  ALTER ALERT my_alert SET SCHEDULE = '2 minutes';
  

  Copy

• Para alterar a condição do alerta chamado my_alert para que você seja alertado se alguma linha da tabela chamada gauge tiver valores maiores que 300 na coluna gauge_value, execute:

  ALTER ALERT my_alert MODIFY CONDITION EXISTS (SELECT gauge_value FROM gauge WHERE gauge_value>300);
  

  Copy

• Para mudar a ação do alerta chamado my_alert para CALL my_procedure(), execute:

  ALTER ALERT my_alert MODIFY ACTION CALL my_procedure();
  

  Copy

Descarte de um alerta¶

Para descartar um alerta, execute o comando DROP ALERT. Por exemplo:

DROP ALERT my_alert;

Para descartar um alerta sem gerar um erro se o alerta não existir, execute:

DROP ALERT IF EXISTS my_alert;

Visualização de detalhes sobre um alerta¶

Para listar os alertas que foram criados em uma conta, banco de dados ou esquema, execute o comando SHOW ALERTS. Por exemplo, para listar os alertas que foram criados no esquema atual, execute o seguinte comando:

SHOW ALERTS;

Este comando lista os alertas que você possui e os alertas nos quais você tem privilégio MONITOR ou OPERATE.

Para ver os detalhes sobre um alerta específico, execute o comando DESCRIBE ALERT. Por exemplo:

DESC ALERT my_alert;

Monitoramento da execução de alertas¶

Para monitorar a execução dos alertas, você pode:

• Verificar os resultados da ação que foi especificada para o alerta. Por exemplo, se a ação tiver inserido linhas em uma tabela, você poderá verificar a existência de novas linhas na tabela.

• Veja o histórico das execuções de alerta usando uma das seguintes opções:

  • A função de tabela ALERT_HISTORY no esquema INFORMATION_SCHEMA.

    Por exemplo, para ver as execuções de alertas na última hora, execute a seguinte instrução:

    SELECT *
    FROM
      TABLE(INFORMATION_SCHEMA.ALERT_HISTORY(
        SCHEDULED_TIME_RANGE_START
          =>dateadd('hour',-1,current_timestamp())))
    ORDER BY SCHEDULED_TIME DESC;
    

    Copy

  • A exibição ALERT_HISTORY no esquema ACCOUNT_USAGE no banco de dados SNOWFLAKE compartilhado.

No histórico de consultas, o nome do usuário que executou a consulta será SYSTEM. (Os alertas são executados pelo serviço do sistema.)