Configurer le traçage des événements pour une application

Cette rubrique décrit comment configurer le traçage des événements pour capturer les messages de journal et les événements de trace émis par une application. Elle décrit également comment activer le partage d’événements pour partager des messages de journal et des événements de trace avec des fournisseurs.

À propos du traçage des événements dans le Snowflake Native App Framework

Le traçage d’événements permet à une application d’émettre des informations liées à ses performances et à son comportement. Le Snowflake Native App Framework prend en charge l’utilisation de la fonctionnalité de la journalisation et du traçage de Snowflake afin de recueillir ces informations. Une application peut émettre les éléments suivants :

  • Les messages de journal sont des messages indépendants et détaillés contenant des informations sur l’état d’une fonctionnalité spécifique de l’application.

  • Les événements de trace contiennent des données structurées que vous pouvez utiliser pour obtenir des informations couvrant et regroupant plusieurs parties d’une application.

Voir les messages de journal et les événements d’une application

Pour voir les messages de journal et les événements de trace émis par l’application, les consommateurs doivent configurer une table d’événements dans leur compte pour collecter ces informations. Consultez Configurer une table d’événements pour plus d’informations.

À propos du partage d’événements

Les consommateurs peuvent également activer le partage d’événements pour partager des données d’événements avec les fournisseurs. Lorsqu’un fournisseur active le partage d’événements, les messages de journal et les événements de trace insérés dans la table d’événements du compte consommateur sont également insérés dans une table d’événements du compte fournisseur.

Le partage d’événements permet au fournisseur de collecter des informations sur les performances et le comportement de l’application. Consultez À propos du partage d’événements pour une application pour plus d’informations.

À propos des définitions d’événements

Les définitions d’événements spécifient comment une application partage les messages de journal et les événements de trace avec le fournisseur. Les définitions d’événements agissent comme des filtres sur les niveaux de messages de journal et d’événements de trace définis par le fournisseur. Un fournisseur spécifie les définitions d’événements pour une application lorsqu’une nouvelle version ou un nouveau correctif est publié.

Note

Les définitions d’événements ne sont pas obligatoires. Si un fournisseur ne spécifie pas de définitions d’événements pour une application, les consommateurs peuvent activer ou désactiver le partage d’événements selon les besoins.

Les fournisseurs peuvent définir une définition d’événement comme étant obligatoire ou facultative :

  • Les définitions d’événements obligatoires sont activées automatiquement lors de l’installation de l’application. Pour collecter les définitions d’événements émises par une application, un consommateur doit créer une table d’événements et la définir comme table d’événements active pour son compte.

  • Les définitions d’événements facultatives peuvent être activées ou désactivées par le consommateur selon les besoins. Les définitions d’événements facultatives nécessitent une table d’événements active, mais elles ne sont pas nécessaires pour installer ou utiliser l’application.

Prudence

Les définitions d’événements ne sont pas les mêmes que les niveaux de journalisation et de traçage définis par le fournisseur. Les niveaux de journalisation et de traçage déterminent les informations insérées dans la table des événements du consommateur.

Les définitions d’événements sont des filtres qui agissent sur les messages de journal et les événements de trace. Ils déterminent quelles informations sont insérées dans la table des événements du fournisseur lorsque le partage d’événements est activé.

Définitions d’événements prises en charge

Le tableau suivant répertorie les définitions d’événements actuellement prises en charge :

Type

Nom

Description

Filtre

All

SNOWFLAKE$ALL

Partage tous les messages de journal et les événements de trace que l’application émet.

*

Errors and warnings

SNOWFLAKE$ERRORS_AND_WARNINGS

Partage les journaux liés aux erreurs, aux avertissements et aux événements fatals.

RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)

Traces

SNOWFLAKE$TRACES

Partage des traces détaillées des activités et des parcours des utilisateurs dans l’application.

RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)

Usage logs

SNOWFLAKE$USAGE_LOGS

Partage les journaux de haut niveau liés aux actions des utilisateurs et aux événements d’application.

RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’

Debug logs

SNOWFLAKE$DEBUG_LOGS

Partage les journaux techniques utilisés pour dépanner l’application.

RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)

Note

Si un fournisseur ne configure pas l’application pour utiliser les définitions d’événements, Snowsight affiche uniquement le type All.

Considérations pour les consommateurs lors de l’utilisation de définitions d’événements

Les consommateurs peuvent continuer à utiliser la propriété SHARE_EVENTS_WITH_PROVIDER existante, mais il existe des limites :

  • Si une application utilise uniquement la définition OPTIONAL ALL de l’événement, définir la propriété SHARE_EVENTS_WITH_PROVIDER sur true permet le partage d’événements et la définir sur false désactive le partage d’événements.

    Ceci est applicable lorsqu’un fournisseur ajoute explicitement la définition OPTIONAL ALL de l’événement au fichier manifeste ou lorsqu’une application a été migrée à partir de la fonctionnalité de partage d’événements existante.

  • Si un fournisseur ajoute des définitions d’événements obligatoires et facultatives au fichier manifeste, définir la propriété SHARE_EVENTS_WITH_PROVIDER sur true active toutes les définitions d’événements. En revanche, la propriété SHARE_EVENTS_WITH_PROVIDER ne peut être définie que sur false si le fournisseur ajoute uniquement des définitions d’événements facultatives.

    SHARE_EVENTS_WITH_PROVIDER est TRUE uniquement lorsque toutes les définitions d’événements sont activées, sinon c’est FALSE.

Flux de travail pour configurer le traçage des événements pour une application

Le flux de travail suivant décrit comment configurer le traçage des événements pour une application :

  1. Passer en revue les considérations relatives à l’utilisation de la journalisation et du traçage d’événements.

  2. Mettez en place une table d’événements

  3. Voir les niveaux de journalisation et de traçage d’événements configurés pour l’application.

  4. Affichez les événements dans la table des événements.

  5. Activer le partage d’événements sur une application.

Points à prendre en considération lors de l’utilisation du traçage d’événements

Avant de configurer le traçage des événements pour une application, vous devez prendre en compte les éléments suivants :

  • Cette fonction nécessite que vous configuriez une table d’événements dans votre compte.

  • Après avoir activé le partage d’événements, une copie masquée et expurgée des événements de trace et des messages de journaux est automatiquement insérée dans la table des événements du compte fournisseur désigné.

  • Snowflake ne vous facture pas l’activation du partage d’événements. Cependant, vous êtes responsable du coût d’ingestion des événements de trace et des messages de journal dans la table d’événements, ainsi que des coûts de stockage de la table d’événements.

  • Après avoir activé le partage d’événements avec un fournisseur, vous ne pouvez pas révoquer l’accès aux événements de trace partagés et aux messages de journal.

  • Vous ne pouvez pas partager d’événements historiques à l’aide du partage d’événements.

  • Snowflake envoie les événements partagés à un compte fournisseur désigné dans la même région que votre compte. Cette fonction ne partage pas de données entre différentes régions.

  • Vous ne pouvez pas modifier les niveaux de journalisation ou de traçage d’une application, car c’est le fournisseur qui les définit. Le fournisseur de l’application définit ces niveaux lors de la publication de l’application.

  • Snowflake recommande de vérifier les événements de trace et les messages de journal dans la table des événements avant d’activer le partage d’événements.

  • Snowflake recommande de désactiver la journalisation et le partage d’événements si vous n’avez pas besoin de dépanner l’application.

Configuration d’une table d’événements

Pour collecter les messages de journal et les événements de trace émis par l’application, les consommateurs doivent créer une table d’événements pour stocker les informations.

Note

IF le consommateur ne configure pas de table d’événements et ne la définit pas comme une table d’événements active avant d’installer l’application, les données d’événements de trace et de journal sont supprimées.

Si un fournisseur inclut les définitions d’événements requises dans l’application, elles sont activées par défaut lors de l’installation. Cependant, si le consommateur ne dispose pas d’une table d’événements active, les messages de journal et les événements de trace émis par l’application sont ignorés.

Un compte peut avoir plusieurs tables d’événements, mais une seule d’entre elles peut être définie comme table d’événements active dans un compte Snowflake à la fois. Sans table d’événements active, les messages de journal et les événements de trace émis par l’application ne sont pas capturés. Cela est vrai même si les fonctions et procédures d’une application appellent les APIs de journalisation et d’événements de trace.

Pour créer une table d’événements, exécutez la commande CREATEEVENT TABLE, comme indiqué dans l’exemple suivant :

CREATE EVENT TABLE event_db.event_schema.my_event_table;
Copy

Notez que cette commande spécifie la base de données et le schéma qui contiennent la table des événements.

Après avoir créé la table d’événements, utilisez la commande ALTER ACCOUNT pour spécifier que la table d’événements est la table active pour le compte :

ALTER ACCOUNT SET EVENT_TABLE=event_db.event_schema.my_event_table;
Copy

Activer le partage d’événements pour une application

Le Snowflake Native App Framework prend en charge le partage des messages de journal et des événements de trace stockés dans la table des événements du consommateur avec le fournisseur d’applications. Pour partager les journaux et les informations sur les événements avec un fournisseur, le client doit activer le partage d’événements pour une application.

Conditions préalables pour activer le partage d’événements pour une application

Les conditions suivantes doivent être remplies pour activer le partage d’événements pour une instance d’application :

Activer le partage d’événements à l’aide de Snowsight

Note

Si le fournisseur inclut les définitions d’événements requises dans l’application, le partage d’événements et les définitions d’événements requises sont activés lors de l’installation et ne peuvent pas être désactivés ultérieurement.

Pour activer le partage d’événements pour une application :

  1. Connectez-vous à Snowsight.

  2. Dans le menu de navigation, sélectionnez Data Products » Apps.

  3. Sélectionnez l’application.

  4. Sélectionnez l’icône Security dans la barre d’outils.

  5. Sélectionnez l’onglet Events and logs.

  6. Sous la zone Events and logs sharing, sélectionnez Enable

  7. Si le fournisseur a défini des définitions d’événements pour l’application :

    1. Utilisez le curseur pour activer les définitions d’événements facultatives.

    2. Sélectionnez Review.

  8. Si aucune table d’événements n’est actuellement sélectionnée, sélectionnez la table d’événements dans la liste sous Event table location.

    Prudence

    Soyez prudent(e) lorsque vous modifiez la table d’événements dans Snowsight. Chaque compte Snowflake utilise une seule table d’événements pour tous les événements générés au sein du compte. La modification de la table d’événements entraîne le stockage au nouvel emplacement de tous les événements générés dans le compte.

Activer le partage d’événements en utilisant SQL

Pour activer le partage d’événements pour une application en utilisant SQL :

  1. Utilisez la commande SHOW TELEMETRY EVENT DEFINITIONS pour déterminer les définitions d’événements pour l’application :

    SHOW TELEMETRY EVENT DEFINITIONS IN APPLICATION hello_snowflake;
    Copy

    Si le fournisseur n’a pas configuré l’application pour utiliser les définitions d’événements, la colonne type affiche ALL. Sinon, cette commande répertorie les définitions d’événements facultatives spécifiées pour l’application.

  2. Si l’application contient les définitions d’événements requises, utilisez la commande ALTER APPLICATION pour les activer :

    ALTER APPLICATION hello_snowflake SET AUTHORIZE_TELEMETRY_EVENT_SHARING=true
    Copy

    Cette commande active toutes les définitions d’événements requises, mais n’active pas les définitions d’événements facultatives.

    Note

    Après avoir activé les définitions d’événements requises pour une application, le partage d’événements ne peut pas être désactivé.

  3. Si l’application contient des définitions d’événements d’options, utilisez l’option ALTER APPLICATION pour les activer comme indiqué dans l’exemple suivant :

    ALTER APPLICATION hello_snowflake SET SHARED TELEMETRY EVENTS ('SNOWFLAKE$TRACES', 'SNOWFLAKE$DEBUG_LOGS');
    Copy

    Cet exemple active le SNOWFLAKE$TRACES et SNOWFLAKE$DEBUG_LOGS basé en fonction du résultat de la commande SHOW TELEMETRY EVENT DEFINITIONS.

  4. Pour vérifier que le traçage et la journalisation des événements sont activés, utilisez la commande DESC APPLICATION :

    DESC APPLICATION hello_snowflake;
    Copy

    Les lignes authorize_telemetry_event_sharing et share_events_with_provider de la sortie indiquent si le partage d’événements est activé.

Activer le partage d’événements à l’aide de SQL (ancienne fonctionnalité)

Prudence

La méthode permettant de partager des événements à l’aide de SQL décrite dans cette section sera obsolète dans une future version. Snowflake recommande d’utiliser la méthode décrite dans Activer le partage des journaux et des événements à l’aide de SQL pour activer le partage d’événements à l’aide de SQL.

Pour activer le partage d’événements pour une application, exécutez la commande ALTER APPLICATION pour définir SHARE_EVENTS_WITH_PROVIDER sur TRUE. Par exemple :

ALTER APPLICATION HelloSnowflake SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
Copy

Pour afficher le statut de partage des événements d’une application, utilisez la commande DESC APPLICATION comme indiqué dans l’exemple suivant :

DESC APPLICATION HelloSnowflake;
Copy

SHARE_EVENTS_WITH_PROVIDER indique le statut du partage d’événements pour l’application.

Activer les définitions d’événements lors des mises à niveau

Lors des mises à niveau, les définitions d’événements se comportent comme suit :

Modification de la définition de l’événement

Comportement lors de la mise à niveau

Aucune modification à la définition d’un événement

La définition de l’événement conserve le même statut que la version ou le correctif précédent.

Une nouvelle définition d’événement

Non activé automatiquement. Ceci est vrai pour les définitions d’événements obligatoires et facultatives. Le consommateur doit activer manuellement les nouvelles définitions d’événements.

Passage d’obligatoire à facultatif ou de facultatif à obligatoire

La définition de l’événement conserve le même statut que la version ou le correctif précédent.

Définition d’événement supprimée

Le partage d’événements s’arrête après la mise à niveau des messages de journal ou du filtre d’événements de trace dans la version ou le correctif précédent.

Lors de la mise à niveau, les consommateurs sont invités à vérifier les modifications apportées aux définitions d’événements par rapport au correctif ou à la version précédente.

Voir les messages de journal et les événements de trace dans la table d’événements

WHen une table d’événements est activée, les consommateurs peuvent interroger la table d’événements pour voir les messages de journal et les événements de trace émis par l’application. Utilisez la commande SELECT pour effectuer une requête sur la table des événements, par exemple :

SELECT * FROM event_db.event_schema.my_event_table;
Copy

Cette commande renvoie tous les messages de journal et les événements de trace stockés dans la table des événements.

Déterminer si un message de journal ou un événement de trace est partagé avec le fournisseur

Les RECORD_ATTRIBUTES de la colonne contient le champ snow.application.shared. Si la valeur de ce champ est TRUE, le message de journal ou l’événement de trace est partagé avec le fournisseur. Dans le cas contraire, le message de journal ou l’événement n’est pas partagé.

Voir les niveaux de journal et de trace pour une application

Le niveau de journal et de trace d’une application est défini par le fournisseur avant la publication d’une application. Les consommateurs ne peuvent pas modifier les niveaux de journal et de trace d’une application.

Cependant, avant de configurer le traçage des événements ou d’activer le partage d’événements pour une application, Snowflake recommande de vérifier le niveau de journal pour comprendre le type d’informations collectées et partagées avec le fournisseur.

Pour voir le niveau de journal et de trace d’une application, exécutez la commande suivante :

DESC APPLICATION HelloSnowflake;
Copy

Cette commande affiche des informations sur l’application HelloSnowflake, y compris les informations suivantes sur le niveau de journal et de trace défini pour l’application :

  • log_level : Le niveau de journal défini par le fournisseur dans le fichier manifeste.

  • trace_level : Le niveau de trace défini par le fournisseur dans le fichier manifeste.

  • effective_log_level : le niveau de journal activé pour l’application.

  • effective_trace_level : le niveau de trace activé pour l’application.

Les niveaux de journal et de trace efficaces sont déterminés par les définitions d’événements que le consommateur active pour l’application.

Par exemple, si le fournisseur définit le niveau de journal comme OFF, mais que le consommateur active la définition de l’événement ERROR_AND_WARNING, l’application modifie dynamiquement le niveau de journal en WARN de sorte que les événements ERROR_AND_WARNING puissent être collectés. L’application émet des événements qui sont moins ou tout aussi verbeux que WARN et partage ces événements d’erreur et d’avertissement avec le fournisseur. Les valeurs de log_level seraient OFF et la valeur de effective_log_level serait WARN.

En revanche, si le fournisseur définit le niveau de journal comme TRACE, mais que le consommateur active la définition de l’événement ERROR_AND_WARNING, l’application émet des événements qui sont moins ou aussi verbeux que trace, mais seuls les messages d’erreur et d’avertissement sont partagés avec le fournisseur. La valeur de log_level et effective_log_level serait TRACE.

Langage: Français