为应用程序设置事件跟踪¶
本主题介绍了如何设置使用事件跟踪来捕获应用程序发出的日志消息和跟踪事件。其中还介绍了如何启用事件共享，以便与提供商共享日志消息和跟踪事件。
关于 Snowflake Native App Framework 中的事件跟踪¶
事件跟踪允许应用程序发出与其性能和行为相关的信息。Snowflake Native App Framework 支持使用 Snowflake 日志记录和跟踪 功能来收集这些信息。应用程序可以发出以下内容：
日志消息：独立的详细消息，包含有关应用程序内特定功能状态的信息。
带有结构化数据的跟踪事件：可用于获取跨越和分组应用程序中多个部分的信息。
查看应用程序的日志消息和事件¶
要查看应用程序发出的日志消息和跟踪事件，使用者必须在其账户中设置事件表以收集这些信息。有关更多信息，请参阅 设置事件表。
关于事件共享¶
使用者还可以启用事件共享，以便与提供商共享事件数据。当提供商启用事件共享时，插入到使用者账户事件表中的日志消息和跟踪事件也会插入到提供商账户的事件表中。
事件共享允许提供商收集有关应用程序性能和行为的信息。有关更多信息，请参阅 关于应用程序事件共享。
关于事件定义¶
事件定义指定应用程序与提供商共享日志消息和跟踪事件的方式。事件定义充当提供商设置的日志消息和跟踪事件级别的筛选器。提供商指定发布新版本或补丁时应用程序的事件定义。
备注
不需要事件定义。如果提供商没有为应用程序指定事件定义，则使用者可以根据需要启用或禁用事件共享。
提供商可以将事件定义设置为必需或可选：
安装应用程序时，将自动启用所需的事件定义。要收集应用程序发出的事件定义，使用者应创建一个事件表，并将其设置为账户的活动事件表。
使用者可以根据需要启用或禁用可选事件定义。可选事件定义需要活动事件表，但安装或使用应用程序时并不需要。
小心
事件定义与提供商设置的日志和跟踪级别不同。日志和跟踪级别确定插入到使用者事件表中的信息。
事件定义是作用于日志消息和跟踪事件的筛选器。由它们确定启用事件共享时在提供商事件表中插入哪些信息。
支持的事件定义¶
下表列出了当前支持的事件定义：
类型
名称
描述
筛选器
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’)
备注
如果提供商未将应用程序配置为使用事件定义，则 Snowsight 仅显示 All 类型。
使用者使用事件定义时的注意事项¶
使用者可以继续使用现有 SHARE_EVENTS_WITH_PROVIDER 属性，但要遵循一些限制：
如果应用程序仅使用 OPTIONAL ALL 事件定义，则将 SHARE_EVENTS_WITH_PROVIDER 属性设置为
true可启用事件共享，而将其设置为false可禁用事件共享。此情况适用于提供商显式添加 OPTIONAL ALL 事件定义到清单文件或应用程序从现有事件共享功能迁移的情况。
如果提供商向清单文件添加强制和可选事件定义，则将 SHARE_EVENTS_WITH_PROVIDER 属性设置为
true启用所有事件定义。相反，只有在提供商仅添加可选事件定义时，才能将 SHARE_EVENTS_WITH_PROVIDER 属性设置为false。仅当启用所有事件定义时 SHARE_EVENTS_WITH_PROVIDER 才为 TRUE，否则为 FALSE。
为应用程序设置事件跟踪的工作流程¶
以下工作流程介绍如何为应用程序设置事件跟踪：
使用事件跟踪时的注意事项¶
在为应用程序启用事件跟踪之前，必须考虑以下事项：
要使用此功能，需在账户中 设置事件表。
启用事件共享 后，系统将在指定提供商账户的事件表中自动插入跟踪事件和日志消息的已脱敏和已编辑副本。
Snowflake 不收取启用事件共享的相关费用。不过，您需要承担在事件表中引入跟踪事件和日志消息的成本，以及事件表的存储成本。
与提供商共享事件后，您无法撤消对共享跟踪事件和日志消息的访问权限。
您无法使用事件共享来共享历史事件。
Snowflake 会将共享事件发送到与您的账户位于同一区域的指定提供商账户。此功能不会跨不同区域共享数据。
您无法更改应用程序的日志记录或跟踪级别。应用程序提供商将在发布应用程序时设置这些级别。
Snowflake 建议在启用事件共享之前查看事件表中的跟踪事件和日志消息。
如果您不需要对应用程序进行故障排除，Snowflake 建议禁用事件共享。
设置事件表¶
要收集应用程序发出的日志消息和跟踪事件，使用者必须创建一个事件表来存储信息。
备注
IF 使用者未在安装应用程序之前设置事件表并将其设为活动事件表，则跟踪事件和日志数据将被丢弃。
如果提供商在应用程序中包含了所需的事件定义，则在安装期间会默认启用这些事件定义。但是，如果使用者没有活动事件表，则应用程序发出的日志消息和跟踪事件将被丢弃。
一个账户可以有多个事件表，但一次只能将其中一个设置为 Snowflake 账户中的活动事件表。如果没有活动事件表，则无法获取应用程序发出的日志消息和跟踪事件。即使应用程序中的函数和程序直接调用了日志记录和跟踪事件 APIs，也是如此。
要创建事件表，请运行 CREATE EVENT TABLE 命令，如以下示例所示：
CREATE EVENT TABLE event_db.event_schema.my_event_table;
请注意，此命令指定包含事件表的数据库和架构。
创建事件表后，使用 ALTER ACCOUNT 命令将事件表指定为账户的活动表：
ALTER ACCOUNT SET EVENT_TABLE=event_db.event_schema.my_event_table;
为应用程序启用事件共享¶
Snowflake Native App Framework 支持与应用程序提供商共享存储在使用者事件表中的日志消息和跟踪事件。要与提供商共享日志和事件信息，使用者必须为应用程序启用事件共享。
为应用程序程序启用事件共享的先决条件¶
必须满足以下先决条件，才能为应用程序程序实例启用事件共享：
使用具有 MANAGE EVENT SHARING 全局权限的角色。ACCOUNTADMIN 角色默认具有此权限，也可以将此权限授予其他角色。
使用 Snowsight 启用事件共享¶
备注
如果提供商在应用程序程序中包含了所需的 事件定义，则在安装期间启用事件共享和所需的事件定义，且以后无法禁用。
要为应用程序程序启用事件共享，请执行以下步骤：
登录 Snowsight。
在导航菜单中，选择 Data Products » Apps。
选择应用程序。
选择工具栏中的 Settings 图标。
选择 Events and logs 选项卡。
在 Events and logs sharing 区域下，选择 Enable。
如果提供商已为应用程序程序定义了事件定义，请执行以下操作：
使用滑块启用可选事件定义。
选择 Review。
如果当前未选择任何事件表，请从 Event table location 下的列表中选择事件表。
小心
请小心地在 Snowsight 中更改事件表。每个 Snowflake 账户对账户内生成的所有事件使用一个事件表。更改事件表会导致账户中生成的所有事件都存储在新位置。
使用 SQL 启用事件共享¶
要使用 SQL 为应用程序程序启用事件共享，请执行以下步骤：
使用 SHOW TELEMETRY EVENT DEFINITIONS 命令来确定应用程序程序的事件定义：
SHOW TELEMETRY EVENT DEFINITIONS IN APPLICATION hello_snowflake;
如果提供商未将应用程序程序配置为使用事件定义，则
type列会显示ALL。否则，此命令会列出为应用程序程序指定的可选事件定义。如果应用程序程序包含所需事件定义，则使用 ALTER APPLICATION 命令来启用它们：
ALTER APPLICATION hello_snowflake SET AUTHORIZE_TELEMETRY_EVENT_SHARING=true
此命令启用所有所需事件定义，但不启用可选事件定义。
备注
为应用程序程序启用所需的事件定义后，无法禁用事件共享。
如果应用程序程序包含可选事件定义，则使用 ALTER APPLICATION 来启用它们，如以下示例所示：
ALTER APPLICATION hello_snowflake SET SHARED TELEMETRY EVENTS ('SNOWFLAKE$TRACES', 'SNOWFLAKE$DEBUG_LOGS');
此示例根据 SHOW TELEMETRY EVENT DEFINITIONS 命令的输出来启用
SNOWFLAKE$TRACES和SNOWFLAKE$DEBUG_LOGS。要验证是否启用了事件跟踪和日志记录，请使用 DESC APPLICATION 命令：
DESC APPLICATION hello_snowflake;
输出的
authorize_telemetry_event_sharing和share_events_with_provider行表示是否启用了事件共享。
使用 SQL 启用事件共享（旧功能）¶
小心
本节中描述的使用 SQL 启用事件共享的方法将在未来的版本中弃用。Snowflake 建议采用 使用 SQL 启用日志和事件共享 中所述的方法，以通过 SQL 启用事件共享。
要为应用程序程序启用事件共享，请运行 ALTER APPLICATION 命令，以将 SHARE_EVENTS_WITH_PROVIDER 设置为 TRUE。例如：
ALTER APPLICATION HelloSnowflake SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
要显示应用程序程序的事件共享状态，请使用 DESC APPLICATION 命令，如以下示例所示：
DESC APPLICATION HelloSnowflake;
SHARE_EVENTS_WITH_PROVIDER 显示应用程序程序的事件共享状态。
在升级期间启用事件定义¶
在升级期间，事件定义的行为如下：
事件定义变更
升级期间的行为
事件定义无变更
事件定义将保留与先前版本或补丁相同的状态。
新事件定义
未自动启用。对于必需和可选事件定义都是如此。使用者必须手动启用新事件定义。
从必需更改为可选或可选更改为必需
事件定义将保留与先前版本或补丁相同的状态。
删除事件定义
在升级后，日志消息或跟踪事件过滤器（基于先前版本或补丁）将停止事件共享。
在升级期间，系统会提示使用者查看之前的补丁或版本中对事件定义所做的变更。
查看事件表中的日志消息和跟踪事件¶
WHen 启用事件表，使用者可以查询事件表以查看应用程序发出的日志消息和跟踪事件。可使用 SELECT 命令查询事件表，例如：
SELECT * FROM event_db.event_schema.my_event_table;
此命令返回存储在事件表中的所有日志消息和跟踪事件。
查看应用程序的日志记录和跟踪级别¶
应用程序程序的日志和跟踪级别由提供商在发布应用程序程序之前定义。使用者无法更改应用程序程序的日志和跟踪级别。
但是，在为应用程序设置事件跟踪或启用事件共享之前，Snowflake 建议验证日志级别，以了解收集并与提供商共享的信息类型。
要查看应用程序程序的日志和跟踪级别，请运行以下命令：
DESC APPLICATION HelloSnowflake;
此命令显示有关 HelloSnowflake 应用程序程序的信息，包括有关为应用程序程序设置的日志和跟踪级别的以下信息：
log_level：提供商在清单文件中定义的日志级别。
trace_level：提供商在清单文件中定义的跟踪级别。
effective_log_level：为应用程序程序启用的日志级别。
effective_trace_level：为应用程序程序启用的跟踪级别。
有效的日志和跟踪级别由使用者为应用程序启用的事件定义确定。
例如，如果提供者将日志级别定义为 OFF，但使用者启用了 ERROR_AND_WARNING 事件定义，则应用程序程序会动态更改日志级别为 WARN，以便可以收集 ERROR_AND_WARNING 事件。应用程序发出不超过 WARN 级别的事件，并与提供商共享这些错误和警告事件。Log_level 的值为 OFF，effective_log_level 的值为 WARN。
相比之下，如果提供商将日志级别定义为 TRACE，但使用者启用了 ERROR_AND_WARNING 事件定义，则应用程序程序发出的事件的级别不超过跟踪事件，但仅与提供商共享错误和警告消息。Log_level 和 effective_log_level 的值都为 TRACE。