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'});

Copy

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

{
  "name": "SProcEmptyEvent"
}

Copy

{
  "name": "SProcEventWithAttributes"
}

Copy

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

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

Copy

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

Copy

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}');

Copy

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

{
  "attr1": "value1",
  "attr2": "value2"
}

Copy

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

Copy

CALL pi_proc();

Copy