Scalaでのトレースイベントの出力

Snowflake Telemetry API ライブラリの com.snowflake.telemetry.Telemetry クラスを使用して、Scalaで記述された関数またはプロシージャハンドラーからトレースイベントを出力できます。Telemetry クラスはSnowflakeに含まれています。

Snowflakeは現在、次のScalaのバージョンをサポートしています。

Snowflakeのロゴ（黒）（文字なし） プレビュー機能 --- オープン

バージョン2.13のサポートはプレビュー中です。すべてのアカウントで利用可能です。

  • 2.13

  • 2.12

詳細については、 異なるScalaバージョンをサポートするコードの記述 をご参照ください。

注釈

Snowflakeテレメトリライブラリを使用すると、関数またはプロシージャの実行環境に他のライブラリが追加されます。詳細については、 Snowflakeテレメトリパッケージの依存関係 をご参照ください。

Mavenでコードをパッケージ化するときにテレメトリライブラリを含める方法については、 テレメトリクラスを使用するためのJavaおよびScala環境の設定 をご参照ください。

イベントテーブルで SELECT コマンドを実行すると、格納されたトレースイベントデータにアクセスできます。詳細については、 トレースデータの表示 をご参照ください。

注釈

トレースイベントを追加する際に留意すべきガイドラインについては、 トレースイベントを追加するための一般的なガイドライン をご参照ください。

Snowflakeでのログの設定とメッセージの取得に関する一般的な情報については、 関数とプロシージャのイベントをトレースする をご参照ください。

コードからログする前に、次を実行する必要があります。

  • ハンドラーコードからログされたメッセージを収集するイベントテーブルを設定します。

    詳細については、 イベントテーブルの概要 をご参照ください。

  • 必要なデータがイベントテーブルに格納されるようにトレースレベルが設定されていることを確認してください。

    詳細については、 ロギング、メトリクス、トレースのレベル設定 をご参照ください。

Telemetry API のサポートの追加

Telemetry メソッドを使用するには、オープンソースの Snowflake テレメトリーパッケージ をハンドラーコードで可用性にする必要があります。

  • CREATE PROCEDURE または CREATE FUNCTION ステートメントの PACKAGES 句に、 com.snowflake:telemetry パッケージを含めます。PACKAGES 句により、含まれているSnowflakeテレメトリ API がコードで使用できるようになります。

    次の例のコードでは、 PACKAGES 句を使用してTelemetryライブラリとSnowparkライブラリ（Scalaで記述されたストアドプロシージャに必要です。詳細については、 SQL で作成したストアドプロシージャの Scala ハンドラーを記述します。 を参照）を参照します。

    CREATE OR REPLACE PROCEDURE myproc(...)
  RETURNS ...
  LANGUAGE SCALA
  ...
  PACKAGES = ('com.snowflake:snowpark_2.12: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 というイベントを追加し、そのイベントに2つの属性 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)

これらのイベントを追加すると、イベントテーブルに2つの行が作成され、それぞれの 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コンテキスト伝搬 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 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"
    }
  }
  $$;