Emitting trace events in Python¶

Adding support for the telemetry package¶

To use telemetry package, you must make the open source Snowflake telemetry package (https://github.com/snowflakedb/snowflake-telemetry-python), which is included with Snowflake, available to your handler code. The package is available from the Anaconda Snowflake channel (https://repo.anaconda.com/pkgs/snowflake).

• For a procedure or function. In the PACKAGES clause in your CREATE PROCEDURE or CREATE FUNCTION statement, include the snowflake-telemetry-python package. The PACKAGES clause makes the included Snowflake telemetry package available to your code.

• For a Streamlit app. You can add the snowflake-telemetry-python package to your app by using Snowsight or an environment.yml. file.

  Code in the following example uses the PACKAGES clause to reference the telemetry package as well as the Snowpark library (which is required for stored procedures written in Python – for more information, see Writing stored procedures in Python).

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

  Copy

• Import the telemetry package in your code.

  from snowflake import telemetry
  

  Copy

Adding trace events¶

You can add trace events by calling the telemetry.add_event method, passing a name for the event. You can also optionally associate attributes – key-value pairs – with an event.

The add_event method is available in the following form:

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

where

• name is a Python string that specifies the name of the trace event.

• attributes is an OpenTelemetry Attributes object (https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-api/src/opentelemetry/util/types.py) that specifies the attributes for this trace event. This argument is optional. Omit the argument if you do not have any attributes to specify for this trace event.

Handler code in the following example adds two events, FunctionEmptyEvent and FunctionEventWithAttributes. With FunctionEventWithAttributes, the code also adds two attributes: key1 and key2.

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

Adding these events results in two rows in the event table, each with a different value in the RECORD column:

{
  "name": "FunctionEmptyEvent"
}

{
  "name": "FunctionEventWithAttributes"
}

The FunctionEventWithAttributes event row includes the following attributes in the row’s RECORD_ATTRIBUTES column:

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

Adding span attributes¶

You can set attributes – key-value pairs – associated with spans by calling the telemetry.set_span_attribute method.

For details on spans, see How Snowflake represents trace events.

The set_span_attribute method is available in the following form:

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

where:

• key is a Python string that specifies the key for an attribute.

• value is an OpenTelemetry AttributeValue object (https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-api/src/opentelemetry/util/types.py) that specifies the value of the attribute.

Code in the following example creates four attributes and sets their values:

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

Setting these attributes results in the following in the event table’s RECORD_ATTRIBUTES column:

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

Adding custom spans¶

You can add custom spans that are separate from the default span created by Snowflake. For details on custom spans, see Adding custom spans to a trace.

Code in the following example uses the OpenTelemetry Python API (https://opentelemetry-python.readthedocs.io/en/latest/api/index.html) to create the my.span span as the current span with start_as_current_span. It then adds an event with attributes to the new span using the OpenTelemetry Python API (https://opentelemetry-python.readthedocs.io/en/latest/api/index.html).

Event data won’t be captured by the event table unless the span ends before your handler completes execution. In this example, closing the span happens automatically when the with statement concludes.

CREATE OR REPLACE FUNCTION customSpansPythonExample() RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.9
PACKAGES = ('snowflake-telemetry-python', '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 examples¶

The following sections provide examples of adding support for trace events from Python code.

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"
$$;

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
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
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
PACKAGES=('snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
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;