Tutorial: Introdução ao registro e rastreamento¶

Introdução¶

Este tutorial apresenta os conceitos básicos de emissão, coleta e consulta de dados de registro e rastreamento do código do manipulador de funções e procedimentos.

O tutorial usa a interface da Web Snowsight, mas você pode usar qualquer cliente Snowflake que ofereça suporte à execução de SQL. Para obter mais informações sobre Snowsight, consulte Introdução a planilhas e Gerenciamento e uso de planilhas no Snowsight.

Configuração do banco de dados, warehouse e acesso¶

Nesta seção, você criará um warehouse e um banco de dados necessários para o tutorial. Você também começará a usar a função ACCOUNTADMIN, que é necessária para executar algumas das instruções deste tutorial.

Você está criando um banco de dados no qual, posteriormente, criará a tabela de eventos e a função definida pelo usuário. Você pode excluir todos os objetos criados no tutorial, inclusive o banco de dados e o warehouse, quando não precisar mais deles.

Para criar um banco de dados e um warehouse para uso no tutorial:

1. Entre em Snowsight.

2. Mude para a função ACCOUNTADMIN.

3. Abra Projects » Worksheets.

4. Selecione + » SQL Worksheet.

5. Renomeie a nova planilha como Logging-tracing tutorial.

6. Na nova planilha, cole e execute a seguinte instrução para criar um banco de dados. O novo banco de dados é apenas para este tutorial.

   CREATE OR REPLACE DATABASE tutorial_log_trace_db;
   

   Copy

7. Cole e execute a seguinte instrução para criar um warehouse. O novo warehouse é apenas para este tutorial.

   CREATE OR REPLACE WAREHOUSE tutorial_log_trace_wh
     WAREHOUSE_TYPE = STANDARD
     WAREHOUSE_SIZE = XSMALL;
   

   Copy

Nesta seção, você coloca no lugar as peças necessárias para o tutorial. Na próxima seção, você criará uma tabela de eventos para armazenar dados de registro e rastreamento.

Criação de uma tabela de eventos¶

Nesta seção, você criará uma tabela de eventos. À medida que seu código do manipulador emite mensagens de registro e dados de rastreamento, o Snowflake salva os dados emitidos em linhas da tabela de eventos. Você pode consultar a tabela de eventos para analisar os dados.

É necessário criar uma tabela de eventos para coletar dados de registro e rastreamento. Uma tabela de eventos sempre usa a estrutura predefinida pelo Snowflake.

Para criar a tabela de eventos e torná-la a tabela de eventos ativa da conta:

1. Cole e execute a seguinte instrução para criar uma tabela de eventos.

   CREATE OR REPLACE EVENT TABLE tutorial_event_table;
   

   Copy

   É nessa tabela que o Snowflake armazena os dados de registro e rastreamento.

2. Cole e execute a instrução a seguir para alterar a conta de modo que a tabela de eventos que você criou seja a ativa para a conta.

   ALTER ACCOUNT SET EVENT_TABLE = tutorial_log_trace_db.public.tutorial_event_table;
   

   Copy

   Essa instrução define a nova tabela de eventos como a tabela que o Snowflake deve usar para armazenar mensagens de registro e dados de rastreamento dos manipuladores na conta atual. Você pode ter apenas uma tabela de eventos ativa para uma conta.

Nesta seção, você criou uma tabela de eventos. Na próxima seção, você começará a emitir mensagens de registro que o Snowflake armazena na tabela.

Emissão de mensagens de registro¶

Nesta seção, você criará uma função definida pelo usuário (UDF) com código de manipulador Python que emite mensagens de registro. À medida que seu código emite mensagens de log, o Snowflake coleta os dados da mensagem e os armazena na tabela de eventos que você criou.

O Snowflake oferece suporte a APIs para registrar mensagens de cada linguagem de manipulador suportada. Para manipuladores escritos em Python, você pode usar o módulo logging na biblioteca padrão do Python.

Para criar uma UDF que emite mensagens de registro:

1. Cole e execute a seguinte instrução para definir o nível de registro como INFO.

   ALTER SESSION SET LOG_LEVEL = INFO;
   

   Copy

   Isso especifica a gravidade das mensagens de log que o Snowflake deve capturar à medida que a UDF é executada. Nesse caso, o nível permite todas as mensagens, desde as informativas (INFO) até as mais graves (FATAL).

2. Cole e execute a instrução a seguir para criar uma função definida pelo usuário.

   CREATE OR REPLACE FUNCTION log_trace_data()
   RETURNS VARCHAR
   LANGUAGE PYTHON
   RUNTIME_VERSION = 3.8
   HANDLER = 'run'
   AS $$
   import logging
   logger = logging.getLogger("tutorial_logger")
   
   def run():
     logger.info("Logging from Python function.")
     return "SUCCESS"
   $$;
   

   Copy

   As linhas destacadas no código fazem o seguinte:

   • Importam o módulo Python logging para que o código do manipulador possa usá-lo.

   • Criam um registrador que exponha a interface que seu código usará para registrar mensagens.

   • Registram uma mensagem no nível INFO.

3. Colam e executam a seguinte instrução para executar a função que você acabou de criar.

   SELECT log_trace_data();
   

   Copy

   Isto produz a seguinte saída. Além disso, à medida que a função era executada, ela emitia uma mensagem de registro que o Snowflake coletava na tabela de eventos.

   --------------------
   | LOG_TRACE_DATA() |
   --------------------
   | SUCCESS          |
   --------------------
   

Nesta seção, você emitiu uma mensagem de registro de uma UDF. Na próxima seção, você consultará a tabela de eventos para recuperar dados relacionados à mensagem.

Consulta de mensagens de registro¶

Nesta seção, você consultará a tabela de eventos para obter dados de mensagens de registro emitidas pela UDF que você executou na seção anterior.

O Snowflake usa colunas predefinidas da tabela de eventos para coletar e armazenar dados de registro e rastreamento dos seguintes tipos:

• Dados que você emite do código do manipulador, como mensagens de log e dados de eventos de rastreamento.

  Você os encontrará em colunas como RECORD_TYPE, RECORD, RECORD_ATTRIBUTES e outras.

• Dados sobre o contexto em que os dados de log ou rastreamento foram emitidos, como o carimbo de data/hora, o nome do método do manipulador a partir do qual os dados foram emitidos e assim por diante.

  Você encontrará esses dados em colunas como RESOURCE_ATTRIBUTES, TIMESTAMP e SCOPE.

Para consultar a tabela de eventos para obter dados de mensagens de registro:

1. Cole e execute a seguinte instrução para consultar a tabela de eventos.

   SELECT
     TIMESTAMP AS time,
     RESOURCE_ATTRIBUTES['snow.executable.name'] as executable,
     RECORD['severity_text'] AS severity,
     VALUE AS message
   FROM
     tutorial_log_trace_db.public.tutorial_event_table
   WHERE
     RECORD_TYPE = 'LOG'
     AND SCOPE['name'] = 'tutorial_logger';
   

   Copy

   Algumas colunas contêm dados estruturados expressos como pares chave-valor. Nessa consulta, você especifica chaves de atributo em uma coluna usando a notação de colchetes, como RECORD['severity_text'].

   Você também usa a notação de colchetes (SCOPE['name']) para especificar que deseja selecionar valores de coluna somente onde as entradas de log são emitidas com o agente de log Python, tutorial_logger, que você criou no código do manipulador.

2. Visualize a saída.

   -----------------------------------------------------------------------------------------------------------
   | TIME                | EXECUTABLE                           | SEVERITY | MESSAGE                         |
   -----------------------------------------------------------------------------------------------------------
   | 2023-04-19 22:00:49 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "INFO"   | "Logging from Python function." |
   -----------------------------------------------------------------------------------------------------------
   

   O resultado ilustra como as colunas predefinidas da tabela de eventos contêm, cada uma, partes dos dados coletados. Para os valores EXECUTABLE e SEVERITY, você usou a notação de colchetes para especificar os atributos cujos valores são desejados.

   Coluna de saída	Descrição
   TIME	A hora em que o registro foi criado (na coluna TIMESTAMP).
   EXECUTABLE	Nome e parâmetros da UDF (do atributo snow.executable.name da colunaRESOURCE_ATTRIBUTES).
   SEVERITY	Gravidade da entrada de log (do atributo severity_text da coluna RECORD).
   MESSAGE	Mensagem de log (da coluna VALUE).

Nesta seção, você usou uma instrução SELECT para consultar os dados de log. Na próxima seção, você atualizará a UDF para que ela emita dados de rastreamento.

Emissão de dados de rastreamento¶

Nesta seção, você atualizará o código do manipulador da UDF para que ele também emita dados de rastreamento. À medida que seu código emite dados de rastreamento, o Snowflake coleta os dados e os armazena na tabela de eventos que você criou.

Os dados de rastreamento têm qualidades estruturais, incluindo dados de eventos agrupados em spans e dados capturados como pares chave-valor, que permitem montar uma imagem mais detalhada da atividade do código do que os dados de log normalmente permitem.

O Snowflake oferece suporte a APIs para emitir dados de rastreamento de cada linguagem de manipulador suportada. Para manipuladores escritos em Python, você pode usar o pacote Snowflake telemetry.

Para atualizar a UDF para emitir dados de rastreamento:

1. Cole e execute a seguinte instrução para especificar quais dados de rastreamento devem ser capturados.

   ALTER SESSION SET TRACE_LEVEL = ON_EVENT;
   

   Copy

   Isso define o nível de rastreamento como ON_EVENT. Isso especifica que somente os dados de rastreamento emitidos explicitamente por seu próprio código devem ser capturados.

2. Cole e execute a instrução a seguir para criar uma UDF que emite dados de rastreamento.

   CREATE OR REPLACE FUNCTION log_trace_data()
   RETURNS VARCHAR
   LANGUAGE PYTHON
   PACKAGES = ('snowflake-telemetry-python')
   RUNTIME_VERSION = 3.8
   HANDLER = 'run'
   AS $$
   import logging
   logger = logging.getLogger("tutorial_logger")
   from snowflake import telemetry
   
   def run():
     telemetry.set_span_attribute("example.proc.run", "begin")
     telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
     logger.info("Logging from Python function.")
     return "SUCCESS"
   $$;
   

   Copy

   Ao executar esse código, você está substituindo a função criada anteriormente por uma que adiciona o código para emitir dados de rastreamento. As linhas destacadas fazem o seguinte:

   • Adicione snowflake-telemetry-python, que contém o pacote telemetry, ao ambiente de execução da UDF.

   • Importe o pacote telemetry para que você possa chamar suas funções.

   • Defina um atributo e um valor de atributo para o span que o Snowflake cria quando o código é executado.

     Um intervalo representa a unidade de execução de um procedimento ou UDF, dentro da qual você pode adicionar vários eventos.

   • Adicione um evento (com seus próprios atributos) para registrar como parte do span.

3. Colam e executam a seguinte instrução para executar a função que você acabou de criar.

   SELECT log_trace_data();
   

   Copy

   Isto produz a seguinte saída. Além disso, à medida que a função era executada, ela emitia dados de rastreamento que o Snowflake coletava na tabela de eventos.

   --------------------
   | LOG_TRACE_DATA() |
   --------------------
   | SUCCESS          |
   --------------------
   

Nesta seção, você emitiu dados de rastreamento de uma UDF. Na próxima seção, você consultará a tabela de eventos para recuperar dados relacionados ao rastreamento.

Consulta de mensagens de rastreamento¶

Nesta seção, você consultará a tabela de eventos para obter dados de rastreamento emitidos pela UDF que você executou na seção anterior.

A consulta que você escrever recuperará informações contextuais sobre os eventos emitidos pela função. Esse contexto inclui o nome da função que o emitiu.

Para consultar a tabela de eventos para obter dados de rastreamento:

1. Cole e execute a seguinte instrução para consultar a tabela de eventos em busca de dados de rastreamento.

   SELECT
     TIMESTAMP AS time,
     RESOURCE_ATTRIBUTES['snow.executable.name'] AS handler_name,
     RECORD['name'] AS event_name,
     RECORD_ATTRIBUTES AS attributes
   FROM
     tutorial_log_trace_db.public.tutorial_event_table
   WHERE
     RECORD_TYPE = 'SPAN_EVENT'
     AND HANDLER_NAME LIKE 'LOG_TRACE_DATA%';
   

   Copy

   Algumas colunas contêm dados estruturados expressos como pares chave-valor. Para isso, você pode selecionar valores de atributos em uma coluna usando a notação de colchetes, conforme mostrado no código.

2. Visualize a saída.

   -----------------------------------------------------------------------------------------------------------------------------------------------------
   | TIME                    | HANDLER_NAME                         | EVENT_NAME              | ATTRIBUTES                                             |
   -----------------------------------------------------------------------------------------------------------------------------------------------------
   | 2023-05-10 20:49:35.080 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "event_with_attributes" | { "example.key1": "value1", "example.key2": "value2" } |
   -----------------------------------------------------------------------------------------------------------------------------------------------------
   

   O resultado ilustra como as colunas predefinidas da tabela de eventos contêm, cada uma, partes dos dados coletados. Para os valores EXECUTABLE e SEVERITY, você usou a notação de colchetes para especificar o atributo cujo valor é desejado.

   Coluna de saída	Descrição
   TIME	Hora em que a entrada foi criada (na coluna TIMESTAMP).
   HANDLER_NAME	Nome e parâmetros da UDF (do atributo snow.executable.name da colunaRESOURCE_ATTRIBUTES).
   EVENT_NAME	Nome do evento adicionado com a função add_event (do atributo RECORD da coluna name).
   ATTRIBUTES	Atributos adicionados para acompanhar o evento (da coluna RECORD_ATTRIBUTES).

Nesta seção, você consultou a tabela de eventos para obter dados de rastreamento emitidos pela UDF que você escreveu. Na última seção, você terá links para informações relacionadas ao que você fez durante o tutorial.

Saiba mais¶

Você terminou! Muito bem.

Neste tutorial, você teve uma visualização de ponta a ponta de como pode emitir e armazenar dados de registro e rastreamento do código do manipulador e, em seguida, consultar os dados armazenados. Ao longo do caminho, você:

• Criou uma tabela de eventos. Para obter mais informações relacionadas a tabelas de eventos, consulte o seguinte:

  • Para obter mais detalhes sobre a configuração de uma tabela de eventos, consulte Configuração de uma tabela de eventos.

  • Para obter informações de referência sobre as colunas que compõem uma tabela de eventos, consulte Colunas da tabela de eventos.

  • Para saber mais sobre o que você pode fazer com as tabelas de eventos, consulte Como trabalhar com tabelas de eventos.

• Criou uma função definida pelo usuário (UDF) que emitiu dados de registro e rastreamento. Para obter informações relacionadas, consulte o seguinte:

  • Para obter uma visão geral do suporte de registro no Snowflake, consulte Registro de mensagens de funções e procedimentos. Para obter informações específicas sobre registro em log com Python, consulte Registro de mensagens de funções e procedimentos e o módulo logging na biblioteca padrão do Python.

  • Para obter mais detalhes sobre a configuração do nível de registro, consulte Configuração do nível de registro.

  • Para obter uma visão geral do suporte de rastreamento, consulte Eventos de rastreamento para funções e procedimentos. Para obter informações específicas sobre rastreamento com Python, consulte Emissão de eventos de rastreamento em Python.

  • Para obter mais detalhes sobre a configuração do nível de rastreamento, consulte Configuração do nível de rastreamento.

  • Para obter informações gerais sobre a criação de UDFs, consulte Visão geral das funções definidas pelo usuário.

• Consultou a tabela de eventos para obter dados de registro e rastreamento. Para obter mais informações relacionadas às tabelas de eventos, consulte o seguinte:

  • Para obter uma visualização mais completa de como consultar os dados de registro, consulte Acesso a dados de mensagens registradas.

  • Para obter uma visualização de como consultar os dados de rastreamento, consulte Acesso a dados de rastreamento.

  • Para obter mais informações sobre spans e eventos, além de informações sobre como o Snowflake armazena dados para eles, consulte Como o Snowflake representa eventos de rastreamento.