Snowpipeのイベントをモニタリングする¶

パイプのステータスに関する詳細情報を提供するイベントを記録するようにSnowflakeを構成できます。これらのイベントは、パイプに関連付けられたアクティブイベントテーブルにキャプチャされます。

これらのイベントをモニタリングすることで、次の領域に対するインサイトを得ることができます。

パイプのステータス変更：Snowpipeの運用状態を追跡します。
ファイル処理の進捗状況：Snowpipeシステムを介したファイルのジャーニーを理解します。
定期的な、集約された、データインジェスションの統計の要約：データインジェスションに関する統計の要約を入手できます。

さらに、次の重大な状況に対するアラートを構成できます。

大量の受信ファイル
高いインジェスションレイテンシ
パイプエラー
ファイルエラー

次のセクションでは、Snowpipeのイベントログを有効にする方法、ログレベルを構成する方法、およびイベントテーブルに記録されたイベントを解釈する方法について説明します。

Snowpipeのイベントタイプ：イベントのさまざまなカテゴリとその詳細について学びます。
キャプチャするイベントの重大度レベルを設定します。重要性に基づいて記録するイベントを構成します。
Snowpipeイベントのイベントテーブルをクエリします。イベントデータを取得し分析する方法を学びます。
Snowpipeイベントのログに記録された情報：イベントテーブル列内のデータの構造と意味を理解します。

注意

Snowpipeのイベントのログにはコストがかかります。詳細については、テレメトリーデータ収集の費用をご参照ください。

Snowpipeのイベントタイプ¶

Snowpipeのイベントはイベントテーブルの RECORD 列内の name 属性によって識別されます。

file_lifecycle¶

file_lifecycle イベントは、Snowpipeシステム内のファイルの移動を追跡します。ファイルの状態は RECEIVED、``INGESTED``または ``ERRORED``となります。

RECEIVED:Snowpipeがファイルリクエストを受信すると、イベントが出力されます。このファイルが以前処理されたものである場合、パイプはこのファイルをスキップする可能性があります。このような場合は skipped 属性で示されます。

{
  "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:ファイルが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"
  }
}

Copy

ERRORED:ファイルが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"
  }
}

Copy

notification_received¶

このイベントは、Snowflakeが通知メッセージを受信したときに発生します。

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

このイベントは、Snowflakeが通知チャネルからメッセージを読み込んでいるときにエラーが発生した場合に出力されます。これは通常、認証の問題などのユーザー構成エラーを示しています。

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

このイベントはパイプのステータスを変更すると出力されます。新しいステータスは RUNNING、PAUSED、STOPPED または STALLED となります。

パイプステータスが RUNNING または 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

パイプステータスが STOPPED_* または STALLED_* の場合：これらのステータスは、パイプがファイルの処理を予期せず停止したことを示します。

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

STOPPED_* または STALLED_* 状態の severity_text は特定の理由によって異なります。

次の理由でパイプが停止した場合は WARN：

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

次の理由でパイプが停止した場合は ERROR：

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¶

このイベントは、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": "pipe_throttled",
    "severity_text": "WARN"
  },
  "VALUE": {
    "throttled_files": "<throttled_file_name_list>"
  }
}

Copy

キャプチャするイベントの重大度レベルを設定する¶

Snowpipeのイベントがイベントテーブルに記録されるようにするには、パイプレベルまたはアカウントレベルのいずれかの LOG_LEVEL パラメーターを設定する必要があります。LOG_LEVEL は、重大度に基づいてどのイベントをキャプチャするかを決定します。

ERROR:解決するために人間の介入が必要な変更を示すイベントに使用します。
WARN:人間の介入なしに解決できる問題を示すイベントに使用します。
INFO:一般に有用で大量のイベントではない、ユーザーが開始するイベントに使用します。
DEBUG:大量のイベントに使用します。
TRACE:非常に詳細な情報をキャプチャするログの最も低いレベル。

注意

アカウントレベルまたはパイプレベルで重大度レベルが設定されていない場合、イベントはキャプチャされません。

例:

アカウント内のすべてのオブジェクトに対して ERROR レベルのイベントをキャプチャするには、次のコードを実行します。

ALTER ACCOUNT <my_account_name> SET LOG_LEVEL = ERROR;

Copy

特定のパイプに対する INFO レベルのイベントをキャプチャするには、次のコードを実行します。

ALTER PIPE <my_pipe_name> SET LOG_LEVEL = INFO;

Copy

各イベントタイプのログレベル¶

次のテーブルは、各Snowpipeイベントタイプのデフォルトまたは推奨 LOG_LEVEL をまとめたものです。

イベント	ログレベル
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 または ERROR（次のセクションを参照）
pipe_throttled	WARN

pipe_lifecycle - STOPPED ログレベルの詳細：

次の理由でパイプが停止した場合は WARN：

STOPPED_BY_SNOWFLAKE_ADMIN
STOPPED_CLONED
STOPPED_FEATURE_DISABLED

次の理由でパイプが停止した場合は ERROR：

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

Snowpipeイベントのイベントテーブルをクエリする¶

クエリの前に、イベントテーブルを設定し、キャプチャするイベントの重大度レベルが構成されていることを確認してください。

次のクエリ例は、ファイルのインジェスション中に生成されたイベントなど、Snowpipeイベントを取得する方法を示しています。

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

出力例（正常なファイルインジェスション）：

次の出力は、ファイルの RECEIVED および INGESTED イベントの両方を示しています。これは処理が成功したことを示します。

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」

Snowpipeイベントのログに記録された情報¶

次のセクションでは、Snowpipeイベントのイベントテーブル内の主要な列とその内容について説明します。列が以下のセクションで明示的にリストされていない場合、Snowpipeイベントのその値は NULL になります。

イベントテーブル列値¶

列	データ型	説明
タイムスタンプ	TIMESTAMP_NTZ	イベントが作成されたときの UTC タイムスタンプ。
resource_attributes	OBJECT	データベース名、スキーマ名、パイプ名など、Snowpipeイベントを識別する属性。
record_type	STRING	記録されたイベントのタイプ。Snowpipeイベントの場合、この値は常に EVENT です。
record	OBJECT	名前とseverity_textなど、Snowpipeイベントの実行ステータスに関する詳細情報が含まれます。
value	VARIANT	Snowpipeイベントに固有の追加情報。Snowpipeタスクが失敗した場合、これにはエラーメッセージが含まれます。

Resource_attributes列のキーと値のペア¶

resource_attributes 列には、以下のキーと値のペアを含む OBJECT 値が含まれます。

属性名	属性の型	説明	例
snow.database.name	VARCHAR	パイプに関連付けられているデータベースの名前。	「MY_DATABASE」
snow.schema.name	VARCHAR	パイプに関連付けられたスキーマの名前。	「MY_SCHEMA_NAME」
snow.pipe.name	VARCHAR	パイプの名前。	「MY_PIPE_NAME」
notification_channel_name	VARCHAR	メッセージを受信したか、エラーが発生した通知チャネルの名前。	"arn:aws:sqs:us-west-2:774383465531:sf-snowpipe-AIDA3"

記録列のキーと値のペア¶

record 列には、以下のキーと値のペアを含む OBJECT 値が含まれます。

キー	型	説明	例
name	VARCHAR	イベントの名前。	"pipe_lifecycle"
severity_text	VARCHAR	ログの重大度レベル。	「INFO」