Ajout de spans personnalisés à une trace

Vous pouvez ajouter vos propres spans personnalisés aux traces pour un traçage plus précis dans le gestionnaire d’une procédure ou d’une fonction.

Par défaut, lorsque vous avez le traçage activé, Snowflake démarre un span pour vous (comme décrit dans Comment Snowflake représente les événements de trace) et ajoute tous les événements de trace à ce span. (Ceci est connu en interne sous le nom de span « auto_instrumenté ».) En utilisant des APIs OpenTelemetry, vous pouvez créer vos propres spans. Dans le nouveau span, vous pouvez ajouter des événements et des attributs à l’aide de l’API OpenTelemetry ou de l’API Snowflake pour votre langage.

Vous souhaiterez peut-être créer votre propre span lorsque, par exemple, vous souhaitez isoler les données de trace pour les actions nécessitant beaucoup de calculs qui se produisent dans une procédure, par exemple lorsque vous utilisez le code pour entraîner un modèle de ML.

Les spans personnalisés que vous créez correspondent au comportement par défaut des spans créés par OpenTelemetry.

Langues acceptées

Vous pouvez ajouter des spans personnalisés 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

[1]

Appli Streamlit

Gestionnaire (handler) d’UDF (fonction scalaire)

[1]

Gestionnaire (handler) d’UDTF (fonction de table)

[1] [2]

Création d’un span personnalisé

Pour ajouter un span personnalisé avec un code de gestionnaire, utilisez l’API OpenTelemetry pour votre langage de gestionnaire dans l’environnement de télémétrie Snowflake existant pour créer un nouveau span, ajouter des événements et des attributs selon les besoins, puis fermer le span.

  1. Utilisez l’API OpenTelemetry pour créer un traceur pour gérer le contexte du span.

    À partir de ce traceur créé à partir de l’environnement de télémétrie Snowflake existant, vous pouvez créer des spans personnalisés qui utilisent l’infrastructure existante dans laquelle les données de trace sont capturées par la table d’événements.

  2. À partir du nouveau traceur, créez le span personnalisé avec une API ce qui garantit que le nouveau span est le span actuel.

    En créant le nouveau span dans le contexte existant géré par Snowflake, vous garantissez que les informations de contexte — y compris les valeurs trace_id et parent_span_id — soient transmises du span par défaut de Snowflake à d’autres spans.

  3. Lorsque votre code se termine avec le span personnalisé, il doit fermer le span avant que le gestionnaire ne termine l’exécution pour que les données de trace soient capturées par la table d’événements.

    Ce comportement des spans personnalisés correspond au comportement par défaut de OpenTelemetry.

Pour plus d’informations sur l’ajout d’un span personnalisé avec un langage pris en charge, consultez les rubriques suivantes :

Exemple Python

Le code dans l’exemple suivant utilise l” API OpenTelemetry Python pour créer le span my.span comme le span actuel avec start_as_current_span. Il ajoute ensuite un événement avec des attributs au nouveau span à l’aide de l’API `OpenTelemetry Python`_.

Les données d’événement ne seront pas capturées par la table d’événements à moins que le span ne se termine avant que votre gestionnaire ne termine l’exécution. Dans cet exemple, la fermeture du span se produit automatiquement lorsque l’instruction with se conclut.

CREATE OR REPLACE FUNCTION customSpansPythonExample() RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.9
PACKAGES = ('snowflake-telemetry-python', 'opentelemetry-api')
HANDLER = 'custom_spans_function'
AS $$
from snowflake import telemetry
from opentelemetry import trace

def custom_spans_function():
  tracer = trace.get_tracer("my.tracer")
  with tracer.start_as_current_span("my.span") as span:
    span.add_event("Event2 in custom span", {"key1": "value1", "key2": "value2"})

  return "success"
$$;
Copy