为应用程序配置事件定义¶

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

关于事件定义¶

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

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

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

小心

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

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

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

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

在安装了具有所需事件定义的应用程序后，使用者无法禁用事件共享或所需的事件定义。当应用程序正在升级时，提供商可以使用系统函数或 Python Permission SDK 来查看使用者是否已启用所有必需的事件定义。
使用者可根据需要启用或禁用可选事件定义。

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

类型	名称	描述	筛选器
All	SNOWFLAKE$ALL	共享应用程序发出的所有日志消息和跟踪事件。	`*`
Errors and warnings	SNOWFLAKE$ERRORS_AND_WARNINGS	共享与错误、警告和致命事件相关的日志。	`RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘FATAL’, ‘ERROR’, ‘WARN’)`
Traces	SNOWFLAKE$TRACES	共享应用程序中用户活动和操作路径的详细跟踪。	`RECORD_TYPE in (‘SPAN’, ‘SPAN_EVENT’)`
Usage logs	SNOWFLAKE$USAGE_LOGS	共享与用户操作和应用程序事件相关的概要日志。	`RECORD_TYPE = LOG AND RECORD:severity_text = ‘INFO’`
Debug logs	SNOWFLAKE$DEBUG_LOGS	共享用于对应用程序进行故障排除的技术日志。	`RECORD_TYPE = ‘LOG’ AND RECORD:severity_text in (‘DEBUG’, ‘TRACE’)`
Metrics	SNOWFLAKE$METRICS	让使用者能够与提供商共享指标。	`RECORD_TYPE in (‘METRIC’)`

备注

如果提供商没有将应用程序配置为使用事件定义，那么 Snowsight 只会向使用者显示所有事件 All 类型。

Snowflake Native Apps with Snowpark Container Services 目前仅支持 ALL 事件定义。对其他事件定义的支持将在未来的版本中添加。

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

要为应用程序设置日志和跟踪级别，请在 manifest.yml 文件中添加一个 configuration 块，如以下示例所示：

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

Copy

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

有关这些参数有效值的信息，请参阅 LOG_LEVEL、TRACE_LEVEL 和 METRIC_LEVEL。

小心

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

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

为让提供商查看应用程序生成的日志消息和跟踪事件，使用者必须启用事件共享。有关更多信息，请参阅为应用程序启用事件共享。

要指定事件定义，提供商会在清单文件的 configuration.telemetry_event_definitions 块中添加一个条目，如下例所示：

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

Copy

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

有关更多信息，请参阅支持的事件定义。

在使用者安装应用程序后，事件定义将出现在应用程序 Security 页面上的 Events and logs 选项卡中。有关更多信息，请参阅为应用程序启用日志记录和事件共享。

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

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

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

对象	命令
架构	ALTER SCHEMA
版本化架构	CREATE OR ALTER VERSIONED SCHEMA
存储过程	ALTER PROCEDURE
用户定义的函数	ALTER FUNCTION

对于架构、存储过程和用户定义的函数，提供商可以使用 ALTER 命令的 SET 子句来设置以下属性：

对于版本化架构，提供商可以在设置脚本中使用 CREATE OR ALTER VERSIONED SCHEMA 来设置这些属性。

在应用程序中，可以采用不同方式为应用程序的组件配置日志、跟踪和指标级别。为了确定发出的事件，Snowflake Native App Framework 使用以下优先顺序：