使用 Scala 发出跟踪事件¶

您可以使用 Snowflake 遥测 API (https://javadoc.io/doc/com.snowflake/telemetry/latest/index.html) 库中的 com.snowflake.telemetry.Telemetry 类，从使用 Scala 编写的函数或过程处理程序中发出跟踪事件。Telemetry 类包含在 Snowflake 中。

Snowflake 目前支持以下 Scala 版本：

2.13
2.12

有关更多信息，请参阅编写代码以支持不同 Scala 版本。

备注

使用 Snowflake 遥测库将其他库添加到函数或过程的执行环境中。有关更多信息，请参阅 Snowflake 遥测包依赖项。

有关使用 Maven 打包代码时包含遥测库的信息，请参阅设置 Java 和 Scala 环境以使用遥测类。

您可以通过对事件表执行 SELECT 命令，来访问存储的跟踪事件数据。有关更多信息，请参阅查看跟踪数据。

备注

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

有关在 Snowflake 中设置日志记录和检索消息的一般信息，请参阅针对函数和过程的跟踪事件。

通过代码记录之前，您必须：

设置事件表来收集通过处理程序代码记录的消息。

有关更多信息，请参阅事件表概述。
请确保已设置跟踪级别，以便将所需数据存储在事件表中。

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

添加对遥测 API 的支持¶

要使用 Telemetry 方法，您必须向处理程序代码提供开源的 Snowflake 遥测包 (https://central.sonatype.com/artifact/com.snowflake/telemetry)。

在 CREATE PROCEDURE 或 CREATE FUNCTION 语句的 PACKAGES 子句中包括 com.snowflake:telemetry 包。PACKAGES 子句会向代码提供包含的 Snowflake 遥测 API。

以下示例中的代码使用 PACKAGES 子句引用遥测库以及 Snowpark 库（这是使用 Scala 编写的存储过程所必需的 – 有关更多信息，请参阅为使用 SQL 创建的存储过程编写 Scala 处理程序）。
CREATE OR REPLACE PROCEDURE myproc(...) RETURNS ... LANGUAGE SCALA ... PACKAGES = ('com.snowflake:snowpark_2.12:latest', 'com.snowflake:telemetry:latest') ...
CREATE OR REPLACE PROCEDURE myproc(...) RETURNS ... LANGUAGE SCALA ... PACKAGES = ('com.snowflake:snowpark_2.13:latest', 'com.snowflake:telemetry:latest') ...
在处理程序代码中导入 com.snowflake.telemetry 包。
```
import com.snowflake.telemetry.Telemetry
```

添加跟踪事件¶

您可以通过调用 Telemetry.addEvent 方法添加跟踪事件，传递事件的名称。您还可以选择将属性（键值对）与事件相关联。

addEvent 方法具有以下签名：

public static void addEvent(String name)
public static void addEvent(String name, Attributes attributes)

以下示例中的代码添加了一个名为 testEvent 的事件，并为事件关联了两个属性：key 和 result。

// 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)

添加这些事件会在事件表中添加两行，每行在列中 RECORD 具有不同的值：

{
  "name": "testEvent"
}

{
  "name": "testEventWithAttributes"
}

testEventWithAttributes 事件行包含行的 RECORD_ATTRIBUTES 列中的以下属性：

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

添加 span 属性¶

您可以通过调用 Telemetry.setSpanAttribute 方法来设置与 span 关联的属性（键值对）。

setSpanAttribute 方法具有以下签名：

public static void setSpanAttribute(String key, boolean value)
public static void setSpanAttribute(String key, long value)
public static void setSpanAttribute(String key, double value)
public static void setSpanAttribute(String key, String value)

有关 Span 的详细信息，请参阅 Snowflake 如何表示跟踪事件。

以下示例中的代码创建四个属性并设置其值：

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

设置这些属性会导致事件表的 RECORD_ATTRIBUTES 列中出现以下内容：

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

添加自定义 span¶

您可以添加与 Snowflake 创建的默认 span 分开的自定义 span。有关自定义 span 的详细信息，请参阅为跟踪添加自定义 span。

以下示例中的代码使用 OpenTelemetry API (https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/index.html) 和 OpenTelemetry 上下文传播 API (https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-context-prop/latest/index.html) 来创建新的 my.span span。然后将事件添加到新的 span。最后，代码结束与 span 相关的操作，以便在事件表中捕获 span 的事件数据。如果该代码不调用 Span.end 方法，则不会在事件表中捕获数据。

CREATE OR REPLACE FUNCTION testScalaUserSpans(x VARCHAR) RETURNS VARCHAR
  LANGUAGE SCALA
  RUNTIME_VERSION = 2.12
  PACKAGES = ('com.snowflake:telemetry:latest')
  HANDLER = 'TestScalaClass.run'
  AS
  $$
  class TestScalaClass {
    import com.snowflake.telemetry.Telemetry
    import io.opentelemetry.api.GlobalOpenTelemetry
    import io.opentelemetry.api.trace.Tracer
    import io.opentelemetry.api.trace.Span
    import io.opentelemetry.context.Scope

    def run(x: String): String = {
      val tracer: Tracer = GlobalOpenTelemetry.getTracerProvider().get("my.tracer")
      val span: Span = tracer.spanBuilder("my.span").startSpan()
      span.addEvent("test event from scala")
      span.end()
      return x
    }
  }
  $$;

CREATE OR REPLACE FUNCTION testScalaUserSpans(x VARCHAR) RETURNS VARCHAR
  LANGUAGE SCALA
  RUNTIME_VERSION = 2.13
  PACKAGES = ('com.snowflake:telemetry:latest')
  HANDLER = 'TestScalaClass.run'
  AS
  $$
  class TestScalaClass {
    import com.snowflake.telemetry.Telemetry
    import io.opentelemetry.api.GlobalOpenTelemetry
    import io.opentelemetry.api.trace.Tracer
    import io.opentelemetry.api.trace.Span
    import io.opentelemetry.context.Scope

    def run(x: String): String = {
      val tracer: Tracer = GlobalOpenTelemetry.getTracerProvider().get("my.tracer")
      val span: Span = tracer.spanBuilder("my.span").startSpan()
      span.addEvent("test event from scala")
      span.end()
      return x
    }
  }
  $$;

示例¶

存储过程示例¶

CREATE OR REPLACE PROCEDURE do_tracing()
  RETURNS STRING
  LANGUAGE SCALA
  RUNTIME_VERSION = '2.12'
  PACKAGES=('com.snowflake:snowpark_2.12:latest', 'com.snowflake:telemetry:latest')
  HANDLER = 'ProcedureHandler.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

  class ProcedureHandler {

    def run(session: Session): String = {

      // Set span attribute.
      Telemetry.setSpanAttribute("example.proc.do_tracing", "begin")

      // Add an event without attributes.
      Telemetry.addEvent("run_method_start")

      // Add an event with attributes.
      val eventAttributes: Attributes = Attributes.of(
        AttributeKey.stringKey("example.method.name"), "run")
      Telemetry.addEvent("event_with_attributes", eventAttributes)

      // Set span attribute.
      Telemetry.setSpanAttribute("example.proc.do_tracing", "complete")

      return "SUCCESS"
    }
  }
  $$;

CREATE OR REPLACE PROCEDURE do_tracing()
  RETURNS STRING
  LANGUAGE SCALA
  RUNTIME_VERSION = '2.13'
  PACKAGES=('com.snowflake:snowpark_2.13:latest', 'com.snowflake:telemetry:latest')
  HANDLER = 'ProcedureHandler.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

  class ProcedureHandler {

    def run(session: Session): String = {

      // Set span attribute.
      Telemetry.setSpanAttribute("example.proc.do_tracing", "begin")

      // Add an event without attributes.
      Telemetry.addEvent("run_method_start")

      // Add an event with attributes.
      val eventAttributes: Attributes = Attributes.of(
        AttributeKey.stringKey("example.method.name"), "run")
      Telemetry.addEvent("event_with_attributes", eventAttributes)

      // Set span attribute.
      Telemetry.setSpanAttribute("example.proc.do_tracing", "complete")

      return "SUCCESS"
    }
  }
  $$;