Snowflakeがトレースイベントを表す方法

Snowflakeは内部的に、 OpenTelemetry データモデルを使用して、 スパン と呼ばれるオブジェクト内のトレースイベントを表します。 スパン は、ストアドプロシージャの呼び出しや一連の行に対する UDF の実行などの操作を記述します。スパンには、操作の開始時刻と終了時刻が含まれます。

Tip

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

Snowflakeがトレースイベントを出力する方法

ストアドプロシージャまたは UDF が呼び出されると、Snowflakeはそれを並列実行できます。各並列実行ユニットは異なる行セットで実行されます。出力されるトレースイベントはすべて、その実行ユニットにスコープされ、同じスパン内にラップされます。

トレースイベントは、実行ユニットが完了した後にのみ出力されます。実行ユニットが完了前に失敗した場合、その実行ユニットからのトレースイベントが出力されることは保証されません。

異なる実行ユニットからのトレースイベントは、イベントテーブルの個別の行（つまり、異なるスパン）に格納されます。

注釈

UDFs は入力テーブルの行ごとに適用されるため、 UDF 内のトレースイベント APIs の呼び出しは、入力テーブルの行ごとに実行されます。ほとんどの場合、行ごとにトレースイベントを追加することはお勧めできません。実行ユニットごとに128個のイベントの制限があります。

例: Javaプロシージャからのイベントの出力

次の例は、ハンドラーコードからイベントを出力する方法を示しています。また、生成されたイベントデータがイベントテーブルにどのように格納されるかについても示します。

Javaハンドラーを使用したストアドプロシージャ

次の例のJavaコードは、属性データとともにイベントをスパンに追加する方法を示しています。ハンドラー言語の 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";
    }
  }
$$;
Copy

記録されたスパンデータ

関数またはプロシージャが正常に実行されると、次のテーブルに示すように、Snowflakeは OpenTelemetry スパンオブジェクトをイベントテーブルの列内のオブジェクトとして表示します。

スパンは独自の属性を持つことができます。スパンはストアドプロシージャと UDF 実行ユニットを表すため、後のデータ分析のためにスパンレベルの属性を設定すると便利な場合があります。スパン属性の設定方法の詳細については、ハンドラーコードを記述している言語に固有の内容をご参照ください。これらの言語のリストについては、 ハンドラーコードからのイベントトレース をご参照ください。

スパンは、最大128個のトレースイベントと最大128個のスパン属性を保持できます。

  • トレースイベントの数が制限を超えると、ハンドラー言語に応じて次のようにイベントがドロップされます。

    • Pythonハンドラーの場合、イベントは追加された順序（つまり、先入れ先出しの順序）でドロップされます。

    • Java、 JavaScript、Scala、およびSnowflakeスクリプトで記述されたハンドラーの場合は、制限に達すると、新しいイベントがドロップされます。

  • スパン属性の数が制限を超えると、それ以上スパン属性は追加できません。

注釈

2022年11月の時点では、 OpenTelemetry JavaScript トレース SDK がドロップ数をレポートしないため、すべての dropped_*_count キーが JavaScript に設定されていません。

説明

データ

ハンドラーコードを含むプロシージャの実行用にSnowflakeによって記録されたスパン。

  • 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"
  }
}
    Copy

スパンのハンドラーコードによって追加された属性。

  • RECORD_ATTRIBUTES 列からのデータ。

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

記録されたイベントデータ

スパンには、トレースイベントの追加時刻をキャプチャするタイムスタンプ付きのトレースイベントのリストが含まれています。ここには示されていません。スパンには、ダッシュなしのクエリ ID である trace_id があります。スパンには、システムが生成した span_id キーと name キーの値も含まれます。スパンの一部であるイベントは、同じ span_id を共有します。

次のデータはイベント testEvent に対して記録されました。

説明

データ

イベント名

  • TIMESTAMP 列からのタイムスタンプ。

    2023-03-21 23:12:06.939

  • RECORD 列からのデータ。

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

次のデータはイベント testEventWithAttributes に対して記録されました。

説明

データ

イベント名

  • TIMESTAMP 列からのタイムスタンプ。

    2023-03-21 23:12:06.940

  • RECORD 列からのデータ。

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

イベント属性

  • RECORD_ATTRIBUTES 列からのデータ。

    {
  "key": "run",
  "result": 123
}
    Copy
言語: 日本語