Événements de trace pour les fonctions et les procédures¶

Vous pouvez émettre des événements de trace à partir du code du gestionnaire pour une procédure, une UDF, ou une UDTF, y compris ceux que vous écrivez en utilisant les APIs Snowpark. Pour une liste des langages de gestionnaire pris en charge, voir Langues acceptées.

Note

Avant de pouvoir collecter des données d’événements de trace, vous devez activer la collecte de données de télémétrie. Quand vous instrumentez votre code, Snowflake génère les données et les collecte dans une table d’événements.

Les événements de trace sont un type de données de télémétrie (comme les messages de journal) qui permettent de savoir quand un événement s’est produit dans le système ou l’application. Contrairement aux messages du journal, les événements de trace ont une charge utile structurée, ce qui en fait un bon choix pour l’analyse des données. Par exemple, vous pouvez utiliser les événements de trace pour capturer certains nombres calculés pendant l’exécution de votre fonction, et analyser ces nombres par la suite.

Dans une procédure ou une UDF, vous pouvez associer des attributs (paires clé-valeur) qui doivent être capturés dans le cadre des événements de trace. Par exemple, si vous souhaitez capturer les noms et les valeurs des paramètres dans un événement de trace, vous pouvez ajouter un événement de trace nommé parameters et définir les noms et les valeurs des paramètres en tant qu’attributs de l’événement.

Lorsqu’une procédure ou une fonction s’exécute avec succès, Snowflake émet les événements de trace qui ont été ajoutés. Snowflake rend ces événements de trace disponibles dans la table des événements actifs associés au compte. Pour une explication des tables d’événements, voir Aperçu de la table d’événements.

Vous pouvez accéder aux données d’événement de trace pour l’analyse des manières suivantes :

Exécutez une commande SELECT sur la table d’événements.
Affichez les entrées de trace dans Snowsight.

Exemple de trace¶

Le code Python de l’exemple suivant définit un attribut example.proc.do_tracing sur le span avec une valeur de begin. Il émet également un événement event_with_attributes avec des attributs example.key1 et example.key2.

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
  telemetry.set_span_attribute("example.proc.do_tracing", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  return "SUCCESS"
$$;

Copy

Prise en main¶

Pour commencer à utiliser les traces d’événements à partir du code du gestionnaire, suivez ces étapes de haut niveau :

Mettre en place une table d’événements.

Snowflake utilise votre table d’événements pour stocker les données d’événements émises par votre code du gestionnaire. Une table d’événements comporte des colonnes prédéfinies par Snowflake.
Familiarisez-vous avec l’API de trace d’événement pour le langage du gestionnaire que vous allez utiliser.

reportez-vous à Langues acceptées pour une liste des langages de gestionnaire, puis consultez le contenu sur la façon d’émettre des événements de trace à partir de votre langage.
Ajoutez le code de trace de l’événement à votre gestionnaire.
Apprenez à récupérer les données de trace des événements à partir de la table des événements.

Niveau pour les événements de trace¶

Vous pouvez gérer la verbosité des données d’événements de trace stockées dans la table des événements en définissant le niveau de trace. Avant de procéder au traçage, utilisez ce paramètre pour vous assurer que vous capturez bien la gravité du message. Si vous constatez que les données de l’événement ne sont pas écrites dans la table, vérifiez le niveau de trace pour vous assurer que Snowflake capture les données souhaitées.

Pour plus d’informations, voir Définition des niveaux de journalisation, des métriques et du traçage.

Langues acceptées¶

Vous pouvez tracer des événements de trace provenant du code écrit dans les langages suivants, y compris lorsque le code du gestionnaire (handler) est écrit avec des APIs Snowpark.

Langage / Type	Java	Python	JavaScript	Scala	Exécution de scripts Snowflake
Gestionnaire (handler) de procédure stockée	✔	✔	✔	✔	✔
Appli Streamlit		✔
Gestionnaire (handler) d’UDF (fonction scalaire)	✔	✔	✔	✔
Gestionnaire (handler) d’UDTF (fonction de table)	✔	✔	✔	✔ *

*:: Gestionnaire d’UDTF Scala écrit dans Snowpark.

Traçage des événements à partir du code du gestionnaire¶

Pour tracer les événements, vous pouvez utiliser une bibliothèque fournie par Snowflake et conçue pour le code du gestionnaire que vous utilisez. Snowflake intercepte les événements de trace et les stocke dans la table d’événements que vous avez créée.

Le tableau suivant répertorie les langages de gestionnaire pris en charge pour la journalisation, ainsi que des liens vers des informations sur la journalisation à partir du code.

Langage	Bibliothèque de télémétrie	Documentation
Java	Classe `Telemetry` Snowflake.	Émettre des événements de trace en Java
JavaScript	Snowflake JavaScriptAPI.	Émettre des événements de trace en JavaScript
Python	Paquet `telemetry` Snowflake.	Émettre des événements de trace en Python
Scala	Classe `Telemetry` Snowflake.	Émettre des événements de trace en Scala
Exécution de scripts Snowflake	Fonctions SQL Snowflake.	Émettre des événements de trace dans Snowflake Scripting

Lignes directrices générales pour l’ajout d’événements de trace¶

Lorsque vous appelez des APIs d’événement de trace pour ajouter des événements de trace et définir des attributs de span, notez ce qui suit :

Un span peut contenir un nombre maximal de 128 événements de trace et un nombre maximal de 128 attributs de span.
Si vous ajoutez un événement de trace qui porte le même nom qu’un événement que vous avez ajouté précédemment, un nouvel enregistrement d’événement est créé.
Si vous définissez un attribut de span ayant la même clé qu’un attribut de span défini précédemment, la valeur de cette clé est remplacée.

Affichage des données d’événements collectées¶

Vous pouvez afficher les données de trace via Snowsight ou en interrogeant la table d’événements dans laquelle les données de trace sont stockées. Pour plus d’informations, voir Affichage des données de trace.