Tutoriel : Démarrer avec la journalisation et le traçage¶

Introduction¶

Ce tutoriel présente les bases de l’émission, de la collecte et de l’interrogation des données de journal et de trace à partir du code du gestionnaire de fonction et de procédure.

Le tutoriel utilise l’interface Web Snowsight, mais vous pouvez utiliser n’importe quel client Snowflake qui prend en charge le SQL d’exécution. Pour plus d’informations sur Snowsight, voir Premiers pas avec les feuilles de calcul et Utilisation de feuilles de calcul dans Snowsight.

Configuration de la base de données, de l’entrepôt et de l’accès¶

Dans cette section, vous allez créer un entrepôt et une base de données dont vous aurez besoin pour le tutoriel. Vous commencerez également à utiliser le rôle ACCOUNTADMIN, qui est nécessaire pour exécuter certaines des instructions de ce tutoriel.

Vous créez une base de données dans laquelle vous créerez ultérieurement la table des événements et la fonction définie par l’utilisateur. Vous pouvez supprimer tous les objets que vous avez créés dans le tutoriel, y compris la base de données et l’entrepôt, lorsque vous n’en avez plus besoin.

Pour créer une base de données et un entrepôt à utiliser dans le tutoriel :

1. Connectez-vous à Snowsight.

2. Passez au rôle ACCOUNTADMIN.

3. Ouvrez Projects » Worksheets.

4. Sélectionnez + » SQL Worksheet.

5. Renommez la nouvelle feuille de calcul en Logging-tracing tutorial.

6. Dans la nouvelle feuille de calcul, collez et exécutez l’instruction suivante pour créer une base de données. La nouvelle base de données n’est destinée qu’à ce tutoriel.

   CREATE OR REPLACE DATABASE tutorial_log_trace_db;
   

   Copy

7. Collez et exécutez l’instruction suivante pour créer un entrepôt. Le nouvel entrepôt n’est destiné qu’à ce tutoriel.

   CREATE OR REPLACE WAREHOUSE tutorial_log_trace_wh
     WAREHOUSE_TYPE = STANDARD
     WAREHOUSE_SIZE = XSMALL;
   

   Copy

Dans cette section, vous mettez en place les éléments dont vous avez besoin pour le tutoriel. Dans la section suivante, vous allez créer une table d’événements pour stocker les données d’enregistrement et de suivi.

Créer une table d’événements¶

Dans cette section, vous allez créer une table d’événements. Lorsque le code de votre gestionnaire émet des messages de journal et des données de trace, Snowflake enregistre les données émises dans les lignes de la table d’événements. Vous pouvez interroger la table des événements pour analyser les données.

Vous devez créer une table d’événements pour collecter les données du journal et de la trace. Une table d’événements utilise toujours la structure prédéfinie définie par Snowflake.

Pour créer la table d’événements, vous devez utiliser un rôle avec le privilège CREATE EVENT TABLE attribué.

Pour créer la table d’événements et en faire la table d’événements active pour le compte :

1. Collez et exécutez l’instruction suivante pour créer une table d’événements.

   CREATE OR REPLACE EVENT TABLE tutorial_event_table;
   

   Copy

   C’est dans cette table que Snowflake stocke les journaux et les données de trace.

2. Collez et exécutez l’instruction suivante pour modifier le compte de sorte que la table d’événements que vous avez créée soit active pour le compte.

   USE ROLE ACCOUNTADMIN;
   
   ALTER ACCOUNT SET EVENT_TABLE = tutorial_log_trace_db.public.tutorial_event_table;
   

   Copy

   Cette instruction définit la nouvelle table d’événements comme la table que Snowflake doit utiliser pour stocker les messages de journal et les données de trace des gestionnaires du compte courant. Vous ne pouvez avoir qu’une seule table d’événements active pour un compte.

Dans cette section, vous avez créé une table d’événements. Dans la section suivante, vous commencerez à émettre des messages de journal que Snowflake stockera dans la table.

Émettre des messages de journal¶

Dans cette section, vous allez créer une fonction définie par l’utilisateur (UDF) avec un code de gestionnaire Python qui émet des messages de journalisation. Lorsque votre code émet des messages de journal, Snowflake collecte les données du message et les stocke dans la table d’événements que vous avez créée.

Snowflake prend en charge les APIs pour enregistrer les messages de chaque langage de gestionnaire pris en charge. Pour les gestionnaires que vous écrivez en Python, vous pouvez utiliser le module logging de la bibliothèque standard de Python.

Pour créer une UDF qui émet des messages de journal :

1. Collez et exécutez l’instruction suivante pour définir le niveau de journalisation sur INFO.

   ALTER SESSION SET LOG_LEVEL = INFO;
   

   Copy

   Ceci spécifie la sévérité des messages de journalisation que Snowflake doit capturer lors de l’exécution de l’UDF. Dans ce cas, le niveau autorise tous les messages, de l’informatif (INFO) au plus grave (FATAL).

2. Collez et exécutez l’instruction suivante pour créer une fonction définie par l’utilisateur.

   CREATE OR REPLACE FUNCTION log_trace_data()
   RETURNS VARCHAR
   LANGUAGE PYTHON
   RUNTIME_VERSION = 3.9
   HANDLER = 'run'
   AS $$
   import logging
   logger = logging.getLogger("tutorial_logger")
   
   def run():
     logger.info("Logging from Python function.")
     return "SUCCESS"
   $$;
   

   Copy

   Les lignes surlignées dans le code effectuent les opérations suivantes :

   • Importez le module Python logging pour que le code du gestionnaire puisse l’utiliser.

   • Créez un enregistreur, qui expose l’interface que votre code utilisera pour enregistrer les messages.

   • Enregistrez un message au niveau INFO.

3. Collez et exécutez l’instruction suivante pour exécuter la fonction que vous venez de créer.

   SELECT log_trace_data();
   

   Copy

   Ceci produit la sortie suivante. En outre, lorsque la fonction s’exécute, elle émet un message de journal que Snowflake collecte dans la table d’événements.

   --------------------
   | LOG_TRACE_DATA() |
   --------------------
   | SUCCESS          |
   --------------------
   

Dans cette section, vous avez émis un message de journal à partir d’une UDF. Dans la section suivante, vous interrogerez la table d’événements pour récupérer les données relatives au message.

Interroger des messages du journal¶

Dans cette section, vous allez interroger la table des événements pour connaître les données des messages de journal émis par l’UDF que vous avez exécutée dans la section précédente.

Snowflake utilise les colonnes de la table d’événements prédéfinies pour collecter et stocker les données de journalisation et de trace des types suivants :

• Données émises par le code du gestionnaire, telles que les messages de journal et les données d’événements de trace.

  Vous les trouverez dans des colonnes telles que RECORD_TYPE, RECORD, RECORD_ATTRIBUTES, etc.

• Données sur le contexte dans lequel les données du journal ou de la trace ont été émises, telles que l’horodatage, le nom de la méthode de gestionnaire à partir de laquelle les données ont été émises, etc.

  Vous trouverez ces données dans des colonnes telles que RESOURCE_ATTRIBUTES, TIMESTAMP et SCOPE.

Pour interroger la table d’événements afin d’obtenir des données sur les messages du journal :

1. Collez et exécutez l’instruction suivante pour interroger la table d’événements.

   SELECT
     TIMESTAMP AS time,
     RESOURCE_ATTRIBUTES['snow.executable.name'] as executable,
     RECORD['severity_text'] AS severity,
     VALUE AS message
   FROM
     tutorial_log_trace_db.public.tutorial_event_table
   WHERE
     RECORD_TYPE = 'LOG'
     AND SCOPE['name'] = 'tutorial_logger';
   

   Copy

   Certaines colonnes contiennent des données structurées exprimées sous forme de paires clé-valeur. Dans cette requête, vous spécifiez les clés d’attribut dans une colonne en utilisant la notation par crochets comme RECORD['severity_text'].

   Vous utilisez également la notation entre crochets (SCOPE['name']) pour spécifier que vous souhaitez sélectionner les valeurs des colonnes uniquement lorsque les entrées de journal sont émises avec l’enregistreur Python, tutorial_logger, que vous avez créé dans le code du gestionnaire.

2. Afficher la sortie.

   -----------------------------------------------------------------------------------------------------------
   | TIME                | EXECUTABLE                           | SEVERITY | MESSAGE                         |
   -----------------------------------------------------------------------------------------------------------
   | 2023-04-19 22:00:49 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "INFO"   | "Logging from Python function." |
   -----------------------------------------------------------------------------------------------------------
   

   La sortie illustre la façon dont les colonnes prédéfinies de la table d’événement contiennent chacune des parties des données collectées. Pour les valeurs EXECUTABLE et SEVERITY, vous avez utilisé la notation entre crochets pour spécifier les attributs dont vous voulez les valeurs.

   Colonne de sortie	Description
   TIME	L’heure à laquelle l’entrée a été créée (à partir de la colonne TIMESTAMP).
   EXECUTABLE	Nom de l’UDF et les paramètres (de l’attribut snow.executable.name de la colonne RESOURCE_ATTRIBUTES).
   SEVERITY	Gravité de l’entrée de journal (à partir de l’attribut RECORD de la colonne severity_text).
   MESSAGE	Message du journal (de la colonne VALUE).

Dans cette section, vous avez utilisé une instruction SELECT pour interroger des données de journalisation. Dans la section suivante, vous mettrez à jour l’UDF pour qu’elle émette des données de trace.

Émettre de données de trace¶

Dans cette section, vous mettrez à jour le code du gestionnaire de l’UDF afin qu’il émette également des données de trace. Lorsque votre code émet des données de trace, Snowflake collecte les données et les stocke dans la table d’événements que vous avez créée.

Les données de trace présentent des qualités structurelles, notamment des données d’événements regroupées en spans et des données capturées sous forme de paires clé-valeur, qui vous permettent de dresser un tableau plus détaillé de l’activité de votre code que ne le permettent généralement les données de journalisation.

Snowflake prend en charge des APIs pour émettre des données de trace à partir de chaque langage de gestionnaire pris en charge. Pour les gestionnaires que vous écrivez en Python, vous pouvez utiliser le paquet telemetry Snowflake.

Pour mettre à jour l’UDF afin d’émettre des données de trace :

1. Collez et exécutez l’instruction suivante pour spécifier les données de trace à capturer.

   ALTER SESSION SET TRACE_LEVEL = ON_EVENT;
   

   Copy

   Cette opération définit le niveau de trace sur ON_EVENT. Ceci spécifie que seules les données de trace émises explicitement par votre propre code doivent être capturées.

2. Collez et exécutez l’instruction suivante pour créer une UDF qui émet des données de trace.

   CREATE OR REPLACE FUNCTION log_trace_data()
   RETURNS VARCHAR
   LANGUAGE PYTHON
   PACKAGES = ('snowflake-telemetry-python')
   RUNTIME_VERSION = 3.9
   HANDLER = 'run'
   AS $$
   import logging
   logger = logging.getLogger("tutorial_logger")
   from snowflake import telemetry
   
   def run():
     telemetry.set_span_attribute("example.proc.run", "begin")
     telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
     logger.info("Logging from Python function.")
     return "SUCCESS"
   $$;
   

   Copy

   En exécutant ce code, vous remplacez la fonction que vous avez créée précédemment par une fonction qui ajoute du code pour l’émission de données de trace. Les lignes surlignées effectuent les opérations suivantes :

   • Ajouter snowflake-telemetry-python – qui contient le paquet telemetry – à l’environnement d’exécution de l’UDF.

   • Importer le paquet telemetry pour pouvoir appeler ses fonctions.

   • Définir un attribut et une valeur d’attribut au span que Snowflake crée lorsque le code s’exécute.

     Un span représente l’unité d’exécution d’une procédure ou d’une UDF, à l’intérieur de laquelle vous pouvez ajouter plusieurs événements.

   • Ajouter un événement (avec ses propres attributs) à enregistrer dans le cadre du span.

3. Collez et exécutez l’instruction suivante pour exécuter la fonction que vous venez de créer.

   SELECT log_trace_data();
   

   Copy

   Ceci produit la sortie suivante. En outre, lorsque la fonction s’exécute, elle émet des données de trace que Snowflake collecte dans la table d’événements.

   --------------------
   | LOG_TRACE_DATA() |
   --------------------
   | SUCCESS          |
   --------------------
   

Dans cette section, vous avez émis des données de trace à partir d’une UDF. Dans la section suivante, vous interrogerez la table d’événements pour récupérer les données relatives à la trace.

Interroger des messages de trace¶

Dans cette section, vous allez interroger la table d’événements pour obtenir des données de trace émises par l’UDF que vous avez exécutée dans la section précédente.

La requête que vous écrivez permet de récupérer des informations contextuelles sur les événements émis par la fonction. Ce contexte inclut le nom de la fonction qui l’a émis.

Pour rechercher des données de trace dans la table des événements :

1. Collez et exécutez l’instruction suivante pour interroger la table d’événements des données de trace.

   SELECT
     TIMESTAMP AS time,
     RESOURCE_ATTRIBUTES['snow.executable.name'] AS handler_name,
     RECORD['name'] AS event_name,
     RECORD_ATTRIBUTES AS attributes
   FROM
     tutorial_log_trace_db.public.tutorial_event_table
   WHERE
     RECORD_TYPE = 'SPAN_EVENT'
     AND HANDLER_NAME LIKE 'LOG_TRACE_DATA%';
   

   Copy

   Certaines colonnes contiennent des données structurées exprimées sous forme de paires clé-valeur. Pour ces dernières, vous pouvez sélectionner les valeurs d’attribut dans une colonne en utilisant la notation par crochets, comme le montre le code.

2. Afficher la sortie.

   -----------------------------------------------------------------------------------------------------------------------------------------------------
   | TIME                    | HANDLER_NAME                         | EVENT_NAME              | ATTRIBUTES                                             |
   -----------------------------------------------------------------------------------------------------------------------------------------------------
   | 2023-05-10 20:49:35.080 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "event_with_attributes" | { "example.key1": "value1", "example.key2": "value2" } |
   -----------------------------------------------------------------------------------------------------------------------------------------------------
   

   La sortie illustre la façon dont les colonnes prédéfinies de la table d’événement contiennent chacune des parties des données collectées. Pour les valeurs EXECUTABLE et SEVERITY, vous avez utilisé la notation entre crochets pour spécifier l’attribut dont vous voulez la valeur.

   Colonne de sortie	Description
   TIME	Heure de création de l’entrée (à partir de la colonne TIMESTAMP).
   HANDLER_NAME	Nom de l’UDF et les paramètres (de l’attribut snow.executable.name de la colonne RESOURCE_ATTRIBUTES).
   EVENT_NAME	Nom de l’événement ajouté avec la fonction add_event (à partir de l’attribut name de la colonne RECORD).
   ATTRIBUTES	Attributs ajoutés pour accompagner l’événement (à partir de la colonne RECORD_ATTRIBUTES).

Dans cette section, vous avez interrogé la table des événements pour obtenir des données de trace émises par l’UDF que vous avez écrite. Dans la dernière section, vous trouverez des liens vers des informations relatives à ce que vous avez fait pendant le tutoriel.

En savoir plus¶

Vous avez terminé ! C’est bien fait.

Dans ce tutoriel, vous avez obtenu une vue d’ensemble de la façon dont vous pouvez émettre et stocker des données de journal et de trace à partir du code du gestionnaire, puis interroger les données stockées. En cours de route, vous :

• Avez créé une table d’événements. Pour plus d’informations sur les tables d’événements, voir ce qui suit :

  • Pour plus de détails sur la mise en place d’une table d’événements, voir Aperçu de la table d’événements.

  • Pour des informations de référence sur les colonnes qui composent une table d’événements, voir Colonnes de table d’événements.

  • Pour en savoir plus sur les possibilités offertes par les tables d’événements, voir Utilisation des tables d’événements.

• Avez créé une fonction définie par l’utilisateur (UDF) qui émet des données de journal et de trace. Pour des informations connexes, consultez les rubriques suivantes :

  • Pour une vue d’ensemble de la prise en charge de la journalisation dans Snowflake, voir Enregistrement de messages à partir de fonctions et de procédures. Pour plus d’informations sur la journalisation avec Python, voir Enregistrement de messages à partir de fonctions et de procédures et le module de journalisation de la bibliothèque standard de Python.

  • Pour plus de détails sur la définition des niveaux, voir Définition des niveaux de journalisation, des métriques et du traçage.

  • Pour une vue d’ensemble de la prise en charge du traçage, voir Événements de trace pour les fonctions et les procédures. Pour plus d’informations sur le traçage avec Python, voir Émettre des événements de trace en Python.

  • Pour des informations générales sur la création d’UDFs, voir Vue d’ensemble des fonctions définies par l’utilisateur.

• Interrogation de la table des événements pour les données de journalisation et de trace. Pour plus d’informations sur les tables d’événements, reportez-vous à ce qui suit :

  • Pour une vue plus complète de la manière d’interroger les données du journal, voir Affichage des messages de journalisation.

  • Pour savoir comment interroger des données de trace, voir Affichage des données de trace.

  • Pour plus d’informations sur les spans et les événements, ainsi que sur la manière dont Snowflake stocke les données les concernant, voir Comment Snowflake représente les événements de trace.