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

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

はじめるにあたり

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

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

    Snowflakeは、イベントテーブルを使用して、ハンドラーコードによって出力されたイベントデータを格納します。イベントテーブルには、 Snowflakeによって事前定義された列 があります。

  2. 使用するハンドラー言語のイベントトレース API について理解を深めます。

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

  3. イベントトレースコードをハンドラーに追加します。

  4. イベントテーブルから イベントトレースデータを取得する 方法を学習します。

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

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

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

サポートされている言語

次の言語で記述された関数およびプロシージャハンドラーコードからイベントをトレースできます。これには、ハンドラーコードが 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 コマンドを実行すると、データにもアクセスできます。詳細については、 トレースデータへのアクセス をご参照ください。