Emissão de eventos de rastreamento no Snowflake Scripting¶
Você pode usar as funções SYSTEM do Snowflake para emitir eventos de rastreamento de um manipulador de função ou procedimento escrito no Script Snowflake.
Antes de emitir eventos de rastreamento, certifique-se de que o nível de rastreamento esteja definido para que os dados desejados sejam armazenados na tabela de eventos. Para obter mais informações, consulte Definição de níveis para registro, métricas e rastreamento.
Nota
Antes de começar a emitir eventos de rastreamento, você deve configurar uma tabela de eventos. Para obter mais informações, consulte Visão geral da tabela de evento.
Você pode acessar os dados de eventos de rastreamento armazenados executando um comando SELECT na tabela de eventos. Para obter mais informações, consulte Visualização dos dados de rastreamento.
Para obter informações gerais sobre como configurar o registro e recuperar mensagens no Snowflake, consulte Eventos de rastreamento para funções e procedimentos.
Nota
Para obter diretrizes a serem lembradas ao adicionar eventos de rastreamento, consulte Diretrizes gerais para adicionar eventos de rastreamento.
Adição de eventos de rastreamento¶
Você pode adicionar eventos de rastreamento chamando a função SYSTEM$ADD_EVENT, passando um nome para o evento. Opcionalmente, você também pode associar atributos (pares chave-valor) a um evento.
O código no exemplo a seguir adiciona dois eventos, SProcEmptyEvent e SProcEventWithAttributes. Com SProcEventWithAttributes, o código também adiciona dois atributos: key1 e key2.
SYSTEM$ADD_EVENT('SProcEmptyEvent');
SYSTEM$ADD_EVENT('SProcEventWithAttributes', {'key1': 'value1', 'key2': 'value2'});
A adição desses eventos resulta em duas linhas na tabela de eventos, cada uma com um valor diferente na coluna RECORD:
{
"name": "SProcEmptyEvent"
}
{
"name": "SProcEventWithAttributes"
}
A linha de evento SProcEventWithAttributes inclui os seguintes atributos na coluna RECORD_ATTRIBUTES da linha:
{
"key1": "value1",
"key2": "value2"
}
Adição de atributos de span¶
Você pode definir atributos (pares chave-valor) associados aos spans chamando a função SYSTEM$SET_SPAN_ATTRIBUTES.
Para obter mais detalhes sobre spans, consulte Como o Snowflake representa eventos de rastreamento.
A função SYSTEM$SET_SPAN_ATTRIBUTES está disponível no seguinte formato:
SYSTEM$SET_SPAN_ATTRIBUTES(<object>);
onde
objecté um objeto do Snowflake Scripting com pares chave-valor que especificam os atributos desse evento de rastreamento.
O código no exemplo a seguir cria dois atributos e define seus valores:
SYSTEM$SET_SPAN_ATTRIBUTES('{'attr1':'value1', 'attr2':true}');
A configuração desses atributos resulta no seguinte na coluna RECORD_ATTRIBUTES da tabela de eventos:
{
"attr1": "value1",
"attr2": "value2"
}
Exemplos¶
O código no exemplo a seguir usa a função SYSTEM$ADD_EVENT para adicionar um evento chamado name_a e um evento chamado name_b. Com name_b, ele associa dois atributos, score e pass. O código também usa SYSTEM$SET_SPAN_ATTRIBUTES para definir dois atributos para o span, key1 e 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();
Emissão automática de eventos de rastreamento para trabalhos secundários e exceções¶
Você pode emitir automaticamente os seguintes tipos adicionais de eventos de rastreamento para um procedimento armazenado do Snowflake Scripting na tabela de eventos:
Captura de exceções.
Informações sobre a execução do trabalho filho.
Estatísticas do trabalho filho.
Estatísticas de procedimento armazenado, incluindo tempo de execução e valores de entrada.
A emissão automática de rastreamentos é destinada aos seguintes casos de uso:
Você deseja emitir eventos de rastreamento predefinidos sem modificar o corpo do procedimento armazenado.
Você deseja coletar informações sobre a execução de procedimentos armazenados que possam ser analisadas posteriormente, inclusive:
Informações sobre a execução do trabalho filho (como
childJobUUID,rowCount,exceptionCodee assim por diante).Tempo de execução do trabalho filho.
Valores dos argumentos de entrada.
Você deseja ter mais visibilidade da execução do procedimento armazenado para facilitar o desenvolvimento e a depuração sem adicionar manualmente o código de rastreamento no procedimento.
Para emitir automaticamente esses eventos de rastreamento adicionais para um procedimento armazenado, defina o parâmetro AUTO_EVENT_LOGGING como TRACING ou ALL usando o comando ALTER PROCEDURE. Quando você define esse parâmetro como ALL, mensagens adicionais de log também são geradas automaticamente para o procedimento armazenado.
Importante
As informações adicionais são adicionadas à tabela de eventos somente se o TRACE_LEVEL efetivo estiver definido como ALWAYS ou ON_EVENT. Para obter mais informações, consulte Definição de níveis para registro, métricas e rastreamento.
Por exemplo, crie uma tabela simples e insira os dados:
CREATE OR REPLACE TABLE test_auto_event_logging (id INTEGER, num NUMBER(12, 2));
INSERT INTO test_auto_event_logging (id, num) VALUES
(1, 11.11),
(2, 22.22);
Em seguida, crie um procedimento armazenado chamado auto_event_logging_sp. Esse procedimento armazenado de exemplo atualiza uma linha da tabela e, em seguida, consulta a tabela:
CREATE OR REPLACE PROCEDURE auto_event_logging_sp(
table_name VARCHAR,
id_val INTEGER,
num_val NUMBER(12, 2))
RETURNS TABLE()
LANGUAGE SQL
AS
$$
BEGIN
UPDATE IDENTIFIER(:table_name)
SET num = :num_val
WHERE id = :id_val;
LET res RESULTSET := (SELECT * FROM IDENTIFIER(:table_name) ORDER BY id);
RETURN TABLE(res);
EXCEPTION
WHEN statement_error THEN
res := (SELECT :sqlcode sql_code, :sqlerrm error_message, :sqlstate sql_state);
RETURN TABLE(res);
END;
$$
;
Os exemplos a seguir definem o parâmetro AUTO_EVENT_LOGGING para o procedimento armazenado:
ALTER PROCEDURE auto_event_logging_sp(VARCHAR, INTEGER, NUMBER)
SET AUTO_EVENT_LOGGING = 'TRACING';
ALTER PROCEDURE auto_event_logging_sp(VARCHAR, INTEGER, NUMBER)
SET AUTO_EVENT_LOGGING = 'ALL';
Chame o procedimento armazenado:
CALL auto_event_logging_sp('test_auto_event_logging', 2, 44.44);
+----+-------+
| ID | NUM |
|----+-------|
| 1 | 11.11 |
| 2 | 44.44 |
+----+-------+
Consulte na tabela de eventos os dados de rastreamento registrados pelo procedimento armazenado denominado auto_event_logging_sp. Para cada evento de rastreamento, imprima o carimbo de data/hora, o nome e os atributos do evento.
SELECT
TIMESTAMP as time,
RECORD['name'] as event_name,
RECORD_ATTRIBUTES as attributes,
FROM
my_db.public.my_events
WHERE
RESOURCE_ATTRIBUTES['snow.executable.name'] LIKE '%AUTO_EVENT_LOGGING_SP%'
AND RECORD_TYPE LIKE 'SPAN%';
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+
| TIME | EVENT_NAME | ATTRIBUTES |
|-------------------------+--------------------------+-----------------------------------------------------------------------------------------------|
| 2024-10-25 20:48:49.844 | "snow.auto_instrumented" | { |
| | | "childJobTime": 474, |
| | | "executionTime": 2, |
| | | "inputArgumentValues": "{ ID_VAL: 2, TABLE_NAME: test_auto_event_logging, NUM_VAL: 44.44 }" |
| | | } |
| 2024-10-25 20:48:49.740 | "child_job" | { |
| | | "childJobUUID": "01b7ef00-0003-01d1-0000-a99501233092", |
| | | "rowCount": 1, |
| | | "rowsAffected": 1 |
| | | } |
| 2024-10-25 20:48:49.843 | "child_job" | { |
| | | "childJobUUID": "01b7ef00-0003-01d1-0000-a99501233096", |
| | | "rowCount": 2, |
| | | "rowsAffected": 0 |
| | | } |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------+
Agora, chame o procedimento armazenado, mas especifique uma tabela que não existe para causar uma exceção:
CALL auto_event_logging_sp('no_table', 2, 82.44);
+----------+-----------------------------------------------------+-----------+
| SQL_CODE | ERROR_MESSAGE | SQL_STATE |
|----------+-----------------------------------------------------+-----------|
| 2003 | SQL compilation error: | 42S02 |
| | Object 'NO_TABLE' does not exist or not authorized. | |
+----------+-----------------------------------------------------+-----------+
Execute a consulta na tabela de eventos novamente para ver as informações sobre a exceção:
SELECT
TIMESTAMP as time,
RECORD['name'] as event_name,
RECORD_ATTRIBUTES as attributes,
FROM
my_db.public.my_events
WHERE
RESOURCE_ATTRIBUTES['snow.executable.name'] LIKE '%AUTO_EVENT_LOGGING_SP%'
AND RECORD_TYPE LIKE 'SPAN%';
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+
| TIME | EVENT_NAME | ATTRIBUTES |
|-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------|
| 2024-10-25 20:52:43.633 | "snow.auto_instrumented" | { |
| | | "childJobTime": 66, |
| | | "executionTime": 4, |
| | | "inputArgumentValues": "{ ID_VAL: 2, TABLE_NAME: no_table, NUM_VAL: 82.44 }" |
| | | } |
| 2024-10-25 20:52:43.601 | "caught_exception" | { |
| | | "exceptionCode": 2003, |
| | | "exceptionMessage": "SQL compilation error:\nObject 'NO_TABLE' does not exist or not authorized." |
| | | } |
+-------------------------+--------------------------+-----------------------------------------------------------------------------------------------------+