関数とプロシージャのイベントをトレースする¶
Snowpark APIs を使用して 記述したイベントを含め、プロシージャ UDF または UDTF のハンドラーコードからトレースイベントを出力できます。サポートされているハンドラー言語のリストについては、 サポートされている言語 をご参照ください。
注釈
トレースイベントデータを収集する前に、 テレメトリデータ収集を有効にする 必要があります。コードにインスツルメンテーションを行う 場合、Snowflake はデータを生成し、イベントテーブルに収集します。
トレースイベントは、システムまたはアプリケーションで何かが発生したときにキャプチャできるテレメトリデータの一種（ログメッセージ等）です。ログメッセージとは異なり、トレースイベントには構造化されたペイロードがあるため、データ分析に適しています。たとえば、トレースイベントを使用して、関数の実行中に計算された数値をキャプチャし、後でこれらの数値を分析できます。
プロシージャまたは UDF では、トレースイベントの一部としてキャプチャされる属性（キーと値のペア）を関連付けることができます。たとえば、トレースイベントのパラメーターの名前と値をキャプチャする場合は、 parameters という名前のトレースイベントを追加し、パラメーターの名前と値をイベントの属性として設定できます。
プロシージャまたは関数が正常に実行されると、Snowflakeは追加されたトレースイベントを出力します。Snowflakeは、アカウントに関連付けられたアクティブイベントテーブルでこれらのトレースイベントを利用できるようにします。イベントテーブルの説明については、 イベントテーブルの概要 をご参照ください。
トレースイベントデータにアクセスし 、以下の方法で分析を行うことができます。
イベントテーブルで SELECT コマンドを実行する機能を付与します。
Snowsight でトレースエントリーを表示します。
トレースの例¶
次の例の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.9
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"
$$;
はじめるにあたり¶
ハンドラーコードからイベントトレースを開始するには、次の高レベルのステップに従います。
-
Snowflakeは、イベントテーブルを使用して、ハンドラーコードによって出力されたイベントデータを格納します。イベントテーブルには、 Snowflakeによって事前定義された列 があります。
使用するハンドラー言語のイベントトレース API について理解を深めます。
ハンドラー言語のリストについては、 サポートされている言語 を参照してから、 言語からトレースイベントを出力する方法に関するコンテンツ を表示します。
イベントトレースコードをハンドラーに追加します。
イベントテーブルから イベントトレースデータを取得する 方法を学習します。
トレースイベントのレベル¶
トレースレベルを設定すると、イベントテーブルに格納されたトレースイベントデータの冗長性を管理できます。トレースする前に、この設定を使用して、ログメッセージの重大度を取得していることを確認してください。イベントデータがテーブルに書き込まれていないことがわかった場合は、トレースレベルをチェックして、必要なデータをSnowflakeがキャプチャしていることを確認してください。
詳細については、 ロギング、メトリクス、トレースのレベル設定 をご参照ください。
サポートされている言語¶
次の言語で記述されたコードからイベントをトレースできます。これには、ハンドラーコードが Snowpark APIs で記述されている場合も含まれます。
言語/型 |
Java |
Python |
JavaScript |
Scala |
Snowflakeスクリプト |
|---|---|---|---|---|---|
ストアドプロシージャハンドラー |
✔ |
✔ |
✔ |
✔ |
✔ |
Streamlitアプリ |
✔ |
||||
UDF ハンドラー（スカラー関数） |
✔ |
✔ |
✔ |
✔ |
|
UDTF ハンドラー（テーブル関数） |
✔ |
✔ |
✔ |
✔ * |
- *:
Snowparkで記述されたScala UDTF ハンドラー。
ハンドラーコードからのイベントトレース¶
イベントトレースのために、使用しているハンドラーコード用に設計されたSnowflakeが提供するライブラリを使用できます。Snowflakeはトレースイベントをインターセプトし、作成したイベントテーブルに格納します。
次のテーブルに、ログでサポートされているハンドラー言語と、コードからのログに関するコンテンツへのリンクを示します。
言語 |
テレメトリライブラリ |
ドキュメント |
|---|---|---|
Java |
Snowflake |
|
JavaScript |
Snowflake JavaScriptAPI。 |
|
Python |
Snowflake |
|
Scala |
Snowflake |
|
Snowflakeスクリプト |
Snowflake SQL 関数。 |
SQL ステートメントトレース¶
デフォルトでは トレースが有効になっている 場合、Snowflakeは、ストアドプロシージャやユーザー定義関数のハンドラー内などの、他のトレース対象コードと組み合わせて実行される SQL ステートメントをトレースします。
デフォルトでは、Snowflakeは SQL を次のコンテキストでトレースします。
ストアドプロシージャ内で実行される SQL
ストアドプロシージャを実行する SQL
1つ以上のユーザー定義関数を実行する SQL
DBT が実行する SQL
Streamlit が実行する SQL
ノートブックが実行する SQL
コードコンテキストがPythonまたはGoコネクタの場合に、Snowpark Container Servicesで実行される SQL
以下はサポートされていないことに注意してください。
Snowflake Native App の SQL ステートメント
ワークシートまたはワークスペースでの SQL の直接実行
トレースされた SQL ステートメントについては、出力されたデータは、次の列などを含むイベントテーブル内にあります。
RESOURCE_ATTRIBUTES 列 で、
snow.executable.typeプロパティ値はQUERYです。RECORD 列 で、
nameプロパティ値は、SELECT、CALL、INSERT などの実行をトレースされた SQL ステートメントの型です。RECORD_ATTRIBUTES 列で、次のプロパティには SQL トレースに関連する値が含まれます。
db.query.table.namesdb.query.view.namesdb.query.executable.namesdb.query.text（有効な場合）
SQL テキスト自体（1024文字まで）をイベントテーブルにキャプチャされたトレースデータに含める必要があるかどうかを指定できます。SQL テキストに機密情報が含まれる可能性がある場合や、役に立たないと思われる場合は省略することもできます。
トレース時に SQL テキストをキャプチャするには、SQL_TRACE_QUERY_TEXT パラメーターを
"ON"に設定します（ACCOUNTADMIN ロールを使用してこのパラメーターを設定する必要があります）。
トレースイベントを追加するための一般的なガイドライン¶
トレースイベント APIs を呼び出してトレースイベントを追加し、スパン属性を設定する場合は、次の点に注意してください。
スパンは、最大128個のトレースイベントと最大128個のスパン属性を保持できます。
前に追加したイベントと同じ名前のトレースイベントを追加すると、新しいイベント記録が作成されます。
前に設定したスパン属性と同じキーを持つスパン属性を設定すると、そのキーの値は上書きされます。
収集したイベントデータの表示¶
トレースデータは、 Snowsight、またはトレースデータが保存されているイベントテーブルをクエリすることで表示することができます。詳細については、 トレースデータの表示 をご参照ください。