Configurer les définitions d’événements pour une application¶

Cette rubrique décrit comment définir des définitions d’événements dans le fichier manifeste d’une application. Les définitions d’événements définissent les messages de journal et les événements de trace partagés avec un fournisseur.

À 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 d’application ou un nouveau correctif est publié.

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é.

Les définitions d’événements sont facultatives. Si un fournisseur ne spécifie pas de définitions d’événements pour une application, les consommateurs peuvent uniquement activer ou désactiver le partage d’événements pour tous les événements lorsque le fournisseur active le traçage des événements.

Prudence

Les définitions d’événements diffèrent des 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. Si ni les niveaux de journalisation ni de traçage ne sont définis, l’application n’émet aucun événement.

Les niveaux de journalisation et de trace d’une application peuvent changer en fonction des définitions d’événements activées par le consommateur. Snowflake utilise les niveaux de journalisation et de trace les plus détaillés autorisés par les définitions d’événements que le consommateur a activées.

Définitions d’événements obligatoires et facultatifs¶

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.

Après avoir installé une application avec les définitions d’événements requises, les consommateurs ne peuvent pas désactiver le partage d’événements ou les définitions d’événements requises. Lorsqu’une application est mise à niveau, les fournisseurs peuvent utiliser les fonctions système ou le Python Permission SDK pour vérifier si le consommateur a activé toutes les définitions d’événements requises.
Les définitions d’événements facultatives peuvent être activées ou désactivées par le consommateur selon les besoins.

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’)`
Metrics	SNOWFLAKE$METRICS	Permettez aux consommateurs de partager des données avec les fournisseurs.	`RECORD_TYPE in (‘METRIC’)`

Note

Snowsight affiche uniquement tous les événements de type All au consommateur si le fournisseur n’a pas configuré l’application pour utiliser les définitions d’événements.

Limitations des définitions d’événements dans les applications avec conteneurs¶

Snowflake Native Apps with Snowpark Container Services ne prend actuellement en charge que la définition de l’événement ALL. La prise en charge de définitions d’événements supplémentaires sera ajoutée dans une future version.

Définir les niveaux de journalisation et de trace pour une application¶

Pour permettre à une application d’utiliser le traçage des événements, un fournisseur doit configurer les niveaux de journalisation et de trace dans le fichier manifeste.

Pour définir les niveaux de journalisation et de trace d’une application, ajoutez un bloc configuration dans le fichier manifest.yml comme indiqué dans l’exemple suivant :

configuration:
  ...
  log_level: INFO
  trace_level: ALWAYS
  metric_level: ALL
  ...

Copy

Cet exemple définit les niveaux de journalisation et de trace pour l’application comme suit :

La propriété log_level est définie sur INFO.
La propriété trace_level est définie sur ALWAYS.
La propriété metric_level est définie sur ALL.

Voir LOG_LEVEL, TRACE_LEVEL et METRIC_LEVEL pour obtenir des informations sur les valeurs valides pour ces paramètres.

Prudence

Une fois que vous avez publié une application, les niveaux de journalisation et de trace ne peuvent pas être modifiés. Si les niveaux de journalisation et de trace ne sont pas définis dans le fichier manifeste, l’application n’émet aucune information.

Lorsque les niveaux de journalisation et de trace sont définis pour une application, les consommateurs doivent configurer une table d’événements dans leur compte pour voir les messages de journal et les événements de trace émis par l’application.

Pour permettre au fournisseur de voir les messages de journal et de suivre les événements générés par une application, les consommateurs doivent activer le partage d’événements. Voir Activer le partage d’événements pour une application pour plus d’informations.

Ajouter une définition d’événement au fichier manifeste¶

Pour spécifier une définition d’événement, un fournisseur ajoute une entrée au bloc configuration.telemetry_event_definitions du fichier manifeste comme indiqué dans l’exemple suivant :

configuration:
  telemetry_event_definitions:
    - type: ERRORS_AND_WARNINGS
      sharing: MANDATORY
    - type: DEBUG_LOGS
      sharing: OPTIONAL

Copy

Cet exemple spécifie les définitions d’événements suivantes :

Une définition d’événement obligatoire avec le type ERRORS_AND_WARNINGS.
Une définition d’événement facultative avec le type DEBUG_LOGS.

Voir Définitions d’événements prises en charge pour plus d’informations.

Une fois qu’un consommateur installe une application, les définitions d’événements apparaissent dans l’onglet Events and logs sur la page Security de l’application. Voir Activer la journalisation et le partage d’événements pour une application pour plus d’informations.

Définir les niveaux de journalisation, de trace et de métrique pour des objets spécifiques¶

Les fournisseurs peuvent affiner les niveaux de journalisation, de trace et de métrique pour des objets spécifiques au sein d’une application. Les fournisseurs ont ainsi plus de contrôle sur les données de télémétrie émises par l’application.

Les fournisseurs peuvent définir les niveaux de journalisation, de trace et de métrique pour les objets suivants au sein d’une application :

Schémas
Schémas versionnés
Procédures stockées
Fonctions définies par l’utilisateur

La table suivante répertorie les commandes SQL utilisées pour définir les niveaux de journalisation, de trace et d’événement pour ces objets :

Objet	Commande
Schémas	ALTER SCHEMA
Schéma versionné	CREATE OR ALTER VERSIONED SCHEMA
Procédures stockées	ALTER PROCEDURE
Fonctions définies par l’utilisateur	ALTER FUNCTION

Pour les schémas, les procédures stockées et les fonctions définies par l’utilisateur, les fournisseurs peuvent utiliser la clause SET des commandes ALTER pour définir les propriétés suivantes :

LOG_LEVEL
TRACE_LEVEL
METRIC_LEVEL

Pour les schémas versionnés, les fournisseurs peuvent définir ces propriétés à l’aide de CREATE OR ALTER VERSIONED SCHEMA dans le script d’installation.

Ordre de priorité pour les niveaux de journalisation, de trace et de métrique¶

Dans une application, les niveaux de journalisation, de trace et de métrique peuvent être configurés de différentes manières pour les composants de l’application. Pour déterminer les événements qui sont émis, le Snowflake Native App Framework utilise l’ordre de priorité suivant :

Procédures stockées et fonctions définies par l’utilisateur

Si un remplacement est défini pour la procédure stockée ou la fonction définie par l’utilisateur spécifique, il est prioritaire.
Schémas et schémas de version

Si aucun remplacement n’est défini pour les procédures stockées ou les fonctions définies par l’utilisateur, les remplacements pour les schémas et les schémas versionnés sont prioritaires.
Paramètres au niveau de l’application

Si aucun remplacement au niveau de l’objet n’est trouvé, la configuration de télémétrie au niveau de l’application, généralement définie dans le fichier manifest, est utilisée.