Eventos de rastreamento para funções e procedimentos¶

Você pode emitir eventos de rastreamento do código do manipulador para um procedimento, UDF ou UDTF, incluindo aqueles que você escreve usando APIs Snowpark. Para obter uma lista de linguagens de manipulador compatíveis, consulte Linguagens compatíveis.

Nota

Antes de poder coletar dados de evento de rastreamento, é necessário habilitar a coleta de dados de telemetria. Quando você instrumenta seu código, o Snowflake gera os dados e os coleta em uma tabela de evento.

Os eventos de rastreamento são um tipo de dados de telemetria (como mensagens de registro) que podem capturar quando algo acontece no sistema ou no aplicativo. Ao contrário das mensagens de registro, os eventos de rastreamento têm uma carga útil estruturada, o que os torna uma boa opção para análise de dados. Por exemplo, você pode usar eventos de rastreamento para capturar alguns números que são calculados durante a execução da sua função e analisá-los posteriormente.

Em um procedimento ou UDF, você pode associar atributos (pares chave-valor) que devem ser capturados como parte dos eventos de rastreamento. Por exemplo, se quiser capturar os nomes e os valores dos parâmetros em um evento de rastreamento, você poderá adicionar um evento de rastreamento chamado parameters e definir os nomes e os valores dos parâmetros como atributos do evento.

Quando um procedimento ou função é executado com êxito, o Snowflake emite os eventos de rastreamento que foram adicionados. O Snowflake disponibiliza esses eventos de rastreamento na tabela de eventos ativa associada à conta. Para uma explicação das tabelas de evento, consulte Visão geral da tabela de evento.

É possível acessar dados de evento de rastreamento para análise das seguintes maneiras:

Execute um comando SELECT na tabela de evento.
Exibição de entradas de rastreamento em Snowsight.

Exemplo de rastreamento¶

O código Python no exemplo a seguir define um atributo example.proc.do_tracing no span com um valor de begin. Ele também emite dentro do span um evento event_with_attributes com atributos example.key1 e example.key2.

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
  telemetry.set_span_attribute("example.proc.do_tracing", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  return "SUCCESS"
$$;

Copy

Introdução¶

Para começar a usar os rastreamentos de eventos do código do manipulador, siga estas etapas de alto nível:

Configure uma tabela de eventos.

O Snowflake usa sua tabela de eventos para armazenar dados de eventos emitidos pelo seu código do manipulador. Uma tabela de eventos tem colunas predefinidas pelo Snowflake.
Familiarize-se com a API de rastreamento de eventos para a linguagem do manipulador que você usará.

Consulte Linguagens compatíveis para uma lista de linguagens de manipulador e, em seguida, visualize o conteúdo sobre como emitir eventos de rastreamento da sua linguagem.
Adicione o código de rastreamento de eventos ao seu manipulador.
Saiba como recuperar dados de rastreamento de eventos da tabela de eventos.

Nível para eventos de rastreamento¶

Você pode gerenciar o detalhamento dos dados de eventos de rastreamento armazenados na tabela de eventos definindo o nível de rastreamento. Antes de rastrear, use esta configuração para garantir que você esteja capturando a gravidade da mensagem de log. Se perceber que os dados do evento não estão sendo gravados na tabela, verifique o nível de rastreamento para garantir que o Snowflake esteja capturando os dados desejados.

Para obter mais informações, consulte Definição de níveis para registro, métricas e rastreamento.

Linguagens compatíveis¶

É possível rastrear eventos do código escrito nas seguintes linguagens, inclusive quando o código do manipulador é escrito com APIs Snowpark.

Linguagem / Tipo	Java	Python	JavaScript	Scala	Script Snowflake
Manipulador de procedimento armazenado	✔	✔	✔	✔	✔
Aplicativo Streamlit		✔
Manipulador de UDF (função escalar)	✔	✔	✔	✔
Manipulador de UDTF (função de tabela)	✔	✔	✔	✔ *

*:: Manipulador de UDTF Scala escrito em Snowpark.

Rastreamento de eventos a partir do código do manipulador¶

Para rastrear eventos, você pode usar uma biblioteca fornecida pelo Snowflake projetada para o código do manipulador que você está usando. O Snowflake intercepta eventos de rastreamento e os armazena na tabela de eventos que você cria.

A tabela a seguir lista as linguagens de manipulador compatíveis com o registro em log, juntamente com links para o conteúdo sobre o registro em log a partir do código.

Linguagem	Biblioteca de telemetria	Documentação
Java	Classe Snowflake `Telemetry`.	Emissão de eventos de rastreamento em Java
JavaScript	Snowflake JavaScriptAPI.	Emissão de eventos de rastreamento em JavaScript
Python	Pacote Snowflake `telemetry`.	Emissão de eventos de rastreamento em Python
Scala	Classe Snowflake `Telemetry`.	Emissão de eventos de rastreamento em Scala
Script Snowflake	Funções SQL Snowflake.	Emissão de eventos de rastreamento no Snowflake Scripting

Diretrizes gerais para adicionar eventos de rastreamento¶

Ao chamar as APIs de evento de rastreamento para adicionar eventos de rastreamento e definir atributos de span, observe o seguinte:

Um span pode conter um número máximo de 128 eventos de rastreamento e um número máximo de 128 atributos de span.
Se você adicionar um evento de rastreamento que tenha o mesmo nome de um evento adicionado anteriormente, será criado um novo registro de evento.
Se você definir um atributo span que tenha a mesma chave que um atributo span definido anteriormente, o valor dessa chave será substituído.

Visualização de dados de evento coletados¶

É possível exibir dados de rastreamento por meio do Snowsight ou consultando a tabela de evento na qual os dados de rastreamento estão armazenados. Para obter mais informações, consulte Visualização dos dados de rastreamento.