Überwachen von Ereignissen für Snowpipe¶

Sie können Snowflake so konfigurieren, dass es Ereignisse aufzeichnet, die detaillierte Informationen über den Status Ihrer Pipes liefern. Diese Ereignisse werden in der der Pipe zugeordneten aktiven Ereignistabelle erfasst.

Durch die Überwachung dieser Ereignisse können Sie Einblicke in die folgenden Bereiche gewinnen:

Änderungen des Pipestatus: Verfolgen des Betriebszustands Ihrer Snowpipes.
Fortschritt der Dateiverarbeitung: Verstehen der Bewegung von Dateien durch das Snowpipe-System.
Periodischer, aggregierter Datenerfassungsstatistik-Digest: Abrufen zusammengefasster Statistiken zur Datenerfassung.

Außerdem können Sie Alerts für die folgenden kritischen Bedingungen konfigurieren:

Hohes Volumen an eingehenden Dateien
Hohe Datenerfassungslatenzen
Pipe-Fehler
Dateifehler

In den folgenden Abschnitten wird erläutert, wie Sie die Ereignisprotokollierung für Snowpipe aktivieren, den Protokolliergrad konfigurieren und die in der Ereignistabelle erfassten Ereignisse interpretieren:

Typen von Snowpipe-Ereignissen: Erfahren Sie mehr über die verschiedenen Kategorien von Ereignissen und deren Details.
Legen Sie den Schweregrad der zu erfassenden Ereignisse fest: Konfigurieren der Ereignisse, die nach ihrer Bedeutung erfasst werden.
Fragen Sie die Ereignistabelle nach Snowpipe-Ereignissen ab: Erfahren Sie, wie Sie Ereignisdaten abrufen und analysieren können.
Protokollierte Informationen zu Snowpipe-Ereignissen: Verstehen Sie die Struktur und Bedeutung der Daten in den Spalten der Ereignistabelle.

Vorsicht

Das Protokollieren von Ereignissen für Snowpipe verursacht Kosten. Weitere Informationen dazu finden Sie unter Kosten der Telemetriedatenerfassung.

Snowpipe-Ereignistypen¶

Snowpipe-Ereignisse werden durch das name-Attribut in der RECORD-Spalte Ihrer Ereignistabelle identifiziert.

file_lifecycle¶

file_lifecycle-Ereignisse verfolgen die Bewegungen einer Datei durch das Snowpipe-System. Der Status einer Datei kann RECEIVED, INGESTED``oder ``ERRORED lauten.

RECEIVED: Ein Ereignis wird ausgegeben, wenn Snowpipe eine Dateianforderung erhält. Die Pipe überspringt diese Datei möglicherweise, wenn sie zuvor verarbeitet wurde. In solchen Fällen gibt das skipped-Attribut dies an.

{
  "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>"
  }
}

Copy

INGESTED: Ein Ereignis wird ausgegeben, nachdem die Datei erfolgreich von Snowpipe erfasst wurde.

{
  "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"
  }
}

Copy

ERRORED: Ein Ereignis wird ausgegeben, wenn die Datei nicht von Snowpipe erfasst werden konnte.

{
  "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"
  }
}

Copy

notification_received¶

Dieses Ereignis wird ausgegeben, wenn Snowflake eine Benachrichtigungsmeldung erhält.

{
  "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>"
  }
}

Copy

notification_channel_errored¶

Dieses Ereignis wird ausgegeben, wenn ein Fehler auftritt, während Snowflake Nachrichten aus einem Benachrichtigungskanal liest. Dies deutet i. d. R. auf einen Fehler in der Benutzerkonfiguration hin, z. B. auf ein Problem mit der Autorisierung.

{
  "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>"
  }
}

Copy

pipe_lifecycle¶

Dieses Ereignis wird ausgegeben, wenn sich der Status einer Pipe ändert. Der neue Status kann RUNNING, PAUSED, STOPPED oder STALLED lauten.

Für den Pipe-Status RUNNING oder 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>"
  }
}

Copy

Für den Pipe-Status STOPPED_* oder STALLED_*: Diese Status zeigen an, dass eine Pipe die Verarbeitung von Dateien unerwartet eingestellt hat.

{
  "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>"
  }
}

Copy

Der severity_text für die Status STOPPED_* oder STALLED_* hängt von einem bestimmten Grund ab:

WARN, wenn die Pipe aus den folgenden Gründen angehalten wurde:

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

ERROR, wenn die Pipe aus den folgenden Gründen angehalten wurde:

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¶

Dieses Ereignis wird ausgegeben, wenn eine Snowpipe gedrosselt wird.

{
  "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>"
  }
}

Copy

Den Schweregrad der zu erfassenden Ereignisse festlegen¶

Damit Snowpipe-Ereignisse in einer Ereignistabelle erfasst werden können, müssen Sie den LOG_LEVEL-Parameter entweder auf Pipe-Ebene oder auf Kontoebene festlegen. Der LOG_LEVEL bestimmt, welche Ereignisse anhand ihres Schweregrads erfasst werden:

ERROR: Verwenden Sie dies für Ereignisse, die auf eine Änderung hinweisen, die menschliches Eingreifen erfordert.
WARN: Verwenden Sie dies für Ereignisse, die auf ein Problem hinweisen, das ohne menschlichen Eingriff gelöst werden kann.
INFO: Verwenden Sie dies für von Benutzenden initiierte Ereignisse, die allgemein nützlich sind und keine hochvolumigen Ereignisse sind.
DEBUG: Verwenden Sie dies für Ereignisse mit hohem Volumen.
TRACE: Die niedrigste Protokollierstufe, die sehr detaillierte Informationen erfasst.

Vorsicht

Wenn der Schweregrad nicht auf Konto- oder Pipe-Ebene festgelegt ist, werden keine Ereignisse erfasst.

Beispiele:

Um Ereignisse auf ERROR-Ebene für alle Objekte in einem Konto zu erfassen, führen Sie den folgenden Code aus:

ALTER ACCOUNT <my_account_name> SET LOG_LEVEL = ERROR;

Copy

Um Ereignisse auf INFO-Ebene für eine bestimmte Pipe zu erfassen, führen Sie den folgenden Code aus:

ALTER PIPE <my_pipe_name> SET LOG_LEVEL = INFO;

Copy

Protokolliergrad für jeden Ereignistyp¶

In der folgenden Tabelle werden der standardmäßige oder der empfohlene LOG_LEVEL für jeden Snowpipe-Ereignistyp zusammengefasst:

Ereignis	Protokolliergrad
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 oder ERROR (siehe nächster Abschnitt)
pipe_throttled	WARN

pipe_lifecycle – STOPPED Details des Protokolliergrads:

WARN, wenn die Pipe aus den folgenden Gründen angehalten wurde:

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

ERROR, wenn die Pipe aus den folgenden Gründen angehalten wurde:

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

Die Ereignistabelle nach Snowpipe-Ereignissen abfragen¶

Stellen Sie vor der Abfrage sicher, dass Sie eine Ereignistabelle eingerichtet und den gewünschten Schweregrad für die erfassten Ereignisse konfiguriert haben.

Die folgende Beispielabfrage zeigt, wie Snowpipe-Ereignisse abrufen werden, z. B. solche, die während der Dateierfassung generiert wurden:

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;

Copy

Ausgabebeispiel (erfolgreiche Dateiaufnahme):

Die folgende Ausgabe zeigt beide RECEIVED- und INGESTED-Ereignisse für eine Datei, was eine erfolgreiche Verarbeitung anzeigt:

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“

Für Snowpipe-Ereignisse protokollierte Informationen¶

In den folgenden Abschnitten werden die wichtigsten Spalten und deren Inhalt in der Ereignistabelle für Snowpipe-Ereignisse beschrieben. Wenn eine Spalte in den folgenden Abschnitten nicht explizit aufgeführt ist, lautet ihr Wert NULL für Snowpipe-Ereignisse.

Spaltenwerte der Ereignistabelle¶

Spalte	Datentyp	Beschreibung
Zeitstempel	TIMESTAMP_NTZ	Der UTC-Zeitstempel für den Zeitpunkt, an dem das Ereignis erstellt wurde.
resource_attributes	OBJECT	Attribute, die das Snowpipe-Ereignis identifizieren, wie Datenbank, Schema und Pipe-Namen.
record_type	STRING	Der Typ des erfassten Ereignisses. Bei Snowpipe-Ereignissen ist dieser Wert immer EVENT.
record	OBJECT	Enthält detaillierte Informationen zum Status der Ausführung des Snowpipe-Ereignisses, einschließlich Name und severity_text.
value	VARIANT	Zusätzliche Informationen zum jeweiligen Snowpipe-Ereignis. Wenn die Snowpipe-Aufgabe fehlgeschlagen ist, enthält dies die Fehlermeldung.

Schlüssel-Wert-Paare in der Spalte „resource_attributes“¶

Die resource_attributes-Spalte enthält einen OBJECT-Wert mit den folgenden Schlüssel-Wert-Paaren:

Attributname	Attributtyp	Beschreibung	Beispiel
snow.database.name	VARCHAR	Der Name der mit der Pipe verknüpften Datenbank.	„MY_DATABASE“
snow.schema.name	VARCHAR	Der Name des mit der Pipe verknüpften Schemas.	„MY_SCHEMA_NAME“
snow.pipe.name	VARCHAR	Der Name der Pipe.	„MY_PIPE_NAME“
notification_channel_name	VARCHAR	Der Name des Benachrichtigungskanals, der die Meldung erhalten oder einen Fehler festgestellt hat.	„arn:aws:sqs:us-west-2:774383465531:sf-snowpipe-AIDA3“

Schlüssel-Wert-Paare in der Datensatzspalte¶

Die record-Spalte enthält einen OBJECT-Wert mit den folgenden Schlüssel-Wert-Paaren:

Schlüssel	Typ	Beschreibung	Beispiel
name	VARCHAR	Der Name des Ereignisses.	„pipe_lifecycle“
severity_text	VARCHAR	Der Schweregrad des Ereignisses.	„INFO“