Émettre des événements de trace en Python

Vous pouvez utiliser le paquet telemetry Snowflake pour émettre des événements de trace à partir d’une fonction ou d’un gestionnaire de procédure écrit en Python. Le paquet est disponible sur la chaîne Anaconda Snowflake.

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, reportez-vous à Accès aux données de trace.

Note

Pour les lignes directrices à garder à l’esprit lors de l’ajout d’événements de trace, se référer à Lignes directrices générales pour l’ajout d’événements de trace.

Pour des informations générales sur la configuration de la journalisation et la récupération des messages dans Snowflake, reportez-vous à Enregistrement de messages à partir de fonctions et de procédures.

Avant de journaliser à partir d’un code, vous devez :

  • Mettre en place une table d’événements pour collecter les messages enregistrés par le code du gestionnaire.

    Pour plus d’informations, reportez-vous à Configuration d’une table d’événement.

  • 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, reportez-vous à Réglage du niveau de trace.

Note

Pour les lignes directrices à garder à l’esprit lors de l’ajout d’événements de trace, se référer à Lignes directrices générales pour l’ajout d’événements de trace.

Ajout d’une prise en charge du paquet de télémétrie

Pour utiliser le paquet de télémétrie, vous devez mettre le paquet de télémétrie Snowflake open source, qui est inclus dans Snowflake, à la disposition de votre code de gestionnaire. Le paquet est disponible sur la chaîne Anaconda Snowflake.

  • Dans la clause PACKAGES de votre instruction CREATE PROCEDURE ou CREATE FUNCTION, incluez le paquet snowflake-telemetry-python. La clause PACKAGES met le paquet de télémétrie Snowflake inclus à la disposition de votre code.

    Le code de l’exemple suivant utilise la clause PACKAGES pour référencer le paquet de télémétrie ainsi que la bibliothèque Snowpark (qui est nécessaire pour les procédures stockées écrites en Python - pour plus d’informations, voir Écriture de procédures stockées en Python).

    CREATE OR REPLACE FUNCTION my_function(...)
      RETURNS ...
      LANGUAGE PYTHON
      ...
      PACKAGES = ('snowflake-telemetry-python')
      ...
    
    Copy
  • Importez le paquet telemetry dans le code de votre gestionnaire.

    from snowflake import telemetry
    
    Copy

Ajout d’événements de trace

Vous pouvez ajouter des événements de trace en appelant la méthode telemetry.add_event et en indiquant le nom de l’événement. Il est également possible d’associer des attributs (paires clé-valeur) à un événement.

La méthode add_event est disponible sous la forme suivante :

telemetry.add_event(<name>, <attributes>)
Copy

où :

  • name est une chaîne Python qui spécifie le nom de l’événement de trace.

  • attributes est un objet Attributs OpenTelemetry qui spécifie les attributs de cet événement de trace. Cet argument est facultatif. Omettez l’argument si vous n’avez pas d’attributs à spécifier pour cet événement de trace.

Le code du gestionnaire de l’exemple suivant ajoute deux événements, FunctionEmptyEvent et FunctionEventWithAttributes. Avec FunctionEventWithAttributes, le code ajoute également deux attributs : key1 et key2.

telemetry.add_event("FunctionEmptyEvent")
telemetry.add_event("FunctionEventWithAttributes", {"key1": "value1", "key2": "value2"})
Copy

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": "FunctionEmptyEvent"
}
Copy
{
  "name": "FunctionEventWithAttributes"
}
Copy

La ligne d’événement FunctionEventWithAttributes comprend les attributs suivants dans la colonne RECORD_ATTRIBUTES de la ligne :

{
  "key1": "value1",
  "key2": "value2"
}
Copy

Ajout d’attributs de span

Vous pouvez définir des attributs (paires clé-valeur) associés aux spans en appelant la méthode telemetry.set_span_attribute.

Pour plus de détails sur les spans, voir Comment Snowflake représente les événements de trace.

La méthode set_span_attribute est disponible sous la forme suivante :

telemetry.set_span_attribute(<key>, <value>)
Copy

où :

  • key est une chaîne Python qui spécifie la clé d’un attribut.

  • value est un objet OpenTelemetry AttributeValue qui spécifie la valeur de l’attribut.

Le code de l’exemple suivant crée quatre attributs et définit leurs valeurs :

// Setting span attributes.
telemetry.set_span_attribute("example.boolean", true);
telemetry.set_span_attribute("example.long", 2);
telemetry.set_span_attribute("example.double", 2.5);
telemetry.set_span_attribute("example.string", "testAttribute");
Copy

La définition de ces attributs se traduit par les éléments suivants dans la colonne RECORD_ATTRIBUTES de la table des événements :

{
  "example.boolean": true,
  "example.long": 2,
  "example.double": 2.5,
  "example.string": "testAttribute"
}
Copy

Exemples Python

Les sections suivantes fournissent des exemples d’ajout d’événements de trace dans les procédures stockées et les fonctions de Python.

Exemple de procédure stockée

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

Exemple UDF

CREATE OR REPLACE FUNCTION times_two(x number)
RETURNS NUMBER
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION=3.8
HANDLER = 'times_two'
AS $$
from snowflake import telemetry
def times_two(x):
  telemetry.set_span_attribute("example.func.times_two", "begin")
  telemetry.add_event("event_without_attributes")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})

  response = 2 * x

  telemetry.set_span_attribute("example.func.times_two.response", response)

  return response
$$;
Copy

Lorsque vous appelez l’API d’événement de trace à partir d’une fonction Python qui traite une ligne d’entrée, l’API sera appelée pour chaque ligne traitée par l’UDF.

Par exemple, l’instruction suivante appelle la fonction Python définie dans l’exemple précédent pour 50 lignes, ce qui produit 100 événements de trace (deux pour chaque ligne) :

select count(times_two(seq8())) from table(generator(rowcount => 50));
Copy

Exemple UDTF

CREATE OR REPLACE FUNCTION digits_of_number(input number)
RETURNS TABLE(result number)
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION=3.8
HANDLER = 'TableFunctionHandler'
AS $$
from snowflake import telemetry

class TableFunctionHandler:

  def __init__(self):
    telemetry.add_event("test_udtf_init")

  def process(self, input):
    telemetry.add_event("test_udtf_process", {"input": str(input)})
    response = input

    while input > 0:
      response = input % 10
      input /= 10
      yield (response,)

  def end_partition(self):
    telemetry.add_event("test_udtf_end_partition")
$$;
Copy

Lorsque vous appelez l’API d’événement de trace dans la méthode process() d’une classe de gestionnaire d’une UDTF, l’API d’événement sera appelée pour chaque ligne traitée.

Par exemple, l’instruction suivante appelle la méthode process() définie dans l’exemple précédent pour 50 lignes, ce qui entraîne l’ajout de 100 événements de trace (deux pour chaque ligne) par la méthode process() :

select * from table(generator(rowcount => 50)), table(digits_of_number(seq8())) order by 1;
Copy