Surveillance des événements pour Snowpipe¶

Vous pouvez configurer Snowflake pour qu’il enregistre des événements vous fournissant des informations détaillées sur l’état de vos canaux. Ces événements sont capturés dans le tableau des événements actif associé au canal.

En surveillant ces événements, vous pouvez obtenir des insights sur les éléments suivants :

Modifications de l’état du canal : Suivez l’état opérationnel de vos Snowpipes.
Progression du traitement des fichiers : Comprenez le parcours des fichiers dans le système Snowpipe.
Résumé périodique et agrégé des statistiques d’ingestion : Obtenez des statistiques synthétiques sur l’ingestion des données.

En outre, vous pouvez configurer des alertes pour les conditions critiques suivantes :

Volume élevé de fichiers entrants
Latences d’ingestion élevées
Erreurs de canal
Erreurs de fichier

The following sections explain how to enable event logging for Snowpipe, configure the severity level for log events, and interpret the events recorded in the event table:

Types d’événements Snowpipe : Découvrez les différentes catégories d’événements et leurs détails.
Définir le niveau de gravité des événements à capturer : Configurez les événements qui sont enregistrés en fonction de leur importance.
Interroger le tableau des événements pour les événements Snowpipe : Découvrez comment récupérer et analyser des données d’événements.
Informations enregistrées pour les événements Snowpipe : Comprenez la structure et la signification des données dans les colonnes du tableau des événements.

Prudence

La journalisation des événements pour Snowpipe entraîne des coûts. Pour plus d’informations, consultez Coûts de la collecte de données télémétriques.

Types d’événements Snowpipe¶

Les événements Snowpipe sont identifiés par l’attribut name dans la colonne RECORD de votre tableau des événements.

file_lifecycle¶

Les événements file_lifecycle suivent le parcours d’un fichier à travers le système Snowpipe. L’état d’un fichier peut être RECEIVED, INGESTED ou ERRORED.

RECEIVED : Un événement est émis lorsque Snowpipe reçoit une requête de fichier. Le canal peut ignorer ce fichier s’il a été traité précédemment ; dans ce cas, l’attribut skipped indique ceci.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "file_lifecycle",
    "severity_text": "DEBUG"
  },
  "RECORD_ATTRIBUTES": {
    "snow.file.path": "<a/path/to/a/file>"
  },
  "VALUE": {
    "notification_channel": "<notification_channel>",
    "file_content_key": "<file_content_key>",
    "last_modified_time": "<last_modified_time>",
    "state": "<received_or_skipped>"
  }
}

INGESTED : Un événement est émis une fois que le fichier a été correctement ingéré par Snowpipe.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "file_lifecycle",
    "severity_text": "DEBUG"
  },
  "RECORD_ATTRIBUTES": {
    "snow.file.path": "<a/path/to/a/file>"
  },
  "VALUE": {
    "notification_channel": "<notification_channel>",
    "file_content_key": "<file_content_key>",
    "state": "ingested"
  }
}

ERRORED : Un événement est émis si le fichier n’a pas pu être ingéré par Snowpipe.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "file_lifecycle",
    "severity_text": "ERROR"
  },
  "RECORD_ATTRIBUTES": {
    "snow.file.path": "<a/path/to/a/file>"
  },
  "VALUE": {
    "notification_channel": "<notification_channel>",
    "file_content_key": "<file_content_key>",
    "first_error_message": "<first_error_message>",
    "first_error_line_number": "<some_number>",
    "first_error_character_pos": "<some_character_pos>",
    "error_count": "<error_count>",
    "error_limit": "<error_limit>",
    "file_state": "FAILED"
  }
}

notification_received¶

Cet événement est émis lorsque Snowflake reçoit un message de notification.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "notification_channel_name": "<notification_channel_name>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "notification_received",
    "severity_text": "TRACE"
  },
  "VALUE": {
    "file_path": "<a/path/to/a/file>",
    "file_content_key": "<file_content_key>",
    "upstream_event_time": "<upstream_event_time>"
  }
}

notification_channel_errored¶

Cet événement est émis lorsqu’une erreur se produit pendant que Snowflake lit des messages dans un canal de notifications. Cela indique généralement une erreur de configuration de l’utilisateur, comme un problème d’autorisation.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "notification_channel_name": "<notification_channel_name>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "notification_channel_errored",
    "severity_text": "ERROR"
  },
  "VALUE": {
    "first_error_message": "<error_message>"
  }
}

pipe_lifecycle¶

Cet événement est émis lorsque l’état d’un canal change. Le nouvel état peut être RUNNING, PAUSED, STOPPED ou STALLED.

Pour les états de canal RUNNING ou PAUSED :

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "pipe_lifecycle",
    "severity_text": "INFO"
  },
  "VALUE": {
    "state": "<running_or_paused>"
  }
}

Pour les états de canal STOPPED_* ou STALLED_* : Ces états indiquent qu’un canal a arrêté de traiter des fichiers de manière inattendue.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "pipe_lifecycle",
    "severity_text": "<WARN_or_ERROR>"
  },
  "VALUE": {
    "state": "<pipe_status>",
    "error_message": "<error_message>"
  }
}

Le severity_text pour les états STOPPED_* ou STALLED_* dépend de la raison spécifique :

WARN si le canal s’est arrêté pour les raisons suivantes :

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

ERROR si le canal s’est arrêté pour les raisons suivantes :

STOPPED_STAGE_ALTERED
STOPPED_STAGE_DROPPED
STOPPED_FILE_FORMAT_DROPPED
STOPPED_NOTIFICATION_INTEGRATION_DROPPED
STOPPED_MISSING_PIPE
STOPPED_MISSING_TABLE
STALLED_COMPILATION_ERROR
STALLED_INITIALIZATION_ERROR
STALLED_EXECUTION_ERROR
STALLED_INTERNAL_ERROR
STALLED_STAGE_PERMISSION_ERROR

pipe_throttled¶

Cet événement est émis si un Snowpipe est limité.

{
  "TIMESTAMP": "<some_timestamp>",
  "RESOURCE_ATTRIBUTES": {
    "snow.database.name": "<MY_DB_NAME>",
    "snow.schema.name": "<MY_SCHEMA_NAME>",
    "snow.pipe.name": "<MY_PIPE_NAME>"
  },
  "RECORD_TYPE": "EVENT",
  "RECORD": {
    "name": "pipe_throttled",
    "severity_text": "WARN"
  },
  "VALUE": {
    "throttled_files": "<throttled_file_name_list>"
  }
}

Définir le niveau de gravité des événements à capturer¶

To enable Snowpipe events to be recorded in an event table, you must set the LOG_EVENT_LEVEL parameter at either the pipe level or the account level. LOG_EVENT_LEVEL determines which log events are captured based on their severity. For more information, see Paramètres and New LOG_EVENT_LEVEL parameter to control events.

ERROR : Utilisé pour les événements qui signalent un changement nécessitant une intervention humaine pour être résolus.
WARN : Utilisé pour les événements qui signalent un problème pouvant être résolus sans intervention humaine.
INFO : Utilisé pour les événements initiés par l’utilisateur qui sont généralement utiles et qui ne sont pas des événements de grand volume.
DEBUG : Utilisé pour les événements de grand volume.
TRACE : Le plus bas niveau de journalisation, qui capture des informations très détaillées.

Prudence

Si le niveau de gravité n’est pas défini au niveau du compte ou au niveau du canal, aucun événement n’est capturé.

Exemples :

Pour capturer les événements de niveau ERROR pour tous les objets d’un compte, exécutez le code suivant :

ALTER ACCOUNT <my_account_name> SET LOG_EVENT_LEVEL = ERROR;

Pour capturer les événements de niveau INFO pour un canal spécifique, exécutez le code suivant :

ALTER PIPE <my_pipe_name> SET LOG_EVENT_LEVEL = INFO;

Severity level for each event type¶

The following table summarizes the default or recommended severity for each Snowpipe event type when you use LOG_EVENT_LEVEL:


Événement	Severity
file_lifecycle - RECEIVED, INGESTED	DEBUG
file_lifecycle - ERRORED	ERROR
notification_received	TRACE
notification_channel_errored	ERROR
pipe_lifecycle - RUNNING, PAUSED	INFO
pipe_lifecycle - STOPPED	WARN ou ERROR (voir la rubrique suivante)
pipe_throttled	WARN

pipe_lifecycle - STOPPED severity details:

WARN si le canal s’est arrêté pour les raisons suivantes :

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

ERROR si le canal s’est arrêté pour les raisons suivantes :

STOPPED_STAGE_ALTERED
STOPPED_STAGE_DROPPED
STOPPED_FILE_FORMAT_DROPPED
STOPPED_NOTIFICATION_INTEGRATION_DROPPED
STOPPED_MISSING_PIPE
STOPPED_MISSING_TABLE
STALLED_COMPILATION_ERROR
STALLED_INITIALIZATION_ERROR
STALLED_EXECUTION_ERROR
STALLED_INTERNAL_ERROR
STALLED_STAGE_PERMISSION_ERROR

Interroger le tableau des événements pour les événements Snowpipe¶

Avant d’effectuer une requête, assurez-vous d’avoir configuré un tableau des événements et défini le niveau de gravité que vous souhaitez pour les événements à capturer.

L’exemple de requête suivant montre comment récupérer des événements Snowpipe, tels que ceux générés lors de l’ingestion de fichiers :

SELECT
    record_type,
    record:"name" AS event_name,
    record:"severity_text" AS log_level,
    resource_attributes:"snow.database.name" AS database_name,
    resource_attributes:"snow.schema.name" AS schema_name,
    resource_attributes:"snow.pipe.name" AS pipe_name,
    record_attributes,
    PARSE_JSON(value):file_content_key AS file_content_key,
    PARSE_JSON(value):state AS state
FROM {my_event_table_name}
ORDER BY state;

Exemple de sortie (ingestion de fichiers réussie) :

La sortie suivante montre à la fois les événements RECEIVED et INGESTED pour un fichier, qui indique un traitement réussi :


SCOPE	RECORD_TYPE	EVENT_NAME	LOG_LEVEL	DATABASE_NAME	SCHEMA_NAME	PIPE_NAME	RECORD_ATTRIBUTES	FILE_CONTENT_KEY	STATE
[NULL]	EVENT	« file_lifecycle »	« DEBUG »	« TESTDB »	« TESTSH »	« MYPIPE »	{ « snow.file.path »: « data_0_0_0.event » }	« ba1f2511fc30423bdbb183fe33f3dd0f »	« INGESTED »
[NULL]	EVENT	« file_lifecycle »	« DEBUG »	« TESTDB »	« TESTSH »	« MYPIPE »	{ « snow.file.path »: « data_0_0_0.event » }	« ba1f2511fc30423bdbb183fe33f3dd0f »	« RECEIVED »

Informations enregistrées pour les événements Snowpipe¶

Les sections suivantes décrivent les colonnes clés et leur contenu dans le tableau des événements Snowpipe. Si une colonne n’est pas explicitement répertoriée dans les sections suivantes, sa valeur est NULL pour les événements Snowpipe.

Valeurs des colonnes de la table des événements¶


Colonne	Type de données	Description
horodatage	TIMESTAMP_NTZ	Horodatage UTC de la création de l’événement.
resource_attributes	OBJECT	Attributs qui identifient l’événement Snowpipe, tels que les noms de la base de données, du schéma et du canal.
record_type	STRING	Type d’événement enregistré. Pour les événements Snowpipe, cette valeur est toujours EVENT.
record	OBJECT	Contient des informations détaillées sur l’état d’exécution de l’événement Snowpipe, y compris le nom et le texte de gravité.
value	VARIANT	Informations complémentaires spécifiques à l’événement Snowpipe. Si la tâche Snowpipe a échoué, cela inclut le message d’erreur.

Paires clé-valeur dans la colonne resource_attributes¶

La colonne resource_attributes contient une valeur OBJECT avec les paires clé-valeur suivantes :


Nom d’attribut	Type d’attribut	Description	Exemple
snow.database.name	VARCHAR	Nom de la base de données associée au canal.	« MY_DATABASE »
snow.schema.name	VARCHAR	Nom du schéma associé au canal.	« MY_SCHEMA_NAME »
snow.schema.name	VARCHAR	Nom du canal.	« MY_PIPE_NAME »
notification_channel_name	VARCHAR	Nom du canal de notifications qui a reçu le message ou qui a rencontré une erreur.	« arn:aws:sqs:us-west-2:774383465531:sf-snowpipe-AIDA3 »

Paires clé-valeur dans la colonne d’enregistrements¶

La colonne record contient une valeur OBJECT avec les paires clé-valeur suivantes :


Clé	Type	Description	Exemple
name	VARCHAR	Nom de l’événement.	« pipe_lifecycle »
severity_text	VARCHAR	Niveau de gravité de l’événement.	« INFO »