为应用程序设置事件跟踪

本主题介绍了如何设置使用事件跟踪来捕获应用程序发出的日志消息和跟踪事件。其中还介绍了如何启用事件共享，以便与提供商共享日志消息和跟踪事件。

About event tracing in the Snowflake Native App Framework¶

Event tracing allows an app to emit information related to its performance and behavior. The Snowflake Native App Framework supports using the Snowflake logging and tracing. functionality to gather this information. An app can emit the following:

• Log messages that are independent, detailed messages with information about the state of a specific feature within the app.
• Trace events with structured data you can use to get information spanning and grouping multiple parts of an app.
• 包含 CPU 的指标数据和 Snowflake 生成的内存指标。

查看应用程序的日志消息、跟踪事件和指标

To view the log messages and trace events emitted by the app, consumers must set up an event table in their account to collect this information. See Set up an event table for more information.

关于事件共享

使用者还可以启用事件共享，以便与提供商共享事件数据。当提供商启用事件共享时，插入到使用者账户事件表中的日志消息和跟踪事件也会插入到提供商账户的事件表中。

Event sharing allows the provider to collect information about the app’s performance and behavior. See About event sharing for an app for more information.

关于事件定义

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

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

• Required event definitions are enabled automatically when the app is installed. To collect the event definitions emitted by an app, a consumer should create an event table and set it as the active event table for their account.
• Optional event definitions can be enabled or disable by the consumer as necessary. Optional event definitions require an active event table, but they are not required to install or use the app.

支持的事件定义

下表列出了当前支持的事件定义：

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’)
Metrics	SNOWFLAKE$METRICS	Shares the CPU and memory metrics that Snowflake generates.	RECORD_TYPE = in ('METRIC')
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’)

Expand

Show lessSee more

使用者使用事件定义时的注意事项

使用者可以继续使用现有 SHARE_EVENTS_WITH_PROVIDER 属性，但要遵循一些限制：

• If an app only uses the OPTIONAL ALL event definition, setting the SHARE_EVENTS_WITH_PROVIDER property to true enables event sharing and setting it to false disables event sharing.

此情况适用于提供商显式添加 OPTIONAL ALL 事件定义到清单文件或应用程序从现有事件共享功能迁移的情况。

• If a provider adds mandatory and optional event definitions to the manifest file, setting the SHARE_EVENTS_WITH_PROVIDER property to true enables all event definitions. In contrast, the SHARE_EVENTS_WITH_PROVIDER property can only be set to false if the provider adds only optional event definitions.

仅当启用所有事件定义时 SHARE_EVENTS_WITH_PROVIDER 才为 TRUE，否则为 FALSE。

为应用程序设置事件跟踪的工作流程

以下工作流程介绍如何为应用程序设置事件跟踪：

1. Review the considerations for using logging and event tracing.
2. Set up an event table.
3. View the logging and trace event levels configured for the app.
4. View the events in the event table.
5. Enable event sharing on an app.

使用事件跟踪时的注意事项

在为应用程序启用事件跟踪之前，必须考虑以下事项：

• This feature requires you to set up an event table in your account.
• After you enable event sharing, a masked and redacted copy of the trace events and logs messages is automatically inserted in the event table of the designated provider account.
• Snowflake does not charge you to enable event sharing. However, you are responsible for the cost of ingesting trace events and log message in the event table as well as storage costs for the event table.
• After enabling event sharing with a provider, you cannot revoke access to shared trace events and log messages.
• 您无法使用事件共享来共享历史事件。
• Snowflake sends the shared events to a designated provider account within the same region as your account. This feature does not share data across different regions.
• You cannot change the logging or tracing levels for an app. The app provider sets these levels when publishing the app.
• Snowflake recommends reviewing the trace events and log messages in the event table before enabling event sharing.
• 如果您不需要对应用程序进行故障排除，Snowflake 建议禁用事件共享。

设置事件表

要收集应用程序发出的日志消息和跟踪事件，使用者必须创建一个事件表来存储信息。

一个账户可以有多个事件表，但一次只能将其中一个设置为 Snowflake 账户中的活动事件表。如果没有活动事件表，则无法获取应用程序发出的日志消息和跟踪事件。即使应用程序中的函数和程序直接调用了日志记录和跟踪事件 APIs，也是如此。

To create an event table, run the CREATE EVENT TABLE command as shown in the following example:

CREATE EVENT TABLE event_db.event_schema.my_event_table;

请注意，此命令指定包含事件表的数据库和架构。

After creating the event table, use the ALTER ACCOUNT command to specify that the event table is the active table for the account:

ALTER ACCOUNT SET EVENT_TABLE=event_db.event_schema.my_event_table;

为应用程序启用事件共享

The Snowflake Native App Framework supports sharing log messages and trace events stored in the consumer event table with the app provider. To share logs and event information with a provider, the consumer must enable event sharing for an app.

为应用程序程序启用事件共享的先决条件

必须满足以下先决条件，才能为应用程序程序实例启用事件共享：

• Use a role with the MANAGE EVENT SHARING global privilege. The ACCOUNTADMIN role has this privilege by default and can grant it to other roles.
• Set up an event table in the consumer account.

Enable event sharing using Snowsight¶

1. Sign in to Snowsight.

2. In the navigation menu, select Catalog » Apps.

3. 选择应用程序。

4. Select the Settings icon in the toolbar.

5. Select the Events and logs tab.

6. Under the Events and logs sharing area, move the slider for the events you want to capture.

7. 如果提供商已为应用程序程序定义了事件定义，请执行以下操作：

   1. 使用滑块启用可选事件定义。默认情况下，所有事件类型都处于已启用状态。
   2. Select Save.

8. If no event table is currently selected, select the event table from the list under Event table location.

   Caution

   Use caution when changing the event table in Snowsight. Each Snowflake account uses a single event table for all events generated within the account. Changing the event table causes all events generated in the account to be stored in the new location.

使用 SQL 启用事件共享¶

1. Use the SHOW TELEMETRY EVENT DEFINITIONS command to determine the event definitions for the app:

   Copy codeExpand code block

   SHOW TELEMETRY EVENT DEFINITIONS IN APPLICATION hello_snowflake;

   Show lessSee more

   Scroll to top

   If the provider did not configure the app to use event definitions, the type column displays ALL. Otherwise, this command lists the optional event definitions specified for the app.

2. If the app contains required event definitions, use the ALTER APPLICATION command to enable them:

   Copy codeExpand code block

   ALTER APPLICATION hello_snowflake SET AUTHORIZE_TELEMETRY_EVENT_SHARING=true

   Show lessSee more

   Scroll to top

此命令启用所有所需事件定义，但不启用可选事件定义。

3. If the app contains options event definitions, use the use the ALTER APPLICATION to enable them as shown in the following example:

   Copy codeExpand code block

   ALTER APPLICATION hello_snowflake SET SHARED TELEMETRY EVENTS ('SNOWFLAKE$TRACES', 'SNOWFLAKE$DEBUG_LOGS');

   Show lessSee more

   Scroll to top

   This example enables the SNOWFLAKE$TRACES and SNOWFLAKE$DEBUG_LOGS based on the output of the SHOW TELEMETRY EVENT DEFINITIONS command.

4. To verify that event tracing and logging is enabled, use the DESCRIBE APPLICATION command:

   Copy codeExpand code block

   DESC APPLICATION hello_snowflake;

   Show lessSee more

   Scroll to top

   The authorize_telemetry_event_sharing and share_events_with_provider rows of the output indicate if event sharing is enabled.

使用 SQL 启用事件共享（已弃用功能）¶

To enable event sharing for an app, run the ALTER APPLICATION command to set SHARE_EVENTS_WITH_PROVIDER to TRUE. For example:

ALTER APPLICATION HelloSnowflake SET SHARE_EVENTS_WITH_PROVIDER = TRUE;

To show the event sharing status for an app, use the DESCRIBE APPLICATION command as shown in the following example:

DESC APPLICATION HelloSnowflake;

SHARE_EVENTS_WITH_PROVIDER shows the status of event sharing for the app.

在升级期间启用事件定义

在升级期间，事件定义的行为如下：

事件定义变更	升级期间的行为
事件定义无变更	事件定义将保留与先前版本或补丁相同的状态。
新事件定义	未自动启用。对于必需和可选事件定义都是如此。使用者必须手动启用新事件定义。
从必需更改为可选或可选更改为必需	事件定义将保留与先前版本或补丁相同的状态。
删除事件定义	在升级后，日志消息或跟踪事件过滤器（基于先前版本或补丁）将停止事件共享。

Expand

Show lessSee more

在升级期间，系统会提示使用者查看之前的补丁或版本中对事件定义所做的变更。

查看事件表中的日志消息和跟踪事件

启用事件表后，使用者可以查询事件表以查看应用程序发出的日志消息和跟踪事件。

View the event log messages and trace events by using Snowsight¶

1. Sign in to Snowsight.
2. In the navigation menu, select Catalog » Apps.
3. 选择应用程序。
4. In the toolbar, select Settings.
5. Select the App events tab.
6. In the Event logging section, select View logs.

This opens a new worksheet with a pre-populated SELECT statement that displays the log messages and trace events for the app.

使用 SQL 查看事件日志消息和跟踪事件¶

Use the SELECT command to query the event log messages and trace events, as shown in the following example:

SELECT
  TIMESTAMP as time,
  RESOURCE_ATTRIBUTES['snow.executable.name'] as executable,
  RECORD['severity_text'] as severity,
  VALUE as message
FROM
  "EVENT_LOG"."PUBLIC"."CONSUMER_EVENT_TABLE"
WHERE RESOURCE_ATTRIBUTES['snow.application.name'] = 'YOUR_APP_NAME'

This command returns all of the log messages and trace events stored in the event table CONSUMER_EVENT_TABLE for an app named YOUR_APP_NAME.

确定是否与提供商共享日志消息或跟踪事件

The RECORD_ATTRIBUTES column contains the snow.application.shared field. If the value of this field is TRUE, the log message or trace event is shared with the provider. Otherwise, the log message or event is not shared.

查看应用程序的日志记录和跟踪级别

应用程序程序的日志和跟踪级别由提供商在发布应用程序程序之前定义。使用者无法更改应用程序程序的日志和跟踪级别。

但是，在为应用程序设置事件跟踪或启用事件共享之前，Snowflake 建议验证日志级别，以了解收集并与提供商共享的信息类型。

要查看应用程序程序的日志和跟踪级别，请运行以下命令：

DESC APPLICATION HelloSnowflake;

This command displays information about the HelloSnowflake app, including the following information about the log and trace level set for the app:

• log_level：提供商设置的日志级别。
• trace_level：提供商设置的跟踪级别。
• metric_level：提供商设置的指标数据级别。
• log_event_level: The log event level set by the provider.
• effective_log_level：为应用程序设置的日志级别。
• effective_trace_level：为应用程序程序启用的跟踪级别。

有效的日志和跟踪级别由使用者为应用程序启用的事件定义确定。

For example, if the provider defines the log level as OFF, but consumer enables the ERROR_AND_WARNING event definition, the app dynamically changes log level to WARN so that ERROR_AND_WARNING events can be collected. The app emits events that are less or equally as verbose as WARN and shares those error and warning events with the provider. The values of log_level would be OFF and the value of effective_log_level would be WARN.

相比之下，如果提供商将日志级别定义为 TRACE，但使用者启用了 ERROR_AND_WARNING 事件定义，则应用程序程序发出的事件的级别不超过跟踪事件，但仅与提供商共享错误和警告消息。Log_level 和 effective_log_level 的值都为 TRACE。

Privacy and masking¶

Telemetry is filtered and transformed before it leaves your account. Fields fall into three categories:

• Shared: general app and organizational context essential for support (for example, APPLICATION_PROVIDER_ORG, LISTING_NAME).
• Masked: sensitive identifiers hashed so providers can correlate events without seeing raw values (for example, snow.database.hash, snow.query.hash, snow.application.hash). Application name and application instance name are not shared in clear text; they are hashed.
• Omitted: fields that never leave the consumer account (for example, snow.user.name, snow.warehouse.name, snow.session.id).

Hashing today uses SHA-1, exposed via SYSTEM$GET_HASH_FOR_APPLICATION so consumers can derive the same hash for support interactions.

For the authoritative categorized list of shared, masked, and omitted fields (including SPCS identifiers), see the field categorization table in Set up and manage an event table in the provider account.

Cost ownership¶

As a consumer, you own the cost of your event table:

• You pay for event storage in your account; you do not pay for sharing telemetry to the provider’s event account.
• You cannot revoke events that have already been shared. To stop sharing future events, disable event sharing for the application.
• Historical events are not backfilled when sharing is enabled.
• Events only share within the same region. Cross-region centralization is the provider’s responsibility.

To control your event-table cost, scope event sharing to the event definitions you actually need (for example, ERRORS_AND_WARNINGS and METRICS may be sufficient for most apps; reserve DEBUG_LOGS and TRACES for active troubleshooting).