Determinação das definições de evento no arquivo de manifesto de um aplicativo¶

Este tópico descreve como determinar definições de evento no arquivo de manifesto de um aplicativo. As definições de eventos determinam quais mensagens de log e eventos de rastreamento são compartilhados com um provedor.

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 do aplicativo é publicado.

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.

As definições de eventos são opcionais. Se um provedor não especificar as definições de evento para um aplicativo, os consumidores só poderão habilitar ou desabilitar o compartilhamento de evento para todos os eventos quando o provedor habilitar o rastreamento de evento.

Cuidado

As definições de evento diferem dos níveis de log e o rastreamento definido pelo provedor. Os níveis de log e rastreamento determinam as informações inseridas na tabela de evento do consumidor. Se nem o nível de log nem o de rastreamento estiver definido, o aplicativo não emitirá nenhum evento.

Os níveis de log e rastreamento de um aplicativo podem mudar com base nas definições de evento habilitadas pelo consumidor. O Snowflake usa os níveis de log e rastreamento mais detalhados permitidos pelas definições de evento que o consumidor habilitou.

Definições de evento obrigatórias e opcionais¶

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.

Após instalar um aplicativo com as definições de evento necessárias, os consumidores não podem desabilitar o compartilhamento de evento ou as definições de evento necessárias. Quando um aplicativo está sendo atualizado, os provedores podem usar funções do sistema ou Python Permission SDK para verificar se o consumidor habilitou todas as definições de evento necessárias.
Definições de evento opcionais podem ser habilitadas ou desabilitadas pelo consumidor conforme necessário.

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

Snowsight só exibe todo o tipo de evento All para o consumidor se o provedor não tiver configurado o aplicativo para usar definições de evento.

Limitações de definição de evento em aplicativos com contêiner¶

Snowflake Native Apps with Snowpark Container Services atualmente é compatível apenas com a definição de evento ALL. O suporte para definições de evento adicionais será incluído em um lançamento futuro.

Definição dos níveis de log e rastreamento para um aplicativo¶

Para permitir que um aplicativo use o rastreamento de evento, um provedor deve configurar os níveis de log e rastreamento no arquivo de manifesto.

Para definir os níveis de log e rastreamento de um aplicativo, adicione um bloco configuration no arquivo manifest.yml, conforme mostrado no exemplo a seguir:

configuration:
  ...
  log_level: INFO
  trace_level: ALWAYS
  ...

Copy

Este exemplo define os níveis de log e rastreamento para o aplicativo da seguinte forma:

A propriedade log_level está definida como INFO.
A propriedade trace_level está definida como ALWAYS.

Consulte LOG_LEVEL e TRACE_LEVEL para obter informações sobre os valores válidos para esses parâmetros.

Cuidado

Após publicar um aplicativo, os níveis de log e rastreamento não podem ser alterados. Se os níveis de log e rastreamento não estiverem definidos no arquivo de manifesto, o aplicativo não emitirá nenhuma informação.

Quando os níveis de log e rastreamento são definidos para um aplicativo, os consumidores devem definir uma tabela de evento em sua conta para ver as mensagens de log e os eventos de rastreamento que o aplicativo emite.

Para permitir que o provedor veja as mensagens de log e rastreie eventos gerados por um aplicativo, os consumidores devem habilitar o compartilhamento de evento. Consulte Habilitação de compartilhamento de evento para um aplicativo para obter mais informações.

Como adicionar uma definição de evento ao arquivo de manifesto¶

Para especificar uma definição de evento, um provedor adiciona uma entrada ao bloco configuration.telemetry_event_definitions do arquivo de manifesto, conforme mostrado no exemplo a seguir:

configuration:
  telemetry_event_definitions:
    - type: ERRORS_AND_WARNINGS
      sharing: MANDATORY
    - type: DEBUG_LOGS
      sharing: OPTIONAL

Copy

Este exemplo especifica as seguintes definições de evento:

Uma definição de evento necessária com o tipo ERRORS_AND_WARNINGS.
Uma definição de evento opcional com o tipo DEBUG_LOGS.

Consulte Definições de evento com suporte para obter mais informações.

Depois que um consumidor instala um aplicativo, as definições de evento aparecem na guia Events and logs na página Security do aplicativo. Consulte Habilitação do registro e compartilhamento de evento para um aplicativo para obter mais informações.