Funcionalidade anterior de registro e compartilhamento de evento – Obsoleto

Este tópico descreve o método obsoleto para configuração do registro e o compartilhamento de evento antes da introdução das definições de evento.

Os provedores que estão configurando o registro e o compartilhamento de evento devem usar o método descrito em Use logging and event tracing for an app. Consulte Considerações ao migrar da funcionalidade anterior de compartilhamento de evento para obter informações sobre como migrar da funcionalidade obsoleta de registro e compartilhamento de evento para a nova.

Aviso

O processo para configuração de registro e compartilhamento de evento descrito neste tópico será descontinuado em um lançamento futuro.

Funcionalidade anterior de registro em log e compartilhamento de evento

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

Eventos de registro em log 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 definir o registro e o compartilhamento de evento 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 instala um aplicativo e habilita o registro e o compartilhamento de evento, você pode exibir as informações de registro e evento compartilhadas pelo aplicativo:

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

Antes de usar o registro e compartilhamento de evento para um aplicativo, os provedores devem considerar o seguinte:

  • Os provedores são responsáveis por todos os custos associados ao compartilhamento de eventos no lado do provedor, incluindo ingestão e armazenamento de dados.

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

  • Os provedores devem definir o nível de log e o nível de rastreamento padrão para um aplicativo no arquivo de manifesto.

Nota

O compartilhamento de eventos não pode ser habilitado para um aplicativo instalado na mesma conta que o pacote de aplicativos no qual ele se baseia. Para testar o compartilhamento de eventos para um aplicativo, um provedor deve usar várias contas.

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

O Native Apps Framework requer uma tabela de evento 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 um aplicativo não definir uma tabela de evento e torná-la a tabela ativa antes de instalar o aplicativo, os dados de evento e registros 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 evento ativa, as mensagens de log e os eventos de rastreamento gerados 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 e rastreamento.

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

Após o código ter registrado mensagens de log e eventos de rastreamento, seu provedor 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 evento de log e rastreamento padrão para uma versão de um aplicativo, defina os parâmetros log_level, trace_level e metric_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.

Para obter informações sobre valores compatíveis com trace_level, log_level e metric_level, consulte Definição de níveis para registro, métricas e rastreamento e Definição de níveis para registro, métricas e rastreamento.

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, um provedor deve selecionar uma conta para manter uma tabela de eventos. Pode ser qualquer conta que um provedor possa acessar. No entanto, se uma 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 às contas usadas para armazenar eventos compartilhados:

  • Você deve usar uma função de administrador da organização para definir uma conta como a conta usada para armazenar 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

Um provedor pode coletar logs e eventos compartilhados somente na mesma região onde um consumidor instala um aplicativo. Os provedores devem definir uma conta para armazenar eventos compartilhados em cada região onde os consumidores configuram o compartilhamento de evento 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. Use sempre o nome da conta e não o identificador de conta Snowflake.

Nota

Você deve usar uma função de administrador da organização para chamar essa função.

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. Use sempre o nome da conta e não o identificador de conta Snowflake.

Nota

Você deve usar uma função de administrador da organização para chamar essa função.

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 uma função de administrador da organização 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 evento de registro e rastreamento definidos para um pacote de aplicativo

Use o comando DESCRIBE APPLICATION para exibir o nível de registro em log de um aplicativo, conforme mostrado no comando a seguir:

DESC APPLICATION HelloSnowflake;
Copy

Use o comando SHOW VERSIONS IN APPLICATION PACKAGE para exibir 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 do evento do 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.

Determine se o compartilhamento de eventos está habilitado na conta do consumidor

Em alguns contextos, um provedor pode precisar determinar se o compartilhamento de eventos foi habilitado em uma conta de consumidor. Por exemplo, um provedor pode precisar desabilitar a funcionalidade do aplicativo se a tabela de eventos não estiver disponível.

Para determinar se o compartilhamento de eventos está habilitado em uma conta de consumidor, os provedores podem chamar as seguintes funções do sistema ao definir a lógica do aplicativo:

  • IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER

    Retorna TRUE se o aplicativo habilitar o compartilhamento de eventos e uma tabela de eventos ativa estiver disponível na conta do consumidor. Caso contrário, retorna FALSE.

  • IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT

    Retorna TRUE se o aplicativo foi instalado na mesma conta que o pacote de aplicativo no qual ele se baseia. Caso contrário, retorna FALSE.

Nota

Essas funções do sistema só podem ser chamadas de dentro de um aplicativo. Consulte Determine se o compartilhamento de eventos está habilitado usando o Python Permission SDK e Determine se o compartilhamento de eventos está habilitado usando SQL

Determine se o compartilhamento de eventos está habilitado usando o Python Permission SDK

O Python Permission SDK fornece as seguintes funções para determinar se o compartilhamento uniforme está habilitado em uma conta de consumidor:

  • is_event_sharing_enabled()

    Retorna TRUE se a propriedade SHARE_EVENTS_WITH_PROVIDER for verdadeira e a conta do consumidor tiver uma tabela de eventos ativa configurada. Caso contrário, retorna FALSE.

  • is_application_local_to_package()

    Retorna TRUE se o aplicativo estiver na mesma conta que o pacote do aplicativo. Caso contrário, retorna FALSE.

Determine se o compartilhamento de eventos está habilitado usando SQL

O exemplo a seguir mostra como chamar um procedimento armazenado quando o compartilhamento de eventos está habilitado na conta do consumidor.

Considere o seguinte procedimento armazenado SQL que cria uma função para calcular a soma de dois números:

CREATE OR ALTER VERSIONED SCHEMA app_schema;

CREATE OR REPLACE PROCEDURE app_schema.hidden_sum(num1 float, num2 float)
RETURNS FLOAT
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
  DECLARE
    SUM FLOAT;
  BEGIN
    SYSTEM$LOG('INFO', 'CALCULATE THE SUM OF TWO NUMBERS');
    SUM := :NUM1 + :NUM2;
    RETURN SUM;
  END;
$$;
Copy

Quando adicionados ao script de configuração do aplicativo, estes comandos SQL criam o procedimento armazenado hidden_sum na conta do consumidor quando o aplicativo é instalado. No entanto, este procedimento armazenado não é visível para os consumidores porque o privilégio USAGE não é concedido no procedimento armazenado para uma função de aplicativo.

O exemplo a seguir mostra como você pode usar os valores retornados pelas funções do sistema IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER e IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT para chamar o procedimento armazenado hidden_sum.

CREATE OR REPLACE PROCEDURE app_schema.sum(num1 float, num2 float)
RETURNS STRING
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
    BEGIN
      IF (SYSTEM$IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT() or SYSTEM$IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER()) THEN
        CALL APP_SCHEMA.HIDDEN_SUM(:NUM1, :NUM2);
      ELSE
        -- notify consumers that they need to enable event sharing
        RETURN 'Sorry you can\'t access the API, please enable event sharing.';
      END IF;
    END;
$$;


CREATE APPLICATION ROLE IF NOT EXISTS ADMIN_ROLE;
GRANT USAGE ON SCHEMA APP_SCHEMA TO APPLICATION ROLE ADMIN_ROLE;
Copy

Neste exemplo, o procedimento armazenado sum testa os valores dos procedimentos armazenados IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER e IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT. Se um dos seus valores for true, o procedimento armazenado sum chama o procedimento armazenado hidden_sum.

Solicite o compartilhamento de eventos dos consumidores usando o Python Permission SDK

Um provedor pode usar o Python Permission SDK para criar um aplicativo Streamlit para solicitar aos consumidores que habilitem o compartilhamento de eventos em suas contas.

O SDK fornece o método request_event_sharing() que exibe uma caixa de diálogo em Snowsight que solicita ao consumidor que habilite o compartilhamento de eventos em sua conta. Se a tabela de eventos não existir na conta do consumidor, a caixa de diálogo permite que o consumidor defina a tabela de eventos se estiver usando a função ACCOUNTADMIN.

Exemplo: uso do Python Permission SDK com tabelas de eventos

O exemplo a seguir do Streamlit mostra como usar o Python Permission SDK para fazer o seguinte:

  • Determine se o compartilhamento de eventos está habilitado.

  • Se o compartilhamento de eventos estiver habilitado, chame a função critical_feature_that_requires_event_sharing().

  • Se o compartilhamento de eventos não estiver habilitado, chame a função request_event_sharing() para exibir uma caixa de diálogo em Snowsight que solicita ao consumidor que habilite o compartilhamento de eventos.

import streamlit as st
import snowflake.permissions as permissions

def critical_feature_that_requires_event_sharing():
  st.write("critical_feature_that_requires_event_sharing")

def main():
  if permissions.is_event_sharing_enabled() or permissions.is_application_local_to_package():
     critical_feature_that_requires_event_sharing()
  else:
     permissions.request_event_sharing()

if __name__ == "__main__":
  main()
Copy

Neste exemplo, o método critical_feature_that_requires_event_sharing() só é chamado se uma das seguintes condições for verdadeira:

  • O compartilhamento de eventos está habilitado e a tabela de eventos existe.

  • O Snowflake Native App está instalado na mesma conta que o pacote do aplicativo.

Se nenhuma das condições for verdadeira, o aplicativo Streamlit chama o método request_event_sharing() que solicita ao consumidor que selecione uma tabela de eventos.

Para obter mais informações, consulte Determine se o compartilhamento de eventos está habilitado na conta do consumidor.

Linguagem: Português