Capturing messages from unhandled exceptions

You can have unhandled exceptions in procedure and UDF handlers automatically recorded as log or trace messages in an event table. Capturing these messages does not require that you add handler code specific to logging or tracing.

Note

This feature is currently supported for handler code written only in Python.

Important

Error messages can contain sensitive information. Before enabling this feature, consider whether you want potentially sensitive information captured in an event table. To learn more, see Protecting sensitive data.

Enable capture of unhandled exception entries

To enable capture of messages from unhandled exceptions, do the following:

  1. Set up an event table as described in Setting up an Event Table.

  2. Set the ENABLE_UNHANDLED_EXCEPTIONS_REPORTING parameter to true.

    For more on setting parameters, see Parameter Management.

  3. Set log or trace level so that Snowflake captures entries for unhandled exceptions. You can have entries captured as log entries, trace event entries, or both.

    1. To capture messages as log entries, set the log level to ERROR or more verbose.

    2. To capture messages as trace event entries, set the trace level to ALWAYS or ON_EVENT.

Data captured for unhandled exceptions

As described in Enable capture of unhandled exception entries, you can capture message data as a log entry, a trace event, or both. The captured data will differ between log and trace event entries.

Data captured in a log entry

When you have enabled unhandled exceptions to be captured as log messages, Snowflake records the following in the event table:

Column

Data

RECORD column

A severity_text attribute whose value is the highest-severity error level for the current language runtime. For example, for a handler written in Python, the value is FATAL.

RECORD_ATTRIBUTES column

The following attributes are recorded for an unhandled exception.

  • exception.message – The error message.

  • exception.type – The name of the exception’s class.

  • exception.stacktrace – The exception’s stack trace formatted by a language runtime.

  • exception.escaped – true if this entry is from an unhandled exception.

VALUE column

The string exception.

Example

Code in the following example queries an event table for log data recorded for an unhandled exception from a UDF handler.

For more about querying an event table for log data, see Accessing Logged Message Data.

SET event_table_name = 'my_db.public.my_event_table';

SELECT
  RECORD['severity_text'] AS severity,
  RECORD_ATTRIBUTES['exception.message'] AS error_message,
  RECORD_ATTRIBUTES['exception.type'] AS exception_type,
  RECORD_ATTRIBUTES['exception.stacktrace'] AS stacktrace
FROM
  my_event_table
WHERE
  RECORD_TYPE = 'LOG';
Copy

The following is possible output from the query.

------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| SEVERITY | ERROR_MESSAGE                                        | EXCEPTION_TYPE | STACKTRACE                                                                                                                                          |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| "FATAL"  | "could not convert string to float: '$1,000,000.00'" | "ValueError"   | "Traceback (most recent call last):\n  File \"_udf_code.py\", line 6, in compute\nValueError: could not convert string to float: '$1,000,000.00'\n" |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Data captured in a trace event entry

When you have enabled unhandled exceptions to be captured as trace events, Snowflake records the following in the event table:

Column

Data

RECORD column

A name attribute whose value is exception and a status attribute whose value is STATUS_CODE_ERROR.

RECORD_ATTRIBUTES column

The following attributes are recorded for an unhandled exception.

  • exception.message – The error message.

  • exception.type – The name of the exception’s class.

  • exception.stacktrace – The exception’s stack trace formatted by a language runtime.

  • exception.escaped – true if this entry is from an unhandled exception.

Examples

Code in the following examples query an event table for trace event data recorded for an unhandled exception from a UDF handler.

For more about querying an event table for trace event data, see Accessing Trace Data.

Span example
SET event_table_name = 'my_db.public.my_event_table';

SELECT
  RECORD['status']['code'] AS span_status
FROM
  my_event_table
WHERE
  record_type = 'SPAN';
Copy

The following is possible output from the query.

-----------------------
| SPAN_STATUS         |
-----------------------
| "STATUS_CODE_ERROR" |
-----------------------
Span event example
SET event_table_name = 'my_db.public.my_event_table';

SELECT
  RECORD['name'] AS event_name,
  RECORD_ATTRIBUTES['exception.message'] AS error_message,
  RECORD_ATTRIBUTES['exception.type'] AS exception_type,
  RECORD_ATTRIBUTES['exception.stacktrace'] AS stacktrace
FROM
  my_event_table
WHERE
  RECORD_TYPE = 'SPAN_EVENT';
Copy

The following is possible output from the query.

-----------------------------------------------------------------------------------------------------------------------------------------
| EVENT_NAME  | ERROR_MESSAGE                                        | EXCEPTION_TYPE | STACKTRACE                                      |
-----------------------------------------------------------------------------------------------------------------------------------------
| "exception" | "could not convert string to float: '$1,000,000.00'" | "ValueError"   | "  File \"_udf_code.py\", line 6, in compute\n" |
-----------------------------------------------------------------------------------------------------------------------------------------

Protecting sensitive data

Given that log and trace messages from unhandled exceptions can include sensitive data, consider doing the following to protect that data:

  • Turn off unhandled exception logging by setting the ENABLE_UNHANDLED_EXCEPTIONS_REPORTING parameter to false.

  • Take steps to protect sensitive data, such as by doing the following:

    • Improve your exception handling code to minimize the risk of unhandled exceptions.

    • Apply row access policies to your event table to restrict access to rows that contain personally identifiable information (PII).

    • Create a view on top of the event table and apply masking policies to it to mask or delete personally identifiable information (PII).

Language: English