Captura de mensagens de exceções não tratadas¶

Você pode ter exceções não tratadas em manipuladores de procedimento e UDF registrados automaticamente como log ou rastreamento em uma tabela de eventos. A captura dessas mensagens não requer a inclusão de código de manipulador específico para criação de log ou rastreamento.

Nota

Atualmente, esse recurso é compatível com código de manipulador escrito apenas em Java ou Python.

Importante

As mensagens de erro podem conter informações confidenciais. Antes de ativar esse recurso, considere se deseja que informações potencialmente confidenciais sejam capturadas em uma tabela de eventos. Para saber mais, consulte Proteção de dados confidenciais.

Habilitação de captura de entradas de exceção não tratadas¶

Para ativar a captura de mensagens de exceções não tratadas, faça o seguinte:

Configure uma tabela de eventos conforme descrito em Configuração de uma tabela de eventos.
Ajuste o parâmetro ENABLE_UNHANDLED_EXCEPTIONS_REPORTING para true.

Para obter mais informações sobre como definir parâmetros, consulte Gerenciamento de parâmetros.
Defina o nível de log ou rastreamento para que o Snowflake capture entradas para exceções não tratadas. Você pode capturar entradas como entradas de log, entradas de eventos de rastreamento ou ambas.
1. Para capturar mensagens como entradas de log, defina o nível de registro em log como ERROR ou mais detalhado.
2. Para capturar mensagens como entradas de eventos de rastreamento, defina o nível de rastreamento como ALWAYS ou ON_EVENT.

Dados capturados para exceções não tratadas¶

Conforme descrito em Habilitação de captura de entradas de exceção não tratadas, você pode capturar dados de mensagens como uma entrada de log, um evento de rastreamento ou ambos. Os dados capturados serão diferentes entre entradas de eventos de log e de rastreamento.

Dados capturados em uma entrada de log¶

Quando você ativa a captura de exceções não tratadas como mensagens de log, o Snowflake registra o seguinte na tabela de eventos:

Coluna	Dados
Coluna RECORD	Um atributo `severity_text` cujo valor é o nível de erro de maior gravidade para o ambiente de execução da linguagem atual. Por exemplo, para um manipulador escrito em Python, o valor é `FATAL`.
Coluna RECORD_ATTRIBUTES	Os atributos a seguir são registrados para uma exceção não tratada. `exception.message` – A mensagem de erro. `exception.type` – O nome da classe de exceção. `exception.stacktrace` – O rastreamento de pilha da exceção formatado por um tempo de execução de linguagem. `exception.escaped` – `true` se esta entrada for de uma exceção não tratada.
Coluna VALUE	A cadeia de caracteres `exception`.

Coluna

Dados

Coluna RECORD

Um atributo severity_text cujo valor é o nível de erro de maior gravidade para o ambiente de execução da linguagem atual. Por exemplo, para um manipulador escrito em Python, o valor é FATAL.

Coluna RECORD_ATTRIBUTES

Os atributos a seguir são registrados para uma exceção não tratada.

exception.message – A mensagem de erro.
exception.type – O nome da classe de exceção.
exception.stacktrace – O rastreamento de pilha da exceção formatado por um tempo de execução de linguagem.
exception.escaped – true se esta entrada for de uma exceção não tratada.

Coluna VALUE

A cadeia de caracteres exception.

Exemplo¶

O código no exemplo a seguir consulta uma tabela de eventos em busca de dados de log registrados para uma exceção não tratada de um manipulador de UDF.

Para obter mais informações sobre como consultar dados de log em uma tabela de eventos, consulte Acesso a dados de mensagens registradas.

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

A seguir está a saída possível da consulta.

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

Dados capturados em uma entrada de evento de rastreamento¶

Quando você ativa a captura de exceções não tratadas como eventos de rastreamento, o Snowflake registra o seguinte na tabela de eventos:

Coluna	Dados
Coluna RECORD	Um atributo `name` cujo valor é `exception` e um atributo `status` cujo valor é `STATUS_CODE_ERROR`.
Coluna RECORD_ATTRIBUTES	Os atributos a seguir são registrados para uma exceção não tratada. `exception.message` – A mensagem de erro. `exception.type` – O nome da classe de exceção. `exception.stacktrace` – O rastreamento de pilha da exceção formatado por um tempo de execução de linguagem. `exception.escaped` – `true` se esta entrada for de uma exceção não tratada.

Coluna

Dados

Coluna RECORD

Um atributo name cujo valor é exception e um atributo status cujo valor é STATUS_CODE_ERROR.

Coluna RECORD_ATTRIBUTES

Os atributos a seguir são registrados para uma exceção não tratada.

exception.message – A mensagem de erro.
exception.type – O nome da classe de exceção.
exception.stacktrace – O rastreamento de pilha da exceção formatado por um tempo de execução de linguagem.
exception.escaped – true se esta entrada for de uma exceção não tratada.

Exemplos¶

O código nos exemplos a seguir consulta uma tabela de eventos para obter dados de eventos de rastreamento registrados para uma exceção não tratada de um manipulador de UDF.

Para obter mais informações sobre como consultar dados de eventos de rastreamento em uma tabela de eventos, consulte Acesso a dados de rastreamento.

Exemplo de span¶

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

A seguir está a saída possível da consulta.

-----------------------
| SPAN_STATUS         |
-----------------------
| "STATUS_CODE_ERROR" |
-----------------------

Exemplo de evento de span¶

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

A seguir está a saída possível da consulta.

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

Proteção de dados confidenciais¶

Dado que as mensagens de log e rastreamento de exceções não tratadas podem incluir dados confidenciais, considere fazer o seguinte para proteger esses dados:

Desative o registro de exceções não tratadas definindo o parâmetro ENABLE_UNHANDLED_EXCEPTIONS_REPORTING como false.
Tome medidas para proteger dados confidenciais, fazendo o seguinte:
- Melhore seu código de tratamento de exceções para minimizar o risco de exceções não tratadas.
- Aplique políticas de acesso a linhas à sua tabela de eventos para restringir o acesso a linhas que contenham informações de identificação pessoal (PII).
- Crie uma exibição na parte superior da tabela de eventos e aplique políticas de mascaramento a ela para mascarar ou excluir informações de identificação pessoal (PII).