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

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

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

デフォルトでは、ストアドプロシージャや関数のPythonハンドラーを作成するときに、テレメトリパッケージが含まれます。ただし、特定のパッケージを明示的に許可または禁止するパッケージポリシーを指定している場合、Snowflakeは snowflake-telemetry-python パッケージを自動的に含めません。この場合は、 PACKAGES 句でパッケージを指定する必要があります。

• Streamlitアプリの場合。 Snowsight または environment.yml. ファイルを使用して、 snowflake-telemetry-python パッケージをアプリに追加できます。

  次の例のコードでは、 PACKAGES 句を使用してTelemetryパッケージとSnowparkライブラリ（Pythonで記述されたストアドプロシージャに必要です。詳細については、 SQL と Python を使ったストアドプロシージャの記述 参照）を参照します。

  CopyExpand

  CREATE OR REPLACE FUNCTION my_function(...)
    RETURNS ...
    LANGUAGE PYTHON
    ...
    PACKAGES = ('snowflake-telemetry-python')
    ...
  

  Show lessSee more

  Scroll to top

• コードに telemetry パッケージをインポートします。

  CopyExpand

  from snowflake import telemetry
  

  Show lessSee more

  Scroll to top

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

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

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

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

条件

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

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

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

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

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

{
  "name": "FunctionEmptyEvent"
}

{
  "name": "FunctionEventWithAttributes"
}

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

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

スパン属性の追加¶

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

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

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

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

条件:

• 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");

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

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

カスタムスパンの追加¶

Snowflakeが作成するデフォルトのスパンとは別に、カスタムスパンを追加することができます。カスタム・スパンの詳細については、 トレースへのカスタムスパンの追加 をご参照ください。

次の例のコードは、 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"
  $$;

Pythonの例¶

以下のセクションでは、Pythonコードからトレースイベントのサポートを追加する例を示します。

CREATE OR REPLACE PROCEDURE do_tracing()
  RETURNS VARIANT
  LANGUAGE PYTHON
  PACKAGES = ('snowflake-snowpark-python', 'snowflake-telemetry-python')
  RUNTIME_VERSION = 3.12
  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"
  $$;

import streamlit as st
from snowflake import telemetry

st.title("Streamlit trace event example")

hifives_val = st.slider("Number of high-fives", min_value=0, max_value=90, value=60)

if st.button("Submit"):
    telemetry.add_event("new_submission", {"high_fives": hifives_val})

CREATE OR REPLACE FUNCTION times_two(x NUMBER)
  RETURNS NUMBER
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.12
  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
$$;

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

CREATE OR REPLACE FUNCTION digits_of_number(input NUMBER)
  RETURNS TABLE(result NUMBER)
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.12
  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")
$$;

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