针对函数和过程的跟踪事件¶

您可以通过过程、UDF 或 UDTF 的处理程序代码发出跟踪事件，包括您使用 Snowpark APIs 编写的事件。有关支持的处理程序语言的列表，请参阅支持的语言。

备注

在收集跟踪事件数据之前，您必须启用遥测数据收集。在检测代码时，Snowflake 会生成数据并收集在事件表中。

跟踪事件是一种遥测数据（如日志消息），可以获取系统或应用程序中发生某些事件的时间。与日志消息不同，跟踪事件具有结构化的有效负载，这使其成为数据分析的不错选择。例如，您可以使用跟踪事件，获取在函数执行期间计算的一些数字，并在之后分析这些数字。

在过程或 UDF 中，您可以关联应作为跟踪事件的一部分获取的属性（键值对）。例如，如果您要获取跟踪事件中参数的名称和值，您可以添加名为 parameters 的跟踪事件，并将参数的名称和值设置为事件的属性。

当过程或函数成功执行时，Snowflake 会发出已添加的跟踪事件。Snowflake 使这些跟踪事件在与账户关联的活动事件表中可用。有关事件表的说明，请参阅事件表概述。

您可以通过以下方式对访问跟踪事件数据进行分析：

执行事件表上的 SELECT 命令。
查看 Snowsight 中的跟踪条目。

跟踪示例¶

以下示例中的 Python 代码对 span 设置值为 begin 的 example.proc.do_tracing 属性。它还会在 span 内发出具有 example.key1 和 example.key2 属性的 event_with_attributes 事件。

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
  telemetry.set_span_attribute("example.proc.do_tracing", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  return "SUCCESS"
$$;

Copy

开始使用¶

若要开始通过处理程序代码使用事件跟踪，请按照下列高级步骤操作：

设置事件表。

Snowflake 使用事件表存储处理程序代码发出的事件数据。事件表包含 :doc:` Snowflake 预定义 </developer-guide/logging-tracing/event-table-columns>` 的列。
熟悉针对您将使用的处理程序语言的事件跟踪 API。

请参阅支持的语言，了解处理程序语言的列表，然后查看有关如何通过您的语言发出跟踪事件的内容。
将事件跟踪代码添加到处理程序。
了解如何从事件表中检索事件跟踪数据。

跟踪事件的级别¶

您可以设置跟踪级别，管理事件表中存储的跟踪事件数据的详细程度。在跟踪之前，请使用此设置来确保获取日志消息的严重性。如果您发现事件数据未写入表，请检查跟踪级别，确保 Snowflake 正在捕获您想要的数据。

有关更多信息，请参阅为日志、指标和跟踪设置级别。

支持的语言¶

您可以跟踪用以下语言编写的代码中的事件，包括使用 Snowpark APIs 编写处理程序代码时的事件。

语言/类型	Java	Python	JavaScript	Scala	Snowflake Scripting
存储过程处理程序	✔	✔	✔	✔	✔
Streamlit 应用程序		✔
UDF 处理程序（标量函数）	✔	✔	✔	✔
UDTF 处理程序（表函数）	✔	✔	✔	✔ *

*:: 在 Snowpark 中编写的 Scala UDTF 处理程序。

通过处理程序代码进行事件跟踪¶

要跟踪事件，您可以使用 Snowflake 提供的库，该库专为您正在使用的处理程序代码而设计。Snowflake 会截获跟踪事件，并将其存储在您创建的事件表中。

下表列出了日志记录支持的处理程序语言，以及指向通过代码记录相关内容的链接。

语言	遥测库	文档
Java	Snowflake `Telemetry` 类。	在 Java 中发出跟踪事件
JavaScript	Snowflake JavaScript API。	在 JavaScript 中发出跟踪事件
Python	Snowflake `telemetry` 包。	在 Python 中发出跟踪事件
Scala	Snowflake `Telemetry` 类。	使用 Scala 发出跟踪事件
Snowflake Scripting	Snowflake SQL 函数。	在 Snowflake Scripting 中发出跟踪事件

SQL 语句跟踪¶

默认情况下当启用跟踪功能时，Snowflake 会跟踪与其他跟踪代码一起执行的 SQL 语句，例如在存储过程或用户定义函数的处理程序中执行的语句。

默认情况下，Snowflake 会在以下上下文中跟踪 SQL：

SQL 在存储过程中执行
执行存储过程的 SQL
执行一个或多个用户定义的函数的 SQL
由 DBT 执行的 SQL
由 Streamlit 执行的 SQL
由笔记本执行的 SQL
当代码上下文是 Python 或 Go 连接器时在 Snowpark Container Services 中执行的 SQL

请注意，不支持以下内容：

Snowflake Native App 中的 SQL 语句
直接在工作表或工作区中执行 SQL

对于跟踪的 SQL 语句，可以在事件表中找到发出的数据，包括以下各列：

在 RESOURCE_ATTRIBUTES 列中，snow.executable.type 属性值为 QUERY。
在 RECORD 列中，name 属性值是跟踪其执行情况的 SQL 语句的类型，例如 SELECT、CALL 或 INSERT。
在 RECORD_ATTRIBUTES 列中，以下属性包含与 SQL 跟踪相关的值：
- db.query.table.names
- db.query.view.names
- db.query.executable.names
- :code:`db.query.text`（如果已启用）

您可以指定是否应将 SQL 文本本身（最多 1024 个字符）包含在事件表中捕获的跟踪数据中。如果 SQL 文本可能包含敏感信息或者没有用处，则可能需要忽略该文本。

要在跟踪时捕获 SQL 文本，请将 SQL_TRACE_QUERY_TEXT 参数设置为 :code:`"ON"`（必须使用 ACCOUNTADMIN 角色来设置此参数）。

添加跟踪事件的一般准则¶

在调用跟踪事件 APIs 以添加跟踪事件和设置 span 属性时，请注意以下几点：

一个 span 最多可以容纳 128 个跟踪事件，以及最多 128 个 span 属性。
如果添加的跟踪事件与之前添加的事件同名，则会创建新的事件记录。
如果设置的 span 属性与之前设置的 span 属性具有相同的键，则该键的值将被覆盖。

查看收集的事件数据¶

您可以通过 Snowsight 查看跟踪数据或者通过查询存储跟踪数据的事件表，以查看跟踪数据。有关更多信息，请参阅查看跟踪数据。