Émettre des événements de trace dans Snowflake Scripting¶
Vous pouvez utiliser les fonctions SYSTEM Snowflake pour émettre des événements de trace à partir d’une fonction ou d’un gestionnaire de procédure écrit dans Exécution de scripts Snowflake.
Avant d’émettre des événements de trace, assurez-vous que le niveau de trace est défini de manière à ce que les données souhaitées soient stockées dans la table des événements. Pour plus d’informations, voir Définition des niveaux de journalisation, des métriques et du traçage.
Note
Avant de commencer à émettre des événements de trace, vous devez mettre en place une table d’événements. Pour plus d’informations, voir Aperçu de la table d’événements.
Vous pouvez accéder aux données de trace stockées en exécutant une commande SELECT sur la table des événements. Pour plus d’informations, voir Affichage des données de trace.
Pour des informations générales sur la configuration de la journalisation et la récupération des messages dans Snowflake, voir Événements de trace pour les fonctions et les procédures.
Note
Pour les lignes directrices à garder à l’esprit lors de l’ajout d’événements de trace, voir Lignes directrices générales pour l’ajout d’événements de trace.
Ajout d’événements de trace¶
Vous pouvez ajouter des événements de trace en appelant la fonction SYSTEM$ADD_EVENT, en indiquant le nom de l’événement. Il est également possible d’associer des attributs (paires clé-valeur) à un événement.
Le code de l’exemple suivant ajoute deux événements, SProcEmptyEvent et SProcEventWithAttributes. Avec SProcEventWithAttributes, le code ajoute également deux attributs : key1 et key2.
SYSTEM$ADD_EVENT('SProcEmptyEvent');
SYSTEM$ADD_EVENT('SProcEventWithAttributes', {'key1': 'value1', 'key2': 'value2'});
L’ajout de ces événements donne lieu à deux lignes dans la table des événements, chacune avec une valeur différente dans la colonne RECORD :
{
"name": "SProcEmptyEvent"
}
{
"name": "SProcEventWithAttributes"
}
La ligne d’événement SProcEventWithAttributes comprend les attributs suivants dans la colonne RECORD_ATTRIBUTES de la ligne :
{
"key1": "value1",
"key2": "value2"
}
Ajout d’attributs de span¶
Vous pouvez définir des attributs (paires clé-valeur) associés aux spans en appelant la fonction SYSTEM$SET_SPAN_ATTRIBUTES.
Pour plus de détails sur les spans, voir Comment Snowflake représente les événements de trace.
La fonction SYSTEM$SET_SPAN_ATTRIBUTES est disponible sous la forme suivante :
SYSTEM$SET_SPAN_ATTRIBUTES(<object>);
où :
objectest un objet de Snowflake Scripting contenant des paires clé-valeur qui spécifient les attributs de cet événement de trace.
Le code de l’exemple suivant crée deux attributs et définit leurs valeurs :
SYSTEM$SET_SPAN_ATTRIBUTES('{'attr1':'value1', 'attr2':true}');
La définition de ces attributs se traduit par les éléments suivants dans la colonne RECORD_ATTRIBUTES de la table des événements :
{
"attr1": "value1",
"attr2": "value2"
}
Exemples¶
Le code de l’exemple suivant utilise la fonction SYSTEM$ADD_EVENT pour ajouter un événement nommé name_a et un événement nommé name_b. Avec name_b, il associe deux attributs, score et pass. Le code utilise également SYSTEM$SET_SPAN_ATTRIBUTES pour définir deux attributs pour le span, key1 et key2.
CREATE OR REPLACE PROCEDURE pi_proc()
RETURNS DOUBLE
LANGUAGE SQL
AS $$
BEGIN
-- Add an event without attributes
SYSTEM$ADD_EVENT('name_a');
-- Add an event with attributes
LET attr := {'score': 89, 'pass': TRUE};
SYSTEM$ADD_EVENT('name_b', attr);
-- Set attributes for the span
SYSTEM$SET_SPAN_ATTRIBUTES({'key1': 'value1', 'key2': TRUE});
RETURN 3.14;
END;
$$;
CALL pi_proc();
Émettre automatiquement des événements de trace pour les tâches enfants et les exceptions¶
Vous pouvez émettre automatiquement les types d’événements de trace supplémentaires suivants pour une procédure stockée Snowflake Scripting dans la table des événements :
Interception des exceptions.
Informations sur l’exécution des tâches enfants.
Statistiques sur les tâches enfants.
Statistiques sur les procédures stockées, y compris le temps d’exécution et les valeurs d’entrée.
L’émission automatique de trace est destinée aux cas d’utilisation suivants :
Vous souhaitez émettre des événements de trace prédéfinis sans modifier le corps de la procédure stockée.
Vous souhaitez collecter des informations sur l’exécution des procédures stockées que vous pourrez analyser ultérieurement, notamment :
Informations sur l’exécution des tâches enfant (telles que
childJobUUID,rowCount,exceptionCode, etc.).Temps d’exécution de la tâche enfant.
Valeurs des arguments d’entrée.
Vous souhaitez avoir plus de visibilité sur l’exécution de la procédure stockée afin de faciliter son développement et son débogage sans avoir à ajouter manuellement du code de traçage dans la procédure.
Pour émettre automatiquement ces événements de trace supplémentaires pour une procédure stockée, donnez au paramètre AUTO_EVENT_LOGGING la valeur TRACING ou ALL à l’aide de la commande ALTER PROCEDURE. Lorsque vous donnez à ce paramètre la valeur ALL, des messages de connexion supplémentaires sont également générés automatiquement pour la procédure stockée.
Important
Les informations supplémentaires ne sont ajoutées à la table des événements que si la valeur effective de TRACE_LEVEL est définie sur ALWAYS ou ON_EVENT. Pour plus d’informations, voir Définition des niveaux de journalisation, des métriques et du traçage.
Par exemple, créez une table simple et insérez des données :
CREATE OR REPLACE TABLE test_auto_event_logging (id INTEGER, num NUMBER(12, 2));
INSERT INTO test_auto_event_logging (id, num) VALUES
(1, 11.11),
(2, 22.22);
Ensuite, créez une procédure stockée nommée auto_event_logging_sp. Cet échantillon de procédure stockée met à jour une ligne de la table, puis effectue une requête sur la table :
CREATE OR REPLACE PROCEDURE auto_event_logging_sp(
table_name VARCHAR,
id_val INTEGER,
num_val NUMBER(12, 2))
RETURNS TABLE()
LANGUAGE SQL
AS
$$
BEGIN
UPDATE IDENTIFIER(:table_name)
SET num = :num_val
WHERE id = :id_val;
LET res RESULTSET := (SELECT * FROM IDENTIFIER(:table_name) ORDER BY id);
RETURN TABLE(res);
EXCEPTION
WHEN statement_error THEN
res := (SELECT :sqlcode sql_code, :sqlerrm error_message, :sqlstate sql_state);
RETURN TABLE(res);
END;
$$
;
Les exemples suivants permettent de définir le paramètre AUTO_EVENT_LOGGING pour la procédure stockée :
ALTER PROCEDURE auto_event_logging_sp(VARCHAR, INTEGER, NUMBER)
SET AUTO_EVENT_LOGGING = 'TRACING';
ALTER PROCEDURE auto_event_logging_sp(VARCHAR, INTEGER, NUMBER)
SET AUTO_EVENT_LOGGING = 'ALL';
Appelez la procédure stockée :
CALL auto_event_logging_sp('test_auto_event_logging', 2, 44.44);
+----+-------+
| ID | NUM |
|----+-------|
| 1 | 11.11 |
| 2 | 44.44 |
+----+-------+
Effectuez une requête dans la table des événements pour obtenir les données de trace enregistrées par la procédure stockée nommée auto_event_logging_sp. Pour chaque événement de trace, imprimez l’horodatage, le nom et les attributs de l’événement.
SELECT
TIMESTAMP as time,
RECORD['name'] as event_name,
RECORD_ATTRIBUTES as attributes,
FROM
my_db.public.my_events
WHERE
RESOURCE_ATTRIBUTES['snow.executable.name'] LIKE '%AUTO_EVENT_LOGGING_SP%'
AND RECORD_TYPE LIKE 'SPAN%';
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+
| TIME | EVENT_NAME | ATTRIBUTES |
|-------------------------+--------------------------+-----------------------------------------------------------------------------------------------|
| 2024-10-25 20:48:49.844 | "snow.auto_instrumented" | { |
| | | "childJobTime": 474, |
| | | "executionTime": 2, |
| | | "inputArgumentValues": "{ ID_VAL: 2, TABLE_NAME: test_auto_event_logging, NUM_VAL: 44.44 }" |
| | | } |
| 2024-10-25 20:48:49.740 | "child_job" | { |
| | | "childJobUUID": "01b7ef00-0003-01d1-0000-a99501233092", |
| | | "rowCount": 1, |
| | | "rowsAffected": 1 |
| | | } |
| 2024-10-25 20:48:49.843 | "child_job" | { |
| | | "childJobUUID": "01b7ef00-0003-01d1-0000-a99501233096", |
| | | "rowCount": 2, |
| | | "rowsAffected": 0 |
| | | } |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+
Appelez maintenant la procédure stockée, mais spécifiez une table qui n’existe pas afin de provoquer une exception :
CALL auto_event_logging_sp('no_table', 2, 82.44);
+----------+-----------------------------------------------------+-----------+
| SQL_CODE | ERROR_MESSAGE | SQL_STATE |
|----------+-----------------------------------------------------+-----------|
| 2003 | SQL compilation error: | 42S02 |
| | Object 'NO_TABLE' does not exist or not authorized. | |
+----------+-----------------------------------------------------+-----------+
Exécutez à nouveau la requête sur la table des événements pour obtenir les informations relatives à l’exception :
SELECT
TIMESTAMP as time,
RECORD['name'] as event_name,
RECORD_ATTRIBUTES as attributes,
FROM
my_db.public.my_events
WHERE
RESOURCE_ATTRIBUTES['snow.executable.name'] LIKE '%AUTO_EVENT_LOGGING_SP%'
AND RECORD_TYPE LIKE 'SPAN%';
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+
| TIME | EVENT_NAME | ATTRIBUTES |
|-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------|
| 2024-10-25 20:52:43.633 | "snow.auto_instrumented" | { |
| | | "childJobTime": 66, |
| | | "executionTime": 4, |
| | | "inputArgumentValues": "{ ID_VAL: 2, TABLE_NAME: no_table, NUM_VAL: 82.44 }" |
| | | } |
| 2024-10-25 20:52:43.601 | "caught_exception" | { |
| | | "exceptionCode": 2003, |
| | | "exceptionMessage": "SQL compilation error:\nObject 'NO_TABLE' does not exist or not authorized." |
| | | } |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+