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

您可以通过过程、UDF 或 UDTF 的处理程序代码发出跟踪事件，包括您 :doc:` 使用 Snowpark APIs ` </developer-guide/snowpark/index> 编写的事件。有关支持的处理程序语言的列表，请参阅支持的语言。

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

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

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

您可以对事件表执行 SELECT 命令，从而访问跟踪事件数据。有关更多信息，请参阅访问跟踪数据。

跟踪示例¶

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

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION=3.8
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。

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

跟踪事件的级别¶

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

有关更多信息，请参阅设置跟踪级别。

支持的语言¶

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

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

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

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

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

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

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

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

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

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

事件数据访问¶

您可以对事件表执行 SELECT 命令，从而访问日志消息。有关更多信息，请参阅访问跟踪数据。