Scala에서 추적 이벤트 내보내기¶

Snowflake Telemetry API 라이브러리의 com.snowflake.telemetry.Telemetry 클래스를 사용하여 Scala로 작성된 함수 또는 프로시저 처리기에서 추적 이벤트를 내보낼 수 있습니다. Telemetry 클래스는 Snowflake에 포함되어 있습니다.

Snowflake는 현재 다음 Scala 버전을 지원합니다.

2.13
2.12

자세한 내용은 다양한 Scala 버전을 지원하는 코드 작성하기 섹션을 참조하십시오.

참고

Snowflake 원격 분석 라이브러리를 사용하면 함수 또는 프로시저의 실행 환경에 다른 라이브러리가 추가됩니다. 자세한 내용은 Snowflake 원격 분석 패키지 종속성 섹션을 참조하십시오.

Maven으로 코드를 패키징할 때 Telemetry 라이브러리를 포함하는 방법에 대한 자세한 내용은 원격 분석 클래스를 사용하도록 Java 및 Scala 환경 설정하기 섹션을 참조하십시오.

이벤트 테이블에서 SELECT 명령을 실행하여 저장된 추적 이벤트 데이터에 액세스할 수 있습니다. 자세한 내용은 추적 데이터 보기 섹션을 참조하십시오.

참고

추적 이벤트를 추가할 때 염두에 두어야 할 지침은 추적 이벤트를 추가하는 일반 지침 섹션을 참조하십시오.

Snowflake에서 로깅 설정 및 메시지 검색에 대한 일반적인 정보는 함수와 프로시저의 추적 이벤트 섹션을 참조하십시오.

코드에서 로깅하기 전에 다음을 수행해야 합니다.

처리기 코드에서 로깅된 메시지를 수집하도록 이벤트 테이블을 설정합니다.

자세한 내용은 이벤트 테이블 개요 섹션을 참조하십시오.
원하는 데이터가 이벤트 테이블에 저장되도록 추적 수준을 설정했는지 확인합니다.

자세한 내용은 로깅, 메트릭 및 추적을 위한 수준 설정하기 섹션을 참조하십시오.

원격 분석 API에 대한 지원 추가하기¶

Telemetry 메서드를 사용하려면 처리기 코드에서 오픈 소스 Snowflake 원격 분석 패키지 를 가용성 있게 설정해야 합니다.

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
}

범위 특성 추가하기¶

Telemetry.setSpanAttribute 메서드를 호출하여 범위와 연결된 특성(키-값 페어)을 설정할 수 있습니다.

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)

범위에 대한 자세한 내용은 Snowflake가 추적 이벤트를 표시하는 방법 섹션을 참조하십시오.

다음 예제의 코드는 4가지 특성을 만들고 해당 값을 설정합니다.

// 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"
}

사용자 지정 범위 추가하기¶

Snowflake에서 생성된 기본 범위와 별도로 사용자 지정 범위를 추가할 수 있습니다. 사용자 지정 범위에 대한 자세한 내용은 추적에 사용자 지정 범위 추가하기 섹션을 참조하십시오.

다음 예제의 코드는 OpenTelemetry API 및 OpenTelemetry context propagation API 를 사용하여 새 my.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"
    }
  }
  $$;