为应用程序配置事件定义

本主题描述如何在应用程序的清单文件中定义事件定义。事件定义定义了与提供商共享哪些日志消息和跟踪事件。

关于事件定义

事件定义指定应用程序与提供商共享日志消息和跟踪事件的方式。事件定义充当提供商设置的日志消息和跟踪事件级别的筛选器。提供商指定发布应用程序新版本或补丁时应用程序的事件定义。

事件定义是作用于日志消息和跟踪事件的筛选器。由它们确定启用事件共享时在提供商事件表中插入哪些信息。

事件定义是可选的。如果提供商没有为应用程序指定事件定义，则使用者只能在提供商启用事件追踪时启用或禁用所有事件的事件共享。

Caution

事件定义与提供商设置的日志和跟踪级别不同。日志和跟踪级别确定插入到使用者事件表中的信息。如果既没有设置日志级别，也没有设置跟踪级别，则应用程序不会发出任何事件。

应用程序的日志和跟踪级别可根据使用者启用的事件定义进行更改。Snowflake 使用使用者启用的事件定义所允许的最详细的日志和跟踪级别。

强制和可选事件定义

提供商可以将事件定义设置为必需或可选：

安装应用程序时，将自动启用所需的事件定义。

After installing an app with required event definitions, consumers cannot disable event sharing or the required event definitions. When an app is being upgraded, providers can use system functions or the Python Permission SDK to check if the consumer has enabled all required event definitions.
使用者可根据需要启用或禁用可选事件定义。

支持的事件定义

以下表格列出了当前支持的事件定义。

Type	Name	Description	Filter
All	SNOWFLAKE$ALL	Shares all log messages and trace events that the app emits.	`*`
Events	SNOWFLAKE$ALL_EVENTS	Shares all events from the application.	`RECORD_TYPE='EVENT'`
Errors and warnings	SNOWFLAKE$ERRORS_AND_WARNINGS	Shares logs related to errors, warnings, and fatal events.	`RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)`
Traces	SNOWFLAKE$TRACES	Shares detailed traces of user activities and journeys in the application.	`RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)`
Usage logs	SNOWFLAKE$USAGE_LOGS	Shares high-level logs related to user actions and app events.	`RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’`
Debug logs	SNOWFLAKE$DEBUG_LOGS	Shares technical logs used to troubleshoot the app.	`RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)`
Metrics	SNOWFLAKE$METRICS	Enable consumers to share metrics with providers.	`RECORD_TYPE in (‘METRIC’)`

Note

Snowsight only displays the all event All type to the consumer if the provider has not configured the app to use event definitions.

带有容器的应用程序中事件定义的限制

Snowflake Native Apps with Snowpark Container Services currently only support the SNOWFLAKE$ALL event definition. Granular event definitions for containerized apps will be added in a future release. Container telemetry levels are configured in the service specification rather than the manifest file. The manifest log_level does not propagate into containers.

为应用程序设置日志和跟踪级别

要允许应用程序使用事件跟踪，提供商必须在清单文件中配置日志和跟踪级别。

To set the log and trace levels for an app, add a configuration block in the manifest file as shown in the following example:

configuration:
  ...
  log_level: INFO
  trace_level: ALWAYS
  metric_level: ALL
  log_event_level: INFO
  ...

此示例将应用程序的日志和跟踪级别设置如下：

The log_level property is set to INFO.
The trace_level property is set to ALWAYS.
The metric_level property is set to ALL.
The log_event_level property is set to INFO.

See LOG_LEVEL, TRACE_LEVEL, METRIC_LEVEL, and LOG_EVENT_LEVEL for information on the valid values for these parameters.

LOG_EVENT_LEVEL was introduced in BCR bundle 2026_02 and controls which application lifecycle events (RECORD_TYPE=EVENT) are recorded, separately from log messages controlled by log_level. Supported severity values are TRACE, DEBUG, INFO, WARN, ERROR, FATAL, and OFF.

Caution

在发布应用程序后，日志和跟踪级别将无法更改。如果在清单文件中未设置日志和跟踪级别，则应用程序不会发出任何信息。

当为应用程序设置日志和跟踪级别时，使用者必须在其账户中设置一个事件表，以查看应用程序发出的日志消息和跟踪事件。

To allow the provider to see the log messages and trace events that an app generates, consumers must enable event sharing. See Enable event sharing for an app for more information.

将事件定义添加到清单文件

To specify an event definition, a provider adds an entry to the configuration.telemetry_event_definitions block of the manifest file as shown in the following example:

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

此示例指定以下事件定义：

A required event definition with type ERRORS_AND_WARNINGS.
An optional event definition with type DEBUG_LOGS.

See Supported event definitions for more information.

After a consumer installs an app, the event definitions appears in the Events and logs tab on the Security page of the app. See Enable logging and event sharing for an app for more information.

为特定对象设置日志、跟踪和指标级别

提供商可微调应用程序中特定对象的日志、跟踪和指标级别。这让提供商能够更好地控制应用程序发出的遥测数据。

提供商可以为应用程序中的以下对象设置日志、跟踪和指标级别：

架构
版本化架构
存储过程
用户定义的函数

下表列出了用于设置这些对象的日志、跟踪和事件级别的 SQL 命令：

Object	Command
Schemas	ALTER SCHEMA
Versioned schema	CREATE OR ALTER VERSIONED SCHEMA
Stored procedures	ALTER PROCEDURE
User-defined functions	ALTER FUNCTION

For schemas, stored procedures, and user-defined functions, providers can use the SET clause of the ALTER commands to set the following properties:

LOG_LEVEL
TRACE_LEVEL
METRIC_LEVEL

For versioned schemas providers can set these properties using CREATE OR ALTER VERSIONED SCHEMA in the setup script.

日志、跟踪和指标级别的优先顺序

Within an app, the log, trace, and metric levels can be configured in different ways for components of the app. To determine the events that are emitted, the Snowflake Native App Framework uses the following order of precedence:

存储过程和用户定义的函数

如果为特定存储过程或用户定义的函数设置了替换，则以此为先。

架构和版本化架构

如果未为存储过程或用户定义的函数设置替换，则架构和版本化架构的替换优先。

应用程序级设置

如果未找到对象级替换，则使用应用程序级遥测配置（通常在清单文件中定义）。