É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.

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 Configuration d’une table d’événement.

Vous pouvez accéder aux données des événements de trace en exécutant une commande SELECT sur la table des événements. Pour plus d’informations, reportez-vous à Accès aux données de trace.

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.8
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 qu’il autorise les données souhaitées.

Pour plus d’informations, reportez-vous à Réglage du niveau de trace.

Langues acceptées¶

Vous pouvez tracer les événements provenant du code du gestionnaire de fonction et de procédure écrit dans les langages suivants, y compris lorsque le code du gestionnaire est écrit avec des APIs Snowpark.

Langage / Type	Java	Python	JavaScript	Scala	Exécution de scripts Snowflake
Procédures stockées	✔	✔	✔	✔	✔
UDFs scalaires	✔	✔	✔	✔
UDTFs	✔	✔	✔	✔ *

*:: 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 Exécution de scripts Snowflake

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.

Accès aux données d’événements¶

Vous pouvez accéder à ces données d’événement en exécutant une commande SELECT sur la table des événements. Pour plus d’informations, reportez-vous à Accès aux données de trace.