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.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"
$$;
Getting started¶
To get started with event traces from handler code, follow these high-level steps:
-
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 |
|
JavaScript |
Snowflake JavaScript API. |
|
Python |
Snowflake |
|
Scala |
Snowflake |
|
Snowflake Scripting |
Snowflake SQL functions. |
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.