Configuração do rastreamento de evento para um aplicativo

Este tópico descreve como definir o uso do rastreamento de evento para capturar mensagens de log e rastrear eventos emitidos por um aplicativo. Ele também descreve como habilitar o compartilhamento de evento para compartilhar mensagens de log e rastrear eventos com provedores.

Sobre o rastreamento de evento no Snowflake Native App Framework

O rastreamento de eventos permite que um aplicativo emita informações relacionadas ao seu desempenho e comportamento. O Snowflake Native App Framework é compatível com a funcionalidade de registro e rastreamento do Snowflake para coletar essas informações. Um aplicativo pode emitir o seguinte:

  • Mensagens de log que são mensagens independentes e detalhadas com informações sobre o estado de um recurso específico no aplicativo.

  • Rastrear eventos com dados estruturados que você pode usar para obter informações abrangendo e agrupando diversas partes de um aplicativo.

Exibir as mensagens de log e eventos de um aplicativo

Para exibir as mensagens de log e rastrear eventos emitidos pelo aplicativo, os consumidores devem definir uma tabela de evento em sua conta para coletar essas informações. Consulte Como definir uma tabela de evento para obter mais informações.

Sobre o compartilhamento de evento

Os consumidores também podem habilitar o compartilhamento de evento para compartilhar dados de evento com provedores. Quando um provedor habilita o compartilhamento de evento, as mensagens de log e os eventos de rastreamento inseridos na tabela de evento na conta do consumidor também são inseridos em uma tabela de evento na conta do provedor.

O compartilhamento de eventos permite que o provedor reúna informações sobre o desempenho e o comportamento do aplicativo. Consulte Sobre o compartilhamento de evento de um aplicativo para obter mais informações.

Sobre definições de evento

As definições de eventos especificam como um aplicativo compartilha mensagens de log e rastreia eventos com o provedor. As definições de eventos atuam como filtros nas mensagens de log e rastreia os níveis de evento definidos pelo provedor. Um provedor especifica as definições de evento para um aplicativo quando uma nova versão ou patch é publicado.

Nota

Definições de eventos não são necessárias. Se um provedor não especificar definições de evento para um aplicativo, os consumidores poderão habilitar ou desabilitar o compartilhamento de evento conforme necessário.

Os provedores podem determinar uma definição de evento como obrigatória ou opcional:

  • As definições de evento necessárias são ativadas automaticamente quando o aplicativo é instalado. Para coletar as definições de evento emitidas por um aplicativo, um consumidor deve criar uma tabela de evento e defini-la como a tabela de evento ativa para sua conta.

  • Definições de evento opcionais podem ser habilitadas ou desabilitadas pelo consumidor, conforme necessário. Definições de evento opcionais exigem uma tabela de evento ativa, mas não são necessárias para instalar ou usar o aplicativo.

Cuidado

As definições de evento não são as mesmas que os níveis de log e de rastreamento definidos pelo provedor. Os níveis de log e rastreamento determinam as informações que são inseridas na tabela de evento do consumidor.

Definições de eventos são filtros que atuam nas mensagens de log e eventos de rastreamento. Eles determinam quais informações são inseridas na tabela de evento do provedor quando o compartilhamento de evento é habilitado.

Definições de evento compatíveis

A tabela a seguir lista as definições de evento atualmente compatíveis:

Tipo

Nome

Descrição

Filter

All

SNOWFLAKE$ALL

Compartilha todas as mensagens de log e eventos de rastreamento que o aplicativo emite.

*

Errors and warnings

SNOWFLAKE$ERRORS_AND_WARNINGS

Compartilha logs relacionados a erros, avisos e eventos fatais.

RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)

Traces

SNOWFLAKE$TRACES

Compartilha rastreamentos detalhados das atividades e jornadas do usuário no aplicativo.

RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)

Usage logs

SNOWFLAKE$USAGE_LOGS

Compartilha logs de alto nível relacionados a ações do usuário e eventos do aplicativo.

RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’

Debug logs

SNOWFLAKE$DEBUG_LOGS

Compartilha logs técnicos usados para solucionar problemas do aplicativo.

RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)

Nota

Se um provedor não configurar o aplicativo para usar definições de evento, Snowsight exibirá apenas o tipo All.

Considerações para consumidores ao usar definições de evento

Os consumidores podem continuar usando a propriedade SHARE_EVENTS_WITH_PROVIDER existente, no entanto, há limitações:

  • Se um aplicativo usar apenas a definição de evento OPTIONAL ALL, definir a propriedade SHARE_EVENTS_WITH_PROVIDER como true irá habilitar o compartilhamento de evento e defini-la como false desabilitará o compartilhamento de evento.

    Isso é aplicável quando um provedor adiciona explicitamente a definição de evento OPTIONAL ALL ao arquivo de manifesto ou um aplicativo foi migrado da funcionalidade de compartilhamento de evento existente.

  • Se um provedor adicionar definições de evento obrigatórias e opcionais ao arquivo de manifesto, configurar a propriedade SHARE_EVENTS_WITH_PROVIDER para true habilita todas as definições de evento. Por outro lado, a propriedade SHARE_EVENTS_WITH_PROVIDER só pode ser definida para false se o provedor adicionar apenas definições de evento opcionais.

    SHARE_EVENTS_WITH_PROVIDER é TRUE somente quando todas as definições de evento estão habilitadas, caso contrário é FALSE.

Fluxo de trabalho para definir o rastreamento de evento para um aplicativo

O fluxo de trabalho a seguir descreve como definir o rastreamento de evento para um aplicativo:

  1. Revise as considerações para usar registro em log e rastreamento de evento.

  2. Configure uma tabela de eventos

  3. Visualize os níveis de evento do registro em log e rastreamento configurados para o aplicativo.

  4. Visualize os eventos na tabela de eventos.

  5. Habilite o compartilhamento de evento em um aplicativo.

Considerações ao usar o rastreamento de evento

Antes de configurar o rastreamento de evento para um aplicativo, você deve considerar o seguinte:

  • Este recurso exige que você configure uma tabela de eventos em sua conta.

  • Após habilitar o compartilhamento de evento, uma cópia mascarada e censurada dos eventos de rastreamento e mensagens de logs é inserida automaticamente na tabela de evento da conta do provedor designada.

  • A Snowflake não cobra para habilitar o compartilhamento de evento. No entanto, você é responsável pelo custo de ingestão de eventos de rastreamento e mensagem de log na tabela de evento, bem como pelos custos de armazenamento da tabela de evento.

  • Após habilitar o compartilhamento de evento com um provedor, você não poderá revogar o acesso a eventos de rastreamento e mensagens de log compartilhados.

  • Você não pode compartilhar eventos históricos usando o compartilhamento de eventos.

  • O Snowflake envia os eventos compartilhados para uma conta de provedor designada na mesma região da sua conta. Esse recurso não compartilha dados entre diferentes regiões.

  • Não é possível alterar os níveis de registro ou rastreamento de um aplicativo. O provedor do aplicativo define esses níveis ao publicar o aplicativo.

  • A Snowflake recomenda revisar os eventos de rastreamento e as mensagens de log na tabela de evento antes de habilitar o compartilhamento de evento.

  • A Snowflake recomenda desabilitar o compartilhamento de evento se você não precisar solucionar problemas do aplicativo.

Configuração de uma tabela de eventos

Para coletar as mensagens de log e eventos de rastreamento emitidos pelo aplicativo, os consumidores devem criar uma tabela de evento para armazenar as informações.

Nota

IF o consumidor não definir uma tabela de evento e a torná-la a tabela de evento ativa antes de instalar o aplicativo, os dados de evento de rastreamento e log são descartados.

Se um provedor incluir definições de evento necessárias no aplicativo, elas serão habilitadas por padrão durante a instalação. Entretanto, se o consumidor não tiver uma tabela de evento ativa, as mensagens de log e os eventos de rastreamento emitidos pelo aplicativo serão descartados.

Uma conta pode ter várias tabelas de evento, mas apenas uma delas pode ser definida como a tabela de evento ativa em uma conta Snowflake por vez. Sem uma tabela de evento ativa, as mensagens de log e os eventos de rastreamento emitidos pelo aplicativo não são capturados. Isso é verdadeiro mesmo que as funções e procedimentos em um aplicativo chamem as APIs de evento de registro em log e rastreamento diretamente.

Para criar uma tabela de evento, execute o comando CREATE EVENT TABLE, conforme mostrado no exemplo a seguir:

CREATE EVENT TABLE event_db.event_schema.my_event_table;
Copy

Observe que este comando especifica o banco de dados e o esquema com a tabela de evento.

Depois de criar a tabela de eventos, use o comando ALTER ACCOUNT para especificar que a tabela de eventos é a tabela ativa para a conta:

ALTER ACCOUNT SET EVENT_TABLE=event_db.event_schema.my_event_table;
Copy

Habilitação do compartilhamento de evento para um aplicativo

O Snowflake Native App Framework é compatível com o compartilhamento de mensagens de log e eventos de rastreamento armazenados na tabela de evento do consumidor com o provedor do aplicativo. Para compartilhar logs e informações de evento com um provedor, o consumidor deve habilitar o compartilhamento de evento para um aplicativo.

Pré-requisitos para habilitar o compartilhamento de evento para um aplicativo

Os seguintes pré-requisitos devem ser atendidos para habilitar o compartilhamento de evento para uma instância de aplicativo:

Habilitação de compartilhamento de evento usando o Snowsight

Nota

Se o provedor incluir definições de evento necessárias no aplicativo, o compartilhamento de evento e as definições de evento necessárias serão ativados durante a instalação e não poderão ser desativados posteriormente.

Para habilitar o compartilhamento de evento para um aplicativo:

  1. Faça login no Snowsight.

  2. No menu de navegação, selecione Data Products » Apps.

  3. Selecione o aplicativo.

  4. Selecione o ícone Security na barra de ferramentas.

  5. Selecione a guia Events and logs.

  6. Na área Events and logs sharing, selecione Enable

  7. Se o provedor tiver determinado definições de evento para o aplicativo:

    1. Use o controle deslizante para habilitar as definições de evento opcionais.

    2. Selecione Review.

  8. Se nenhuma tabela de evento estiver selecionada no momento, selecione a tabela de evento na lista em Event table location.

    Cuidado

    Tenha cuidado ao alterar a tabela de eventos no Snowsight. Cada conta Snowflake usa uma única tabela de eventos para todos os eventos gerados na conta. Alterar a tabela de eventos faz com que todos os eventos gerados na conta sejam armazenados no novo local.

Habilite o compartilhamento de evento usando SQL

Para habilitar o compartilhamento de evento para um aplicativo usando SQL:

  1. Use o comando SHOW TELEMETRY EVENT DEFINITIONS para determinar as definições de evento para o aplicativo:

    SHOW TELEMETRY EVENT DEFINITIONS IN APPLICATION hello_snowflake;
    Copy

    Se o provedor não configurou o aplicativo para usar definições de evento, a coluna type exibirá ALL. Caso contrário, este comando lista as definições de evento opcionais especificadas para o aplicativo.

  2. Se o aplicativo contiver definições de evento necessárias, use o comando ALTER APPLICATION para habilitá-las:

    ALTER APPLICATION hello_snowflake SET AUTHORIZE_TELEMETRY_EVENT_SHARING=true
    Copy

    Este comando habilita todas as definições de evento necessárias, mas não habilita as definições de evento opcionais.

    Nota

    Após habilitar as definições de evento necessárias para um aplicativo, o compartilhamento de evento não pode ser desabilitado.

  3. Se o aplicativo contiver definições de evento de opções, use ALTER APPLICATION para habilitá-las, conforme mostrado no exemplo a seguir:

    ALTER APPLICATION hello_snowflake SET SHARED TELEMETRY EVENTS ('SNOWFLAKE$TRACES', 'SNOWFLAKE$DEBUG_LOGS');
    Copy

    Este exemplo habilita SNOWFLAKE$TRACES e SNOWFLAKE$DEBUG_LOGS com base na saída do comando SHOW TELEMETRY EVENT DEFINITIONS.

  4. Para verificar se o rastreamento e o registro de evento estão habilitados, use o comando DESC APPLICATION:

    DESC APPLICATION hello_snowflake;
    Copy

    As linhas authorize_telemetry_event_sharing e share_events_with_provider da saída indicam se o compartilhamento de evento está habilitado.

Habilitação do compartilhamento de evento usando SQL (funcionalidade mais antiga)

Cuidado

O método de ativação do compartilhamento de evento usando SQL descrito nesta seção será descontinuado em um lançamento futuro. A Snowflake recomenda usar o método descrito em Habilitação do compartilhamento de log e evento usando SQL para habilitar o compartilhamento de evento usando SQL.

Para habilitar o compartilhamento de evento para um aplicativo, execute o comando ALTER APPLICATION para definir SHARE_EVENTS_WITH_PROVIDER como TRUE. Por exemplo:

ALTER APPLICATION HelloSnowflake SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
Copy

Para mostrar o status de compartilhamento de evento de um aplicativo, use o comando DESC APPLICATION, conforme mostrado no exemplo a seguir:

DESC APPLICATION HelloSnowflake;
Copy

SHARE_EVENTS_WITH_PROVIDER mostra o status do compartilhamento de evento do aplicativo.

Habilitação das definições de evento durante as atualizações

Durante as atualizações, as definições de evento se comportam da seguinte forma:

Alteração da definição do evento

Comportamento durante a atualização

Nenhuma alteração na definição do evento

A definição do evento mantém o mesmo status da versão ou patch anterior.

Uma nova definição de evento

Não habilitado automaticamente. Isso é verdadeiro tanto para definições de evento obrigatórias quanto opcionais. O consumidor deve habilitar manualmente novas definições de evento.

Mudanças de obrigatório para opcional ou de opcional para obrigatório

A definição do evento mantém o mesmo status da versão ou patch anterior.

Definição de evento excluído

O compartilhamento de eventos é interrompido após a atualização do filtro de mensagens de log ou eventos de rastreamento na versão ou patch anterior.

Durante a atualização, os consumidores são solicitados a revisar as alterações nas definições de evento do patch ou versão anterior.

Visualize as mensagens de log e rastreie os eventos na tabela de evento

WHen uma tabela de evento é habilitada, os consumidores podem consultar a tabela de evento para ver as mensagens de log e rastrear eventos emitidos pelo aplicativo. Use o comando SELECT para consultar a tabela de evento, por exemplo:

SELECT * FROM event_db.event_schema.my_event_table;
Copy

Este comando retorna todas as mensagens de log e eventos de rastreamento armazenados na tabela de evento.

Como determinar se uma mensagem de log ou evento de rastreamento é compartilhado com o provedor

A coluna RECORD_ATTRIBUTES contém o campo snow.application.shared. Se o valor deste campo for TRUE, a mensagem de log ou o evento de rastreamento será compartilhado com o provedor. Caso contrário, a mensagem de log ou o evento não será compartilhado.

Como exibir os níveis de log e rastreamento de um aplicativo

O nível de log e rastreamento de um aplicativo é definido pelo provedor antes da publicação do aplicativo. Os consumidores não podem alterar os níveis de log e rastreamento de um aplicativo.

No entanto, antes de configurar o rastreamento de evento ou habilitar o compartilhamento de evento para um aplicativo, a Snowflake recomenda verificar o nível de log para entender o tipo de informação coletada e compartilhada com o provedor.

Para exibir o nível de log e rastreamento de um aplicativo, execute o seguinte comando:

DESC APPLICATION HelloSnowflake;
Copy

Este comando exibe informações sobre o aplicativo HelloSnowflake, incluindo as seguintes informações sobre o nível de log e rastreamento definidas para o aplicativo:

  • log_level: O nível de log definido pelo provedor no arquivo de manifesto.

  • trace_level: O nível de rastreamento definido pelo provedor no arquivo de manifesto.

  • effective_log_level: O nível de log habilitado para o aplicativo.

  • effective_trace_level: O nível de rastreamento habilitado para o aplicativo.

Os níveis efetivos de log e rastreamento são determinados pelas definições de evento que o consumidor habilita para o aplicativo.

Por exemplo, se o provedor definir o nível de log como OFF, mas o consumidor habilitar a definição de evento ERROR_AND_WARNING, o aplicativo alterará dinamicamente o nível de log para WARN para que os eventos ERROR_AND_WARNING possam ser coletados. O aplicativo emite eventos que são menos ou igualmente detalhados como WARN e compartilha esses eventos de erro e aviso com o provedor. Os valores de log_level seriam OFF e o valor de effective_log_level seria WARN.

Por outro lado, se o provedor definir o nível de log como TRACE, mas o consumidor habilitar a definição de evento ERROR_AND_WARNING, o aplicativo emitirá eventos que serão menos ou igualmente tão detalhados quanto o rastreamento, mas apenas mensagens de erro e aviso serão compartilhadas com o provedor. O valor de log_level e effective_log_level seria TRACE.

Linguagem: Português