为跟踪添加自定义 span

您可以为跟踪添加自定义 span，以便在过程或函数的处理程序中进行更精细的跟踪。

默认情况下，当您 启用跟踪 后，Snowflake 会为您启动一个 span（如 Snowflake 如何表示跟踪事件 中所述），并将所有跟踪事件添加到该 span 中。（这在内部称为“auto_instrumented”span。）您可使用 OpenTelemetry APIs 创建您自己的 span。对于新的 span，您可以使用您的语言的 OpenTelemetry API 或 Snowflake API 来添加事件和属性。

例如，当您想为过程中发生的计算量大的操作（比如使用代码训练 ML 模型）隔离跟踪数据时，你可能需要创建自己的 span。

您创建的自定义 span 与 OpenTelemetry 创建的 span 的默认行为相匹配。

支持的语言

您可以通过使用以下语言编写的代码添加自定义 span，包括使用 Snowpark APIs 编写处理程序代码时。

语言/类型

Java

Python

JavaScript

Scala

Snowflake Scripting

存储过程处理程序

✔

✔

✔

✔ [1]

Streamlit 应用程序

✔

UDF 处理程序（标量函数）

✔

✔

✔

✔ [1]

UDTF 处理程序（表函数）

✔

✔

✔

✔ [1] [2]

创建自定义 span

要使用处理程序代码添加自定义 span，请在现有的 Snowflake 遥测环境中使用 OpenTelemetry API 为处理程序语言创建一个新 span，根据需要添加事件和属性，然后关闭此 span。

  1. 使用 OpenTelemetry API 创建一个跟踪器来管理 span 的上下文。

    通过这个在现有 Snowflake 遥测环境中创建的跟踪器，您可以创建使用现有基础设施的自定义 span，在此基础设施中，跟踪数据由事件表捕获。

  2. 在新的跟踪器中，使用一个 API 创建自定义 span，以确保新的 span 就是当前 span。

    通过在 Snowflake 管理的现有上下文中创建新的 span，您可以确保来自上下文中的信息（包括 trace_id 和 parent_span_id 值）从 Snowflake 默认 span 传递到其他 span。

  3. 当使用自定义 span 的代码执行完成时，必须在处理程序完成执行之前关闭 span，以便事件表捕获跟踪数据。

    自定义 span 的这种行为与 OpenTelemetry 的默认行为相匹配。

有关使用支持的语言添加自定义 span 的信息，请参阅以下主题：

Python 示例

以下示例中的代码使用 OpenTelemetry Python API (https://opentelemetry-python.readthedocs.io/en/latest/api/index.html) 通过 start_as_current_span 来创建 my.span，以作为当前 span。然后使用 OpenTelemetry Python API (https://opentelemetry-python.readthedocs.io/en/latest/api/index.html) 向新的 span 添加一个带有属性的事件。

事件表不会捕获事件数据，除非 span 在处理程序完成执行之前结束。在本例中，with 语句结束时，会自动关闭 span。

CREATE OR REPLACE FUNCTION customSpansPythonExample() RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.9
PACKAGES = ('snowflake-telemetry-python', 'opentelemetry-api')
HANDLER = 'custom_spans_function'
AS $$
from snowflake import telemetry
from opentelemetry import trace

def custom_spans_function():
  tracer = trace.get_tracer("my.tracer")
  with tracer.start_as_current_span("my.span") as span:
    span.add_event("Event2 in custom span", {"key1": "value1", "key2": "value2"})

  return "success"
$$;
Copy
语言: 中文