トレースへのカスタムスパンの追加¶

独自のカスタムスパンをトレースに追加して、プロシージャや関数のハンドラー内でより細かいトレースを行うことができます。

デフォルトでは、トレースが有効になっている場合、、Snowflake は（ Snowflakeがトレースイベントを表す方法で説明されているように）あなたのためにスパンを開始し、すべてのトレースイベントをそのスパンに追加します。（これは内部では「auto_instrumented」スパンと呼ばれています）。OpenTelemetry APIs を使えば、独自のスパンを作ることができます。新しいスパンには、あなたの言語の OpenTelemetry API または Snowflake API のいずれかを使用して、イベントと属性を追加できます。

例えば、 ML モデルのトレーニングにコードを使用する場合など、プロシージャー内で発生する計算負荷の高いアクションのトレースデータを分離したい場合、独自のスパンを作成したいと思うかもしれません。

作成したカスタム・スパンは、 OpenTelemetry によって作成されたスパンのデフォルトの動作と一致します。

サポートされている言語¶

次の言語で記述されたコードからのメッセージをログに記録できます。これには、ハンドラーコードを Snowpark APIs で記述する場合も含みます。


言語/タイプ	Java	Python	JavaScript	Scala
ストアドプロシージャハンドラー	✔	✔	✔	✔ [1]
Streamlitアプリ		✔
UDF ハンドラー（スカラー関数）	✔	✔	✔	✔ [1]
UDTF ハンドラー（テーブル関数）	✔	✔	✔	✔ [1] [2]

カスタム予算の作成¶

ハンドラコードを持つカスタムスパンを追加するには、既存のSnowflake Telemetry環境内でハンドラー言語用の OpenTelemetry API を使用して新しいスパンを作成し、必要に応じてイベントと属性を追加し、スパンを閉じます。

OpenTelemetry API を使用して、スパンのコンテキストを管理するトレーサーを作成します。

既存の Snowflake Telemetry環境から作成されたこのトレーサーから、イベントテーブルによってトレースデータがキャプチャされる既存のインフラストラクチャを使用するカスタムスパンを作成できます。
新しいトレーサーから、新しいスパンが現在のスパンであることを保証する API で、カスタムスパンを作成します。

Snowflakeが管理する既存のコンテキストに新しいスパンを作成することで、コンテキストからの情報（trace_id および parent_span_id の値を含む）が、Snowflakeのデフォルトスパンから他のスパンに確実に渡されます。
あなたのコードがカスタムスパンで終了したとき、イベントテーブルにトレースデータが取り込まれるためには、ハンドラーの実行が完了する前にスパンを閉じなければなりません。

カスタムスパンのこの動作は、 OpenTelemetry のデフォルトの動作と一致します。

サポートされている言語でカスタムスパンを追加する方法については、以下のトピックを参照してください。

Pythonの例¶

次の例のコードは、 OpenTelemetry Python API を使って、 my.span スパンを現在のスパンとして作成し、 start_as_current_span を使っています。そして、 OpenTelemetry Python API を使用して、新しいスパンに属性を持つイベントを追加します。

ハンドラーの実行が完了する前にスパンが終了しない限り、イベントデータはイベントテーブルに取り込まれません。この例では、 with ステートメントが終了すると、スパンが自動的に閉じられます。

CREATE OR REPLACE FUNCTION customSpansPythonExample() RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.12
PACKAGES = ('opentelemetry-api')
HANDLER = 'custom_spans_function'
AS $$
from snowflake import telemetry
from opentelemetry import trace

def custom_spans_function():
  tracer = trace.get_tracer("my.tracer")
  with tracer.start_as_current_span("my.span") as span:
    span.add_event("Event2 in custom span", {"key1": "value1", "key2": "value2"})

  return "success"
$$;