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.

O que você aprenderá

Neste tutorial, você aprenderá como:

  • Criar uma tabela de eventos para armazenar dados de registro e rastreamento.

    O Snowflake coleta dados de registro e rastreamento na estrutura predefinida da tabela.

  • Emitir mensagens de registro e dados de rastreamento de uma função definida pelo usuário (UDF).

    Você pode usar uma API projetada para a sua linguagem de manipulador para emitir mensagens de registro e rastrear dados do código do manipulador.

  • Visualizar os dados de registro e rastreamento coletados consultando a tabela de eventos.

    Você pode consultar a tabela com uma instrução SELECT para analisar os dados coletados.

Pré-requisitos

  • Você deve executar todos os comandos SQL na mesma sessão de comando SQL porque o contexto da sessão é necessário.

    Para fazer isso na Snowsight, por exemplo, cole todo o seu código na mesma planilha à medida que avança. À medida que você avança de uma seção para outra, cada seção se baseia na anterior.

  • Você deve ser capaz de usar a função ACCOUNTADMIN.

    Neste tutorial, você executará todas as etapas usando a função ACCOUNTADMIN. Na prática geral, no entanto, você deve usar funções com privilégios especificamente definidos para a ação que está executando. Por exemplo, você pode ter funções separadas para os desenvolvedores que criam UDFs, para os analistas que consultam os dados de registro e rastreamento coletados e assim por diante.

    Para saber mais sobre funções, consulte Mudança de sua função ativa e Considerações sobre o controle de acesso.

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.

Importante

Para concluir esta seção, você precisará ser capaz de usar a função ACCOUNTADMIN, que é necessária ao alterar uma conta para que a nova tabela de eventos seja a tabela de eventos ativa da conta.

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.

Nota

Pode levar vários segundos para que os dados de registro ou rastreamento emitidos pelo código do manipulador sejam registrados na tabela de eventos. Se você não vir resultados imediatamente, tente novamente em alguns segundos.

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.

Nota

Pode levar vários segundos para que os dados de registro ou rastreamento emitidos pelo código do manipulador sejam registrados na tabela de eventos. Se você não vir resultados imediatamente, tente novamente em alguns segundos.

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ê: