Ações personalizadas para orçamentos

Você pode configurar um orçamento para chamar automaticamente um procedimento armazenado quando um limite de gastos for atingido. Isso permite que você execute ações automatizadas em resposta ao consumo de crédito, como suspender warehouses, carregar alertas personalizados ou registrar eventos de gastos em uma tabela. Ações personalizadas não substituem as notificações que o Snowflake envia quando o consumo previsto excede o limite do seu orçamento.

Ao definir uma ação personalizada, você especifica se ela chama o procedimento armazenado com base no consumo de crédito projetado ou no consumo de crédito real e, em seguida, define o limite. Quando o consumo projetado ou real atinge o limite, o procedimento armazenado é executado.

Requisitos do procedimento armazenado

O procedimento armazenado chamado por uma ação personalizada deve atender aos seguintes requisitos:

Depois de criar um procedimento armazenado que atenda a esses requisitos, você deve conceder ao aplicativo SNOWFLAKE o privilégio USAGE no procedimento e em seu banco de dados/esquema pai. Por exemplo, se o nome totalmente qualificado do procedimento armazenado é code_db.sch1.alert_team, execute os seguintes comandos:

GRANT USAGE ON DATABASE code_db TO APPLICATION SNOWFLAKE;
GRANT USAGE ON SCHEMA code_db.sch1 TO APPLICATION SNOWFLAKE;
GRANT USAGE ON PROCEDURE code_db.sch1.alert_team(STRING, NUMBER) TO APPLICATION SNOWFLAKE;
Copy

Nota

Se você atualizar o procedimento armazenado depois de adicioná-lo a uma ação personalizada, deverá conceder novamente o privilégio USAGE no procedimento ao aplicativo SNOWFLAKE.

Adicionar uma ação personalizada a um orçamento

Você pode adicionar várias ações personalizadas ao orçamento da conta ou a um orçamento personalizado, mas não pode adicionar mais de 10 ações personalizadas ao mesmo orçamento. Uma ação personalizada consiste nos seguintes componentes:

  • Procedimento armazenado: uma referência ao procedimento a ser chamado.

  • Argumentos: uma matriz de argumentos a serem passados ​​para o procedimento armazenado.

  • Limite: a porcentagem do limite do orçamento que aciona a ação personalizada (por exemplo, 75%).

  • Tipo de acionador: se a ação personalizada é acionada com base no consumo projetado ou real.

Para adicionar uma ação personalizada a um orçamento, chame o método ADD_CUSTOM_ACTION na instância do orçamento. Por exemplo, o código a seguir adiciona uma ação personalizada que chama o procedimento armazenado send_email_notification quando a previsão de gastos ultrapassa 75% do limite do orçamento:

CALL budget_db.sch1.my_budget!ADD_CUSTOM_ACTION(
  SYSTEM$REFERENCE('PROCEDURE', 'code_db.sch1.alert_team(string, string, string)'),
  ARRAY_CONSTRUCT('admin@example.com', 'Budget Alert', 'Spending at 75% of budget limit'),
  'PROJECTED',
  75);
Copy

Para obter um exemplo completo que inclui a criação do procedimento armazenado chamado pela ação personalizada, consulte Exemplo estendido.

Remover uma ação personalizada de um orçamento

Para remover uma ação personalizada de um orçamento, chame o método REMOVE_CUSTOM_ACTIONS na instância do orçamento. Você pode usar esse método para fazer o seguinte:

  • Remover todas as ações personalizadas de um orçamento. Por exemplo:

    CALL budget_db.sch1.my_budget!REMOVE_CUSTOM_ACTIONS();
    Copy

  • Remover todas as ações personalizadas que têm um limite especificado. Por exemplo, para remover todas as ações personalizadas que são acionadas quando o consumo atinge 75%, execute o seguinte comando:

    CALL budget_db.sch1.my_budget!REMOVE_CUSTOM_ACTIONS(75);
    Copy

  • Remover uma ação personalizada específica de um orçamento. Por exemplo, para remover a ação personalizada que chama o procedimento armazenado my_sp quando o consumo atinge 75%, execute o seguinte comando:

    CALL budget_db.sch1.my_budget!REMOVE_CUSTOM_ACTIONS(75, 'code_db.sch1.my_sp');
    Copy

    Dica

    Se você estiver removendo uma ação específica, use o nome totalmente qualificado do procedimento que é retornado pelo método GET_CUSTOM_ACTIONS.

Exemplo estendido

O exemplo a seguir demonstra como escrever um procedimento armazenado chamado por uma ação personalizada, conceder os privilégios necessários ao procedimento e, em seguida, adicionar a ação personalizada ao orçamento.

  1. Crie um procedimento armazenado que esteja em conformidade com todos os requisitos:

    CREATE OR REPLACE PROCEDURE code_db.sch1.alert_team(
    integration_name string,
    email_list string,
    email_subject string,
    email_content string)
RETURNS STRING
LANGUAGE JAVASCRIPT
EXECUTE AS OWNER
AS
$$
    var sql_command = "CALL SYSTEM$SEND_EMAIL('" + INTEGRATION_NAME + "', " +
                                            "'" +  EMAIL_LIST + "', " +
                                            "'" + EMAIL_SUBJECT + "'," +
                                            "'" + EMAIL_CONTENT + "'" + ");";
    var statement1 = snowflake.createStatement({sqlText: sql_command});
    statement1.execute();
    return "alert sent";
$$;
    Copy

  2. Conceda privilégios no procedimento armazenado para o aplicativo SNOWFLAKE:

    GRANT USAGE ON DATABASE code_db TO APPLICATION SNOWFLAKE;
GRANT USAGE ON SCHEMA code_db.sch1 TO APPLICATION SNOWFLAKE;
GRANT USAGE ON PROCEDURE code_db.sch1.alert_team(STRING, STRING, STRING, STRING)
  TO APPLICATION SNOWFLAKE;
    Copy

  3. Adicione a ação personalizada ao orçamento para que ela seja acionada quando o consumo atingir 90% do limite de gastos do orçamento:

    CALL budget_db.sch1.my_budget!ADD_CUSTOM_ACTION(
  SYSTEM$REFERENCE('PROCEDURE', 'code_db.sch1.alert_team(string, string, string, string)'),
  ARRAY_CONSTRUCT('my_int', 'admin@example.com', 'Budget Alert', 'Spending at 90% of budget limit'),
  'ACTUAL',
  90);
    Copy

Solução de problemas de ações personalizadas

Se uma ação personalizada não estiver funcionando conforme o esperado, use os seguintes métodos para diagnosticar o problema.

Monitorar a execução da ação personalizada

O Snowflake usa tarefas para executar ações personalizadas. Essas tarefas seguem a convenção de nomenclatura BUDGET_CUSTOM_ACTION_TRIGGER_AT_%. Para verificar o status de execução de todas as tarefas de ação personalizadas para uma instância de orçamento, execute a seguinte consulta:

SELECT th.*, ci.name AS budget_name
  FROM SNOWFLAKE.ACCOUNT_USAGE.TASK_HISTORY th
  JOIN SNOWFLAKE.ACCOUNT_USAGE.CLASS_INSTANCES ci
    ON th.instance_id = ci.id
  WHERE ci.class_name = 'BUDGET'
    AND th.name ILIKE 'BUDGET_CUSTOM_ACTION_TRIGGER_AT_%'
    AND ci.name = '<budget_name>'
  ORDER BY th.completed_time DESC
  LIMIT 10;
Copy

Visualizar histórico de acionamento de ação

Para ver quais ações personalizadas foram acionadas a partir de um orçamento específico durante um determinado período, execute a seguinte consulta:

SELECT th.*, ci.name as budget_name
  FROM SNOWFLAKE.ACCOUNT_USAGE.TASK_HISTORY th
  JOIN SNOWFLAKE.ACCOUNT_USAGE.CLASS_INSTANCES ci
    ON th.instance_id = ci.id
  WHERE ci.class_name = 'BUDGET'
    AND th.name ILIKE 'BUDGET_CUSTOM_ACTION_TRIGGER_AT_%'
    AND ci.name = '<budget_name>'
    AND th.COMPLETED_TIME >= DATEADD('day', -7, CURRENT_TIMESTAMP())
  ORDER BY th.completed_time DESC;
Copy

Para verificar o histórico de acionamento de uma ação personalizada específica, primeiro obtenha o ID da ação chamando o método GET_CUSTOM_ACTIONS:

CALL <budget_name>!GET_CUSTOM_ACTIONS();
Copy

Em seguida, use o ID da ação na seguinte consulta:

SELECT th.*, ci.name AS budget_name
  FROM SNOWFLAKE.ACCOUNT_USAGE.TASK_HISTORY th
  JOIN SNOWFLAKE.ACCOUNT_USAGE.CLASS_INSTANCES ci
    ON th.instance_id = ci.id
  WHERE ci.class_name = 'BUDGET'
    AND th.name ILIKE 'BUDGET_CUSTOM_ACTION_TRIGGER_AT_%'
    AND th.query_text ILIKE '%<action_id>%'
    AND ci.name = '<budget_name>'
    AND th.COMPLETED_TIME >= DATEADD('day', -7, CURRENT_TIMESTAMP())
  ORDER BY th.completed_time DESC;
Copy

Solucionar problemas de ações que não estão sendo acionadas

Se uma ação personalizada não estiver sendo acionada quando esperado, verifique os seguintes problemas comuns. Suponha que seu orçamento personalizado seja budget_db.sch1.my_budget.

Procedimento armazenado ou privilégios alterados

Verifique se o procedimento armazenado chamado pela ação personalizada ainda é válido e se o aplicativo SNOWFLAKE ainda tem os privilégios necessários. Chame o método CONFIRM_CUSTOM_ACTIONS_ACCESS para validar o procedimento armazenado e os privilégios de controle de acesso:

CALL budget_db.sch1.my_budget!CONFIRM_CUSTOM_ACTIONS_ACCESS();
Copy

Orçamento não ativado

Somente para orçamentos de conta, verifique se o orçamento está ativado chamando o método GET_CONFIG e verificando o campo is_active.

CALL budget_db.sch1.my_budget!GET_CONFIG();
Copy

Orçamento sem limite de gastos

As ações personalizadas não serão acionadas se o orçamento não tiver um limite de gastos configurado. Verifique o limite de gastos:

CALL budget_db.sch1.my_budget!GET_SPENDING_LIMIT();
Copy

O orçamento não está rastreando nenhum recurso

Verifique se o orçamento está rastreando recursos verificando o histórico de gastos:

CALL budget_db.sch1.my_budget!GET_SPENDING_HISTORY();
Copy

Ação personalizada acionada recentemente

Para impedir acionamentos excessivos, o Snowflake limita a frequência com que uma ação personalizada pode ser executada:

  • Se a ação personalizada for executada quando o consumo de crédito estiver projetado para atingir um limite de gastos, o procedimento armazenado não será chamado mais de uma vez por dia.

  • Se a ação personalizada for executada quando o consumo de crédito atingir um limite de gastos reais, o procedimento armazenado não será chamado mais de uma vez por mês.

Verifique o campo LAST_TRIGGER_ATTEMPT_TIME chamando o método GET_CUSTOM_ACTIONS.