Pythonでのトレースイベントの出力¶

Snowflake telemetry パッケージを使用すると、Pythonで記述された関数またはプロシージャハンドラーからトレースイベントを出力できます。このパッケージは、 Anaconda Snowflakeチャネルから入手できます。

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

注釈

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

Snowflakeでのログの設定とメッセージの取得に関する一般的な情報については、関数とプロシージャからのメッセージのログをご参照ください。

コードからログする前に、次を実行する必要があります。

ハンドラーコードからログされたメッセージを収集するイベントテーブルを設定します。

詳細については、イベントテーブルの設定をご参照ください。
必要なデータがイベントテーブルに格納されるようにトレースレベルが設定されていることを確認してください。

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

注釈

テレメトリパッケージのサポートの追加¶

テレメトリパッケージを使用するには、Snowflakeに含まれるオープンソースの Snowflakeテレメトリパッケージをハンドラーコードで利用できるようにする必要があります。このパッケージは、 Anaconda Snowflakeチャネルから入手できます。

CREATE PROCEDURE または CREATE FUNCTION ステートメントの PACKAGES 句に、 snowflake-telemetry-python パッケージを含めます。PACKAGES 句により、含まれているSnowflakeテレメトリパッケージがコードで使用できるようになります。

次の例のコードでは、 PACKAGES 句を使用してテレメトリパッケージとSnowparkライブラリ（Pythonで記述されたストアドプロシージャに必要です。詳細については、 Pythonでのストアドプロシージャの記述をご参照ください）を参照します。
```
CREATE OR REPLACE FUNCTION my_function(...)
  RETURNS ...
  LANGUAGE PYTHON
  ...
  PACKAGES = ('snowflake-telemetry-python')
  ...
```
Copy
ハンドラーコードに telemetry パッケージをインポートします。
```
from snowflake import telemetry
```
Copy

トレースイベントの追加¶

トレースイベントを追加するには、 telemetry.add_event メソッドを呼び出してイベントの名前を渡します。オプションで、属性（キーと値のペア）をイベントに関連付けることもできます。

add_event メソッドは次の形式で使用できます。

telemetry.add_event(<name>, <attributes>)

Copy

条件

name は、トレースイベントの名前を指定するPython文字列です。

attributes は、このトレースイベントの属性を指定する OpenTelemetry 属性オブジェクトです。この引数はオプションです。このトレースイベントに指定する属性がない場合は、引数を省略します。

次の例のハンドラーコードは、2つのイベント FunctionEmptyEvent と FunctionEventWithAttributes を追加します。 FunctionEventWithAttributes を使用すると、コードは2つの属性、 key1 と key2 も追加します。

telemetry.add_event("FunctionEmptyEvent")
telemetry.add_event("FunctionEventWithAttributes", {"key1": "value1", "key2": "value2"})

Copy

これらのイベントを追加すると、イベントテーブルに2つの行が作成され、それぞれの RECORD 列に異なる値が含まれます。

{
  "name": "FunctionEmptyEvent"
}

Copy

{
  "name": "FunctionEventWithAttributes"
}

Copy

FunctionEventWithAttributes イベント行には、行の RECORD_ATTRIBUTES 列に次の属性が含まれています。

{
  "key1": "value1",
  "key2": "value2"
}

Copy

スパン属性の追加¶

telemetry.set_span_attribute メソッドを呼び出すと、スパンに関連付けられた属性（キーと値のペア）を設定できます。

スパンの詳細については、 Snowflakeがトレースイベントを表す方法をご参照ください。

set_span_attribute メソッドは次の形式で使用できます。

telemetry.set_span_attribute(<key>, <value>)

Copy

条件:

key は、属性のキーを指定するPython文字列です。

value は、属性の値を指定する OpenTelemetry AttributeValue オブジェクトです。

次の例のコードは4つの属性を作成し、それらの値を設定します。

// Setting span attributes.
telemetry.set_span_attribute("example.boolean", true);
telemetry.set_span_attribute("example.long", 2);
telemetry.set_span_attribute("example.double", 2.5);
telemetry.set_span_attribute("example.string", "testAttribute");

Copy

これらの属性を設定すると、イベントテーブルの RECORD_ATTRIBUTES 列が次のようになります。

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

Copy

Pythonの例¶

次のセクションでは、Pythonのストアドプロシージャと関数にトレースイベントを追加する例を示します。

ストアドプロシージャの例¶

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

UDF の例¶

CREATE OR REPLACE FUNCTION times_two(x number)
RETURNS NUMBER
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION=3.8
HANDLER = 'times_two'
AS $$
from snowflake import telemetry
def times_two(x):
  telemetry.set_span_attribute("example.func.times_two", "begin")
  telemetry.add_event("event_without_attributes")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})

  response = 2 * x

  telemetry.set_span_attribute("example.func.times_two.response", response)

  return response
$$;

Copy

入力行を処理するPython関数からトレースイベント API を呼び出すと、 UDF によって処理される すべての行 に対して API が呼び出されます。

たとえば、次のステートメントは、前の例で50行に対して定義されたPython関数を呼び出し、その結果、100個のトレースイベント（各行に2つ）が生成されます。

select count(times_two(seq8())) from table(generator(rowcount => 50));

Copy

UDTF の例¶

CREATE OR REPLACE FUNCTION digits_of_number(input number)
RETURNS TABLE(result number)
LANGUAGE PYTHON
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION=3.8
HANDLER = 'TableFunctionHandler'
AS $$
from snowflake import telemetry

class TableFunctionHandler:

  def __init__(self):
    telemetry.add_event("test_udtf_init")

  def process(self, input):
    telemetry.add_event("test_udtf_process", {"input": str(input)})
    response = input

    while input > 0:
      response = input % 10
      input /= 10
      yield (response,)

  def end_partition(self):
    telemetry.add_event("test_udtf_end_partition")
$$;

Copy

UDTF ハンドラークラスの process() メソッドでトレースイベント API を呼び出すと、処理される すべての行 に対して API が呼び出されます。

たとえば、次のステートメントは、前の例で50行に対して定義された process() メソッドを呼び出します。その結果、 process() メソッドによって追加された100個のトレースイベント（各行に2つ）が生成されます。

select * from table(generator(rowcount => 50)), table(digits_of_number(seq8())) order by 1;

Copy