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, refer to Supported Languages.

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, refer to Setting up an Event Table.

You can access trace event data by executing a SELECT command on the event table. For more information, refer to Accessing Trace Data.

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

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.

Refer to 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 make sure 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 it’s allowing the data you want.

For more information, refer to Setting Trace Level.

Supported Languages¶

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

Language / Type	Java	Python	JavaScript	Scala	Snowflake Scripting
Stored Procedures	✔	✔	✔	✔	✔
Scalar UDFs	✔	✔	✔	✔
UDTFs	✔	✔	✔	✔ *

*: 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.

Event Data Access¶

You can access even data by executing a SELECT command on the event table. For more information, refer to Accessing Trace Data.