Trace events for functions and procedures¶

You can emit trace events from the handler code for a procedure, UDF, or UDTF, including those you write using Snowpark APIs. For a list of supported handler languages, see Supported languages.

Note

Before you can collect trace event data, you must enable telemetry data collection. When you instrument your code, Snowflake generates the data and collects it in an event table.

Trace events are a type of telemetry data (like log messages) that can capture when something has happened in the system or the application. Unlike log messages, trace events have a structured payload, which makes them a good choice for data analysis. For example, you can use trace events to capture some numbers that are calculated during the execution of your function, and analyze these numbers afterwards.

In a procedure or UDF, you can associate attributes (key-value pairs) that should be captured as part of the trace events. For example, if you want to capture the names and values of parameters in a trace event, you can add a trace event named parameters and set the names and values of the parameters as attributes of the event.

When a procedure or function executes successfully, Snowflake emits the trace events that were added. Snowflake makes these trace events available in the active event table associated with the account. For an explanation of event tables, see Event table overview.

You can access trace event data for analysis in the following ways:

Execute a SELECT command on the event table.
View trace entries in Snowsight.

Trace example¶

Python code in the following example sets a example.proc.do_tracing attribute on the span with a value of begin. It also emits within the span an event_with_attributes event with example.key1 and example.key2 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"
$$;

Copy

Getting started¶

To get started with event traces from handler code, follow these high-level steps:

Set up an event table.

Snowflake uses your event table to store event data emitted by your handler code. An event table has columns predefined by Snowflake.
Get acquainted with the event trace API for the handler language you’ll be using.

see Supported languages for a list of handler languages, then view content about how to emit trace events from your language.
Add event trace code to your handler.
Learn how to retrieve event trace data from the event table.

Level for trace events¶

You can manage the verbosity of trace event data stored in the event table by setting the trace level. Before tracing, use this setting to ensure that you’re capturing the log message severity. If you find that event data isn’t being written to the table, check the trace level to ensure that Snowflake is capturing the data you want.

For more information, see Setting levels for logging, metrics, and tracing.

Supported languages¶

You can trace events from code written in the following languages, including when handler code is written with Snowpark APIs.

Language / Type	Java	Python	JavaScript	Scala	Snowflake Scripting
Stored procedure handler	✔	✔	✔	✔	✔
Streamlit app		✔
UDF handler (scalar function)	✔	✔	✔	✔
UDTF handler (table function)	✔	✔	✔	✔ *

*:: Scala UDTF handler written in Snowpark.

Event tracing from handler code¶

To trace events, you can use a Snowflake-provided library designed for the handler code you’re using. Snowflake intercepts trace events and stores them in the event table you create.

The following table lists handler languages supported for logging, along with links to content on logging from code.

Language	Telemetry Library	Documentation
Java	Snowflake `Telemetry` class.	Emitting trace events in Java
JavaScript	Snowflake JavaScript API.	Emitting trace events in JavaScript
Python	Snowflake `telemetry` package.	Emitting trace events in Python
Scala	Snowflake `Telemetry` class.	Emitting trace events in Scala
Snowflake Scripting	Snowflake SQL functions.	Emitting trace events in Snowflake Scripting

General guidelines for adding trace events¶

When calling the trace event APIs to add trace events and set span attributes, note the following:

A span can hold a maximum number of 128 trace events and a maximum number of 128 span attributes.
If you add a trace event that has the same name as an event that you added earlier, a new event record is created.
If you set a span attribute that has the same key as a span attribute that you set earlier, the value for that key is overwritten.

Viewing collected event data¶

You can view trace data either through Snowsight or by querying the event table in which trace data is stored. For more information, see Viewing trace data.