Configuration de la journalisation et du partage d’événements pour une application

Cette rubrique décrit comment configurer la journalisation et le partage d’événements pour dépanner une application installée.

Cette rubrique fournit des informations sur la configuration de la journalisation et du partage d’événements en tant que fournisseur. Reportez-vous à Activation de la journalisation et du partage d’événements pour une application pour connaître les exigences des consommateurs en matière de configuration de cette fonction.

Les événements de journalisation et de traçage vous permettent de collecter des informations sur une application afin de résoudre les erreurs. Grâce à la journalisation et aux événements de traçage, vous pouvez également avoir une meilleure idée du fonctionnement de votre application et l’améliorer par la suite.

Workflow de configuration de la journalisation et du partage d’événements en tant que fournisseur

En tant que fournisseur, vous pouvez configurer la journalisation et le partage d’événements pour une application en procédant comme suit :

  1. Passez en revue les considérations relatives à l’utilisation de la journalisation et du partage d’événements.

  2. Configurez la journalisation et les événements de traçage pour les fonctions et les procédures stockées.

  3. Définissez le niveau de journalisation et de traçage dans le fichier manifeste.

  4. Configurez un compte pour stocker les événements partagés.

Une fois que le consommateur a installé une application et activé la journalisation et le partage d’événements, vous pouvez voir les informations de journalisation et d’événements partagées par l’application installée :

Considérations relatives à l’utilisation de la journalisation et du partage d’événements

Avant d’utiliser la journalisation et le partage d’événements pour une application, vous devez tenir compte des points suivants :

  • Vous êtes responsable de tous les coûts associés au partage d’événements du côté du fournisseur, y compris l’ingestion et le stockage des données.

  • Vous devez avoir un compte pour stocker des événements partagés dans chaque région où vous souhaitez prendre en charge le partage d’événements.

  • Vous devez définir le niveau de journalisation et le niveau de traçage par défaut pour une application dans le fichier manifeste.

Configurer la journalisation et des événements de trace dans les fonctions et les procédures

Le Native Apps Framework nécessite une table d’événements pour stocker les messages de journal et les événements de traçage générés par les fonctions et les procédures stockées dans une application.

Note

Si le consommateur de votre application ne configure pas une table d’événements et n’en fait pas la table active avant d’installer l’application, les données d’événements et de journalisation sont rejetées.

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 pour un compte Snowflake à la fois. Sans table d’événements active, les messages de journal et les événements de traçage générés 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 d’événements de journalisation et de traçage.

Pour créer une table d’événements, utilisez la commande CREATE EVENT TABLE. Pour plus d’informations, reportez-vous à Configuration d’une table d’événement.

Une fois que le code a enregistré les messages du journal et les événements de traçage, vous pouvez interroger les données enregistrées.

Pour plus d’informations sur l’enregistrement et l’interrogation des données de journal et de traçage, reportez-vous à ce qui suit :

Définir le niveau de journalisation et de traçage dans le fichier manifeste

Pour définir les niveaux de journalisation et de traçage par défaut pour une version d’une application, définissez les paramètres log_level et trace_level dans le fichier manifeste, comme indiqué dans l’exemple suivant :

artifacts:
  setup_script: setup.sql
configuration:
  trace_level: OFF
  log_level: DEBUG
Copy

Lorsqu’un fournisseur active le traçage, une Snowflake Native App capture automatiquement les heures de début et de fin de toutes les requêtes et de tous les appels de procédures stockées.

Note

La publication d’une Snowflake Native App dont la propriété trace_level est définie sur une valeur autre que OFF peut exposer les appels à des procédures stockées cachées à tout utilisateur du compte du consommateur qui peut voir la table des événements.

Reportez-vous à Réglage du niveau de trace et Réglage du niveau de journalisation pour obtenir des informations sur les valeurs prises en charge pour trace_level et log_level.

Lors de son installation initiale, l”Snowflake Native App utilise les niveaux de journalisation définis dans le fichier manifeste. Si le niveau de journalisation est modifié lors d’une mise à niveau ultérieure, le nouveau niveau de journalisation prend effet après la fin du processus de mise à niveau.

Le niveau de journalisation et de traçage ne peut être défini que dans le fichier manifeste. Le consommateur n’est pas autorisé à modifier le niveau de journalisation à l’aide des commandes ALTER APPLICATION ou ALTER DATABASE.

De même, tout paramètre de niveau de session pour le niveau de journalisation est ignoré par l’application.

Configurer un compte pour stocker les événements partagés

Pour stocker les journaux et les événements partagés, vous devez sélectionner un compte qui contiendra une table d’événements. Il peut s’agir de n’importe quel compte auquel un fournisseur peut accéder. Toutefois, si votre organisation compte plusieurs fournisseurs publiant des paquets d’applications, envisagez d’utiliser un compte Snowflake dédié au stockage des événements partagés du consommateur.

Les restrictions suivantes s’appliquent au compte des événements partagés :

  • Vous devez utiliser le rôle ORGADMIN pour définir un compte comme compte d’événements.

  • Le compte doit avoir une table d’événements actifs.

  • Le compte spécifié ne peut pas être :

    • Un compte bloqué ou suspendu.

    • Un compte de lecteurs.

    • Un compte d’essai.

    • Un compte géré par Snowflake.

Note

Vous ne pouvez collecter des journaux et des événements partagés que dans la région où un consommateur installe une application. Par conséquent, vous devez configurer un compte pour stocker les événements partagés dans chaque région où les consommateurs configurent le partage d’événements pour une application.

Définir un compte comme compte d’événements

Pour faire d’un compte le compte d’événements d’une région, appelez la fonction système SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION :

CALL SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

Où :

snowflake_region

Nom de la région où se trouve le compte, par exemple AWS_US_WEST_2, AWS_US_EAST_1.

region_group

Spécifie le groupe de régions, par exemple : PUBLIC. Reportez-vous à Groupes de régions pour plus de détails.

account_name

Spécifie le nom du compte. Si un autre compte est déjà défini comme compte d’événements dans la région spécifiée, l’exécution de cette commande remplace le compte d’événements par le compte spécifié ici.

Définir un compte comme compte d’événements

Pour annuler la désignation d’un compte comme compte d’événements pour une région, appelez la fonction système SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION :

CALL SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

Où :

snowflake_region

Nom de la région où se trouve le compte, par exemple AWS_US_WEST_2, AWS_US_EAST_1.

region_group

Spécifie le groupe de régions, par exemple : PUBLIC.

account_name

Spécifie le nom du compte.

Afficher des comptes d’événements dans l’organisation du fournisseur

Pour afficher les comptes d’événements dans l’organisation d’un fournisseur, appelez la fonction système SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS :

CALL SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS()
Copy

Note

Vous devez utiliser le rôle ORGADMIN pour appeler cette fonction.

Cette fonction système renvoie une chaîne au format JSON contenant une liste des comptes d’événements de l’organisation. Étant donné que les métadonnées mettent un certain temps à se propager dans toutes les régions, cette fonction peut accuser un certain retard lorsqu’elle affiche le dernier compte d’événements, après que l’utilisateur a défini un compte d’événements pour l’organisation ou annulé sa désignation en tant que telle.

Voir les niveaux d’événements de journalisation et de trace définis dans un paquet d’application

Utilisez la commande DESCRIBE APPLICATION pour afficher le niveau de journalisation d’une application installée, comme le montre la commande suivante :

DESC APPLICATION HelloSnowflake;
Copy

Utilisez la commande SHOW VERSIONS pour voir le niveau de journalisation des versions d’application définies dans un paquet d’application, comme le montre l’exemple suivant :

SHOW VERSIONS
  IN APPLICATION PACKAGE HelloSnowflake;
Copy

Voir les journaux et les événements dans la table d’événements

Pour voir les journaux et les événements stockés dans la table des événements, utilisez la commande SELECT comme indiqué dans l’exemple suivant :

SELECT * FROM EVENT_DB.EVENT_SCHEMA.MY_EVENT_TABLE
Copy

Informations sur les événements partagés disponibles par le fournisseur

Les sections suivantes décrivent les informations que le Native Apps Framework partage avec les fournisseurs.

Contexte de l’événement de l’application partagé avec le fournisseur

Pour aider les fournisseurs à identifier facilement la source des événements partagés, les champs suivants sont remplis dans la colonne RESOURCE_ATTRIBUTES de la table des événements lorsqu’ils sont partagés avec le fournisseur :

  • snow.application.package.name

  • snow.application.consumer.organization

  • snow.application.consumer.name

  • snow.listing.name

  • snow.listing.global_name

Champs non partagés avec le fournisseur

Afin de protéger les informations relatives au consommateur, les champs suivants de la colonne RESOURCE_ATTRIBUTES ne sont pas partagés avec le fournisseur :

  • snow.database.id

  • snow.database.name

  • snow.schema.id

  • snow.executable.id

  • snow.owner.name

  • snow.owner.id

  • snow.warehouse.name

  • snow.warehouse.id

  • snow.query.id

  • snow.session.id

  • snow.session.role.primary.name

  • snow.session.role.primary.id

  • snow.user.name

  • snow.user.id

  • db.user

Au lieu de partager directement les champs snow.database.name et snow.query.id avec le fournisseur, Snowflake partage les valeurs de hachage (SHA-1) de ces deux champs dans les champs suivants :

  • snow.database.hash

  • snow.query.hash

Snowflake fournit la fonction SHA-1 utilisée pour masquer ces attributs. Les consommateurs peuvent calculer les valeurs de hachage pour le nom de la base de données et l’identifiant de la requête, et les utiliser comme valeurs de référence lorsqu’ils contactent le fournisseur.