Émettre des événements de trace en Python¶

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>)

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"})

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"
}

{
  "name": "FunctionEventWithAttributes"
}

La ligne d’événement FunctionEventWithAttributes 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 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>)

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");

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"
}

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.

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"
$$;

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
$$;

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

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")
$$;

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