関数とプロシージャのイベントをトレースする¶

Snowpark APIs を使用して記述したイベントを含め、プロシージャ UDF または UDTF のハンドラーコードからトレースイベントを出力できます。サポートされているハンドラー言語のリストについては、サポートされている言語をご参照ください。

トレースイベントは、システムまたはアプリケーションで何かが発生したときにキャプチャできるテレメトリデータの一種（ログメッセージ等）です。ログメッセージとは異なり、トレースイベントには構造化されたペイロードがあるため、データ分析に適しています。たとえば、トレースイベントを使用して、関数の実行中に計算された数値をキャプチャし、後でこれらの数値を分析できます。

プロシージャまたは UDF では、トレースイベントの一部としてキャプチャされる属性（キーと値のペア）を関連付けることができます。たとえば、トレースイベントのパラメーターの名前と値をキャプチャする場合は、 parameters という名前のトレースイベントを追加し、パラメーターの名前と値をイベントの属性として設定できます。

プロシージャまたは関数が正常に実行されると、Snowflakeは追加されたトレースイベントを出力します。Snowflakeは、アカウントに関連付けられたアクティブイベントテーブルでこれらのトレースイベントを利用できるようにします。イベントテーブルの説明については、イベントテーブルの設定をご参照ください。

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

トレースの例¶

次の例のPythonコードは、スパンに example.proc.do_tracing 属性を値 begin で設定します。また、スパン内で、 example.key1 および example.key2 属性を持つ event_with_attributes イベントを出力します。

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION=3.8
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
  telemetry.set_span_attribute("example.proc.do_tracing", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  return "SUCCESS"
$$;

Copy

はじめるにあたり¶

ハンドラーコードからイベントトレースを開始するには、次の高レベルのステップに従います。

イベントテーブルを設定します。

Snowflakeは、イベントテーブルを使用して、ハンドラーコードによって出力されたイベントデータを格納します。イベントテーブルには、 Snowflakeによって事前定義された列があります。
使用するハンドラー言語のイベントトレース API について理解を深めます。

ハンドラー言語のリストについては、サポートされている言語を参照してから、言語からトレースイベントを出力する方法に関するコンテンツを表示します。
イベントトレースコードをハンドラーに追加します。
イベントテーブルからイベントトレースデータを取得する方法を学習します。

トレースイベントのレベル¶

トレースレベルを設定すると、イベントテーブルに格納されたトレースイベントデータの冗長性を管理できます。トレースする前に、この設定を使用して、ログメッセージの重大度を取得していることを確認してください。イベントデータがテーブルに書き込まれていないことがわかった場合は、トレースレベルをチェックして、必要なデータが許可されていることを確認してください。

詳細については、トレースレベルの設定をご参照ください。

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

次の言語で記述された関数およびプロシージャハンドラーコードからイベントをトレースできます。これには、ハンドラーコードが Snowpark APIs で記述されている場合も含まれます。

言語/型	Java	Python	JavaScript	Scala	Snowflakeスクリプト
ストアドプロシージャ	✔	✔	✔	✔	✔
Scalar UDFs	✔	✔	✔	✔
UDTFs	✔	✔	✔	✔ *

*: Snowparkで記述されたScala UDTF ハンドラー。

ハンドラーコードからのイベントトレース¶

イベントトレースのために、使用しているハンドラーコード用に設計されたSnowflakeが提供するライブラリを使用できます。Snowflakeはトレースイベントをインターセプトし、作成したイベントテーブルに格納します。

次のテーブルに、ログでサポートされているハンドラー言語と、コードからのログに関するコンテンツへのリンクを示します。

言語	テレメトリライブラリ	ドキュメント
Java	Snowflake `Telemetry` クラス。	Javaでのトレースイベントの出力
JavaScript	Snowflake JavaScriptAPI。	JavaScript でのトレースイベントの出力
Python	Snowflake `telemetry` パッケージ。	Pythonでのトレースイベントの出力
Scala	Snowflake `Telemetry` クラス。	Scalaでのトレースイベントの出力
Snowflakeスクリプト	Snowflake SQL 関数。	Snowflakeスクリプトでのトレースイベントの出力

トレースイベントを追加するための一般的なガイドライン¶

トレースイベント APIs を呼び出してトレースイベントを追加し、スパン属性を設定する場合は、次の点に注意してください。

スパンは、最大128個のトレースイベントと最大128個のスパン属性を保持できます。
前に追加したイベントと同じ名前のトレースイベントを追加すると、新しいイベント記録が作成されます。
前に設定したスパン属性と同じキーを持つスパン属性を設定すると、そのキーの値は上書きされます。

イベントデータアクセス¶

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