Snowflake 如何表示跟踪事件

在内部，Snowflake 使用 OpenTelemetry (https://opentelemetry.io/) 数据模型来表示名为 span 的对象内的跟踪事件。span (https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span) 描述操作，例如调用存储过程或对一组行执行 UDF。span 包括操作的开始时间和结束时间。

小技巧

有关添加跟踪事件时要牢记的准则，请参阅 添加跟踪事件的一般准则。

Snowflake 如何发出跟踪事件

对于存储过程或 UDF，Snowflake 可以在调用时并行执行它，其中每个并行执行单元在一组不同的行上执行。发出的任何跟踪事件都限定到其执行单元，并包装在同一 span 内。

对于 Streamlit 应用程序，每个用户会话在单个 span 中获取。

跟踪事件仅在其执行单元完成后发出。如果执行单元在完成之前失败，则不保证会发出来自该执行单元的跟踪事件。

来自不同执行单元的跟踪事件存储在事件表的单独行中（即在不同的 span 中）。

备注

由于是按输入表行应用 UDFs，因此针对每个输入表行执行 UDF 中跟踪事件 APIs 的调用。在大多数情况下，不建议为每行添加跟踪事件。每个执行单元限制为 128 个事件。

示例：从 Java 过程发出事件

以下示例演示如何从处理程序代码发出事件。它还显示事件表如何存储生成的事件数据。

使用 Java 处理程序的存储过程

以下示例中的 Java 代码演示如何将事件以及属性数据添加到 span。有关处理程序语言的 APIs 的更多信息，请参阅 通过处理程序代码进行事件跟踪。

CREATE OR REPLACE PROCEDURE test_stored_proc()
RETURNS STRING
LANGUAGE JAVA
RUNTIME_VERSION = '11'
PACKAGES=('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
HANDLER = 'MyClass.run'
AS
$$
  import com.snowflake.snowpark_java.Session;
  import com.snowflake.telemetry.Telemetry;
  import io.opentelemetry.api.common.AttributeKey;
  import io.opentelemetry.api.common.Attributes;
  import io.opentelemetry.api.common.AttributesBuilder;

  public class MyClass {

    public String run(Session session) {
      // Adding an event without attributes.
      Telemetry.addEvent("testEvent");

      // Adding an event with attributes.
      Attributes eventAttributes = Attributes.of(
          AttributeKey.stringKey("key"), "run",
          AttributeKey.longKey("result"), Long.valueOf(123));
      Telemetry.addEvent("testEventWithAttributes", eventAttributes);

      // Setting span attributes of different types.
      Telemetry.setSpanAttribute("example.boolean", true);
      Telemetry.setSpanAttribute("example.long", 2L);
      Telemetry.setSpanAttribute("example.double", 2.5);
      Telemetry.setSpanAttribute("example.string", "testAttribute");

      return "SUCCESS";
    }
  }
$$;

记录的 span 数据

函数或过程成功执行后，Snowflake 会将 OpenTelemetry span 对象呈现为事件表列中的对象，如下表所示。

span 可以有自己的属性。由于 span 表示存储过程和 UDF 执行单元，因此您可能会发现为以后的数据分析设置 span 级别属性很有用。有关如何设置 span 属性的更多信息，请参阅特定于编写处理程序代码所用语言的内容。有关这些语言的列表，请参阅 通过处理程序代码进行事件跟踪。

一个 span 最多可以容纳 128 个跟踪事件，以及最多 128 个 span 属性。

  • 如果跟踪事件数超过限制，则根据处理程序语言，按如下方式删除事件：

    • 对于 Python 处理程序，按添加顺序（换句话说，按先进先出的顺序）删除事件。

    • 对于用 Java、JavaScript、Scala 和 Snowflake Scripting 编写的处理程序，一旦达到限制，就会删除新事件。

  • 如果 span 属性的数量超过限制，则无法再添加 span 属性。

备注

截至 2022 年 11 月，由于 OpenTelemetry JavaScript Tracing SDK 没有报告删除的计数，因此所有 dropped_*_count 键均未针对 JavaScript 设置。

描述

数据

Snowflake 记录的 span，用于执行包含处理程序代码的过程。

  • START_TIMESTAMP 列中的开始时间戳：

    2023-03-21 23:12:06.231

  • TIMESTAMP 列中的完成时间戳：

    2023-03-21 23:12:06.944

  • RECORD 列中的数据：

    {
  "kind": "SPAN_KIND_INTERNAL",
  "name": "snow.auto_instrumented",
  "status": {
    "code": "STATUS_CODE_UNSET"
  }
}

由处理程序代码为 span 添加的属性。

  • RECORD_ATTRIBUTES 列中的数据：

    {
  "example.boolean": true,
  "example.double": 2.5,
  "example.long": 2,
  "example.string": "testAttribute"
}

记录的事件数据

该 span 包含一系列跟踪事件，其中时间戳获取跟踪事件的添加时间。此处未显示：span 具有 trace_id，即不带破折号的查询 ID。该 span 还具有系统生成的 span_id 和 name 键值。属于该 span 的事件共享相同的 span_id.

针对事件 testEvent 记录以下数据。

描述

数据

事件名称

  • TIMESTAMP 列中的时间戳：

    2023-03-21 23:12:06.939

  • RECORD 列中的数据：

    {
  "dropped_attributes_count": 0,
  "name": "testEvent"
}

针对事件 testEventWithAttributes 记录以下数据。

描述

数据

事件名称

  • TIMESTAMP 列中的时间戳：

    2023-03-21 23:12:06.940

  • RECORD 列中的数据：

    {
  "dropped_attributes_count": 0,
  "name": "testEventWithAttributes"
}

事件属性

  • RECORD_ATTRIBUTES 列中的数据：

    {
  "key": "run",
  "result": 123
}