Configuração do registro e o compartilhamento de eventos para um aplicativo

Este tópico descreve como configurar o registro e o compartilhamento de eventos para solucionar problemas de um aplicativo instalado.

Este tópico fornece informações sobre como configurar o registro e o compartilhamento de eventos como um provedor. Consulte Como ativar o registro e o compartilhamento de eventos para um aplicativo para os requisitos do consumidor para configurar esse recurso.

Os eventos de registro e rastreamento permitem que você colete informações sobre um aplicativo para solucionar erros. Usando eventos de registro e rastreamento, você também pode ter uma ideia melhor de como seu aplicativo é executado e melhorá-lo posteriormente.

Fluxo de trabalho para configurar o registro e o compartilhamento de eventos como um provedor

Como provedor, você pode configurar o registro e o compartilhamento de eventos para um aplicativo executando o seguinte:

  1. Revisão das considerações para usar o registro e o compartilhamento de eventos.

  2. Configuração de eventos de registro e rastreamento para funções e procedimentos armazenados.

  3. Definição do nível de registro e rastreamento no arquivo de manifesto.

  4. Configuração de uma conta para armazenar eventos compartilhados.

Depois que o consumidor instalar um aplicativo e habilitar o registro e o compartilhamento de eventos, você pode visualizar o registro e as informações de eventos compartilhadas pelo aplicativo instalado:

Considerações para usar o registro e o compartilhamento de eventos

Antes de usar o registro e o compartilhamento de eventos para um aplicativo, você deve considerar o seguinte:

  • Você é responsável por todos os custos associados ao compartilhamento de eventos no lado do provedor, incluindo ingestão e armazenamento de dados.

  • Você deve ter uma conta para armazenar eventos compartilhados em cada região onde você deseja oferecer suporte ao compartilhamento de eventos.

  • Você deve definir o nível de log padrão e o nível de rastreamento para um aplicativo no arquivo de manifesto.

Configuração de eventos de registro e rastreamento em funções e procedimentos

O Native Apps Framework exige uma tabela de eventos para armazenar mensagens de log e rastrear eventos gerados a partir de funções e procedimentos armazenados em um aplicativo.

Nota

Se o consumidor de seu aplicativo não configurar uma tabela de eventos e torná-la a tabela ativa antes de instalar o aplicativo, os dados de registro e eventos serão descartados.

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

Para criar uma tabela de eventos, use o comando CREATE EVENT TABLE. Para obter mais informações, consulte Configuração de uma tabela de eventos.

Após o código ter registrado mensagens de log e eventos de rastreamento, você pode consultar os dados gravados.

Para obter informações sobre como registrar e consultar dados de log e rastreamento, consulte o seguinte:

Definição do nível de registro e rastreamento no arquivo de manifesto

Para definir os níveis de eventos de rastreamento e log padrão para uma versão de um aplicativo, defina os parâmetros log_level e trace_level no arquivo de manifesto, conforme mostrado no exemplo a seguir:

artifacts:
  setup_script: setup.sql
configuration:
  trace_level: OFF
  log_level: DEBUG
Copy

Quando um provedor ativa o rastreamento, um Snowflake Native App captura automaticamente as horas de início e término de todas as consultas e chamadas de procedimento armazenado.

Nota

Publicar um Snowflake Native App com a propriedade trace_level definida com um valor diferente de OFF pode expor chamadas para procedimentos armazenados ocultos a qualquer usuário na conta do consumidor que possa visualizar a tabela de eventos.

Consulte Configuração do nível de rastreamento e Configuração do nível de registro para obter informações sobre os valores suportados para trace_level e log_level.

Quando o Snowflake Native App é instalado inicialmente, ele usa os níveis de log definidos no arquivo de manifesto. Se o nível de log for alterado em uma atualização subsequente, o novo nível de log entrará em vigor após a conclusão do processo de atualização.

O nível de rastreamento e log só podem ser definidos no arquivo de manifesto. O consumidor não tem permissão para modificar o nível de log usando os comandos ALTER APPLICATION ou ALTER DATABASE.

Da mesma forma, quaisquer configurações de nível de sessão para o nível de registro em log são ignoradas pelo aplicativo.

Configuração de uma conta para armazenar eventos compartilhados

Para armazenar logs e eventos compartilhados, você deve selecionar uma conta para armazenar uma tabela de eventos. Pode ser qualquer conta que um provedor possa acessar. No entanto, se sua organização tiver vários provedores publicando pacotes de aplicativos, considere usar uma conta Snowflake dedicada para armazenar eventos compartilhados do consumidor.

As seguintes restrições se aplicam à conta de eventos compartilhados:

  • Você deve usar a função ORGADMIN para definir uma conta como a conta de eventos.

  • A conta deve ter uma tabela de eventos ativos.

  • A conta especificada não pode ser nenhuma das seguintes opções:

    • Uma conta bloqueada ou suspensa.

    • Uma conta de leitor.

    • Uma conta de avaliação.

    • Uma conta gerenciada do Snowflake.

Nota

Você pode coletar logs e eventos compartilhados apenas na mesma região em que um consumidor instala um aplicativo. Portanto, você deve configurar uma conta para armazenar eventos compartilhados em cada região onde os consumidores configuram o compartilhamento de eventos para um aplicativo.

Definição de uma conta como a conta de eventos

Para definir uma conta para ser a conta de eventos de uma região, chame a função do sistema SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION:

CALL SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

Onde:

snowflake_region

Especifica o nome da região onde a conta está localizada, por exemplo: AWS_US_WEST_2, AWS_US_EAST_1

region_group

Especifica o grupo de regiões, por exemplo: PUBLIC. Consulte Grupos de regiões para obter detalhes.

account_name

Especifica o nome da conta. Se outra conta já estiver definida como a conta de eventos na região especificada, a execução desse comando altera a conta de eventos para a conta especificada aqui.

Cancelamento da definição de uma conta como a conta de eventos

Para cancelar a definição de uma conta para ser a conta de eventos de uma região, chame a função do sistema SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION:

CALL SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

Onde:

snowflake_region

Especifica o nome da região onde a conta está localizada, por exemplo: AWS_US_WEST_2, AWS_US_EAST_1

region_group

Especifica o grupo de regiões, por exemplo: PUBLIC.

account_name

Especifica o nome da conta.

Visualização de contas de eventos na organização do provedor

Para mostrar contas de eventos na organização de um provedor, chame a função do sistema SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS:

CALL SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS()
Copy

Nota

Você deve usar a função ORGADMIN para chamar essa função.

Esta função do sistema retorna uma string em formato JSON contendo uma lista de contas de eventos dentro da organização. Como os metadados levam algum tempo para se propagar para todas as regiões, esta função pode apresentar algum atraso ao mostrar a conta de eventos mais recentes após o usuário definir/cancelar a definição de uma conta de eventos para a organização.

Exibição dos níveis de log e rastreamento de eventos definidos em um pacote de aplicativo

Use o comando DESCRIBE APPLICATION para visualizar o nível de registro em log de um aplicativo instalado, conforme mostrado no seguinte comando:

DESC APPLICATION HelloSnowflake;
Copy

Use o comando SHOW VERSIONS para visualizar o nível de registro em log das versões do aplicativo definidas em um pacote de aplicativo, conforme mostrado no exemplo a seguir:

SHOW VERSIONS
  IN APPLICATION PACKAGE HelloSnowflake;
Copy

Exibição dos logs e eventos na tabela de eventos

Para visualizar os logs e eventos armazenados na tabela de eventos, use o comando SELECT como mostrado no exemplo a seguir:

SELECT * FROM EVENT_DB.EVENT_SCHEMA.MY_EVENT_TABLE
Copy

Informações de eventos compartilhados disponíveis para o provedor

As seções a seguir descrevem as informações que o Native Apps Framework compartilha com os provedores.

Contexto de evento de aplicativo compartilhado com o provedor

Para ajudar os provedores a identificar facilmente a origem dos eventos compartilhados, os campos a seguir são preenchidos na coluna RESOURCE_ATTRIBUTES da tabela de eventos quando são compartilhados com o provedor:

  • snow.application.package.name

  • snow.application.consumer.organization

  • snow.application.consumer.name

  • snow.listing.name

  • snow.listing.global_name

Campos que não são compartilhados com o provedor

Para proteger as informações do consumidor, os seguintes campos da coluna RESOURCE_ATTRIBUTES não são compartilhados com o provedor:

  • snow.database.id

  • snow.database.name

  • snow.schema.id

  • snow.executable.id

  • snow.owner.name

  • snow.owner.id

  • snow.warehouse.name

  • snow.warehouse.id

  • snow.query.id

  • snow.session.id

  • snow.session.role.primary.name

  • snow.session.role.primary.id

  • snow.user.name

  • snow.user.id

  • db.user

Em vez de compartilhar diretamente os campos snow.database.name e snow.query.id com o provedor, o Snowflake compartilha os valores de hash (SHA-1) desses dois campos como os seguintes campos:

  • snow.database.hash

  • snow.query.hash

O Snowflake fornece a função SHA-1 usada para mascarar esses atributos. Os consumidores podem calcular os valores de hash para o nome do banco de dados e o ID da consulta e usá-los como valores de referência ao entrar em contato com o provedor.