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

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

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

  3. Ajoutez le code de trace de l’événement à votre gestionnaire.

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