Emitting trace events in Snowflake Scripting¶
You can use the Snowflake SYSTEM
functions to emit trace events from a function or procedure handler written in Snowflake Scripting.
Before emitting trace events, be sure you have the trace level set so that the data you want are stored in the event table. For more information, refer to Setting trace level.
Note
Before you can begin emitting trace events, you must set up an event table. For more information, refer to Setting up an event table.
You can access stored trace event data by executing a SELECT command on the event table. For more information, refer to Accessing trace data.
For general information about setting up logging and retrieving messages in Snowflake, refer to Trace events for functions and procedures.
Note
For guidelines to keep in mind when adding trace events, refer to General guidelines for adding trace events.
Adding trace events¶
You can add trace events by calling the SYSTEM$ADD_EVENT (for Snowflake Scripting) function, passing a name for the event. You can also optionally associate attributes – key-value pairs – with an event.
Code in the following example adds two events, SProcEmptyEvent
and SProcEventWithAttributes
. With
SProcEventWithAttributes
, the code also adds two attributes: key1
and key2
.
SYSTEM$ADD_EVENT('SProcEmptyEvent');
SYSTEM$ADD_EVENT('SProcEventWithAttributes', {'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": "SProcEmptyEvent"
}
{
"name": "SProcEventWithAttributes"
}
The SProcEventWithAttributes
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 SYSTEM$SET_SPAN_ATTRIBUTES function.
For details on spans, see How Snowflake represents trace events.
The SYSTEM$SET_SPAN_ATTRIBUTES (for Snowflake Scripting) function is available in the following form:
SYSTEM$SET_SPAN_ATTRIBUTES(<object>);
where
object
is a Snowflake Scripting object with key-value pairs that specifies the attributes for this trace event.
Code in the following example creates four attributes and sets their values:
SYSTEM$SET_SPAN_ATTRIBUTES('{'attr1':'value1', 'attr2':true}');
Setting these attributes results in the following in the event table’s RECORD_ATTRIBUTES column:
{
"attr1": "value1",
"attr2": "value2"
}
Examples¶
Code in the following example uses the SYSTEM$ADD_EVENT function to add an event named name_a
and an event named name_b
.
With name_b
, it associates two attributes, score
and pass
. The code also uses SYSTEM$SET_SPAN_ATTRIBUTES to
set two attributes for the span, key1
and key2
.
CREATE OR REPLACE PROCEDURE pi_proc()
RETURNS DOUBLE
LANGUAGE SQL
AS $$
BEGIN
-- Add an event without attributes
SYSTEM$ADD_EVENT('name_a');
-- Add an event with attributes
LET attr := {'score': 89, 'pass': TRUE};
SYSTEM$ADD_EVENT('name_b', attr);
-- Set attributes for the span
SYSTEM$SET_SPAN_ATTRIBUTES({'key1': 'value1', 'key2': TRUE});
RETURN 3.14;
END;
$$;
CALL pi_proc();