监控 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	TIMESTAMP_NTZ	事件创建时的 UTC 时间戳。
resource_attributes	OBJECT	用于标识 Snowpipe 事件的属性，例如数据库、架构和管道名称。
record_type	STRING	记录的事件类型。对于 Snowpipe 事件，此值始终为 EVENT。
record	OBJECT	包含有关运行 Snowpipe 事件状态的详细信息，包括 name 和 severity_text。
值	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"