Actions personnalisées pour les budgets

Vous pouvez configurer un budget pour appeler automatiquement une procédure stockée lorsqu’un seuil de dépenses est atteint. Cela vous permet d’effectuer des actions automatisées en réponse à la consommation de crédits, telles que la suspension d’entrepôts, l’envoi d’alertes personnalisées ou l’enregistrement des événements de dépenses dans une table. Les actions personnalisées ne remplacent pas les notifications que Snowflake envoie lorsque la consommation devrait dépasser votre limite budgétaire.

Lorsque vous définissez une action personnalisée, vous indiquez si celle-ci doit appeler la procédure stockée en fonction de la consommation de crédit prévue ou de la consommation de crédit réelle, puis vous définissez le seuil. Lorsque la consommation prévue ou réelle atteint le seuil, la procédure stockée s’exécute.

Exigences en matière de procédures stockées

La procédure stockée qui est appelée par une action personnalisée doit répondre aux exigences suivantes :

Après avoir créé une procédure stockée qui répond à ces exigences, vous devez accorder à l’application SNOWFLAKE le privilège USAGE sur la procédure et sa base de données/schéma parent. Par exemple, si le nom complet de votre procédure stockée est code_db.sch1.alert_team, exécutez les commandes suivantes :

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

Note

Si vous mettez à jour la procédure stockée après l’avoir ajoutée à une action personnalisée, vous devez accorder de nouveau le privilège USAGE sur cette procédure à l’application SNOWFLAKE.

Ajouter une action personnalisée à un budget

Vous pouvez ajouter plusieurs actions personnalisées au budget du compte ou à un budget personnalisé, mais vous ne pouvez pas ajouter plus de 10 actions personnalisées au même budget. Une action personnalisée se compose des éléments suivants :

  • Procédure stockée : Référence à la procédure à appeler.

  • Arguments : Tableau d’arguments à transmettre à la procédure stockée.

  • Seuil : Pourcentage de la limite budgétaire qui déclenche l’action personnalisée (par exemple, 75 %).

  • Type de déclencheur : Indique si l’action personnalisée est déclenchée en fonction de la consommation projetée ou de la consommation réelle.

Pour ajouter une action personnalisée à un budget, appelez la méthode ADD_CUSTOM_ACTION sur l’instance de budget. Par exemple, le code suivant ajoute une action personnalisée qui appelle la procédure stockée send_email_notification lorsqu’il est prévu que les dépenses dépassent 75 % de la limite budgétaire :

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

Pour un exemple de bout en bout qui inclut la création de la procédure stockée qui est appelée par l’action personnalisée, voir Exemple étendu.

Supprimer une action personnalisée d’un budget

Pour supprimer une action personnalisée d’un budget, appelez la méthode REMOVE_CUSTOM_ACTIONS sur l’instance de budget. Vous pouvez utiliser cette méthode pour effectuer les actions suivantes :

  • Supprimer toutes les actions personnalisées d’un budget. Par exemple :

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

  • Supprimer toutes les actions personnalisées qui ont un seuil spécifié. Par exemple, pour supprimer toutes les actions personnalisées qui sont déclenchées lorsque la consommation atteint 75 %, exécutez la commande suivante :

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

  • Supprimer une action personnalisée spécifiée d’un budget. Par exemple, pour supprimer l’action personnalisée qui appelle la procédure stockée my_sp lorsque la consommation atteint 75 %, exécutez la commande suivante :

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

    Astuce

    Si vous supprimez une action spécifique, utilisez le nom de procédure complet renvoyé par la méthode GET_CUSTOM_ACTIONS.

Exemple étendu

L’exemple suivant montre comment écrire une procédure stockée appelée par une action personnalisée, accorder les privilèges nécessaires à la procédure, puis ajouter l’action personnalisée au budget.

  1. Créez une procédure stockée qui est conforme à toutes les exigences :

    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. Accordez des privilèges sur la procédure stockée à l’application 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. Ajoutez l’action personnalisée au budget afin qu’elle soit déclenchée lorsque la consommation atteint 90 % de la limite de dépenses du budget :

    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

Dépannage des actions personnalisées

Si une action personnalisée ne fonctionne pas comme prévu, utilisez les méthodes suivantes pour diagnostiquer le problème.

Surveiller l’exécution des actions personnalisées

Snowflake utilise des tâches pour exécuter des actions personnalisées. Ces tâches suivent la convention de dénomination BUDGET_CUSTOM_ACTION_TRIGGER_AT_%. Pour vérifier le statut d’exécution de toutes les tâches d’actions personnalisées pour une instance de budget, exécutez la requête suivante :

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

Afficher l’historique du déclencheur d’action

Pour voir quelles actions personnalisées ont été déclenchées à partir d’un budget spécifique sur une période donnée, exécutez la requête suivante :

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

Pour vérifier l’historique de déclenchement d’une action personnalisée spécifique, obtenez d’abord l’ID de l’action en appelant la méthode GET_CUSTOM_ACTIONS :

CALL <budget_name>!GET_CUSTOM_ACTIONS();
Copy

Utilisez alors l’ID d’action dans la requête suivante :

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

Dépannage des actions qui ne se déclenchent pas

Si une action personnalisée ne se déclenche pas comme prévu, vérifiez les problèmes courants suivants. Supposons que votre budget personnalisé soit budget_db.sch1.my_budget.

Procédure stockée ou privilèges modifiés

Vérifiez que la procédure stockée appelée par l’action personnalisée est toujours valide et que l’application SNOWFLAKE dispose encore des privilèges nécessaires. Appelez la méthode CONFIRM_CUSTOM_ACTIONS_ACCESS pour valider les privilèges de contrôle d’accès et de la procédure stockée :

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

Le budget n’est pas activé

Pour les budgets de compte uniquement, vérifiez que le budget est activé en appelant la méthode GET_CONFIG et en vérifiant le champ is_active.

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

Le budget ne dispose pas de limite de dépense

Les actions personnalisées ne se déclencheront pas si le budget n’a pas de limite de dépenses configurée. Vérifiez la limite de dépense :

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

Le budget ne suit aucune ressource

Vérifiez que le budget suit les ressources en contrôlant l’historique des dépenses :

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

L’action personnalisée s’est récemment déclenchée

Pour éviter un déclenchement excessif, Snowflake limite la fréquence à laquelle une action personnalisée peut s’exécuter :

  • Si l’action personnalisée s’exécute lorsqu’il est prévu que la consommation de crédit atteigne un seuil de dépenses, la procédure stockée ne sera pas appelée plus d’une fois par jour.

  • Si l’action personnalisée s’exécute lorsque la consommation de crédit atteint une limite de dépenses réelles, la procédure stockée ne sera pas appelée plus d’une fois par mois.

Vérifiez le champ LAST_TRIGGER_ATTEMPT_TIME en appelant la méthode GET_CUSTOM_ACTIONS.