为应用程序设置日志记录和事件共享

本主题介绍如何设置日志记录和事件共享以排除已安装应用程序的故障。

本主题提供有关作为提供商设置日志记录和事件共享的信息。有关配置此功能时需满足的使用者要求，请参阅 为应用程序启用日志记录和事件共享。

日志记录和跟踪事件允许您收集有关应用程序的信息以排查错误。使用日志记录和跟踪事件，您还可以更好地了解应用程序的运行方式并在以后改进应用程序。

作为提供商设置日志记录和事件共享的工作流程

作为提供商，您可以通过执行以下操作来设置应用程序的日志记录和事件共享：

  1. 查看使用日志记录和事件共享的注意事项。

  2. 为函数和存储过程配置日志记录和跟踪事件。

  3. 在清单文件中设置日志和跟踪级别。

  4. 配置账户以存储共享事件。

使用者安装应用程序并启用日志记录和事件共享后，您可以查看已安装应用程序共享的日志和事件信息：

使用日志记录和事件共享时的注意事项

在为应用程序启用日志记录和事件共享之前，提供商必须考虑以下几点：

  • 提供商需承担提供商方面事件共享相关的所有费用，包括数据引入和存储。

  • 提供商必须在您想要支持事件共享的每个区域拥有 存储共享事件的账户。

  • 提供商必须在清单文件中定义应用程序的默认日志级别和跟踪级别。

备注

对于与作为基础的应用程序包安装在相同账户中的应用程序，无法启用事件共享。要测试应用程序的事件共享，提供商必须使用多个账户。

在函数和过程中配置日志记录和跟踪事件

Native Apps Framework 需要一个事件表来存储由应用程序中的函数和存储过程生成的日志消息和跟踪事件。

备注

如果应用程序的使用者在安装应用程序之前没有设置事件表并使其成为活动表，则事件和日志数据将被丢弃。

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

要创建事件表，请使用 CREATE EVENT TABLE 命令。有关更多信息，请参阅 设置事件表。

在代码记录了日志消息和跟踪事件之后，提供商可以查询记录的数据。

有关记录和查询日志和跟踪数据的信息，请参阅以下内容：

在清单文件中设置日志和跟踪级别

要设置应用程序某个版本的默认日志和跟踪事件级别，请设置清单文件中的 log_level 和 trace_level 参数，如下例所示：

artifacts:
  setup_script: setup.sql
configuration:
  trace_level: OFF
  log_level: DEBUG
Copy

在提供商启用跟踪时， Snowflake Native App 会自动获取所有查询和存储过程调用的开始时间和结束时间。

备注

如果将 trace_level 属性设置为 OFF 以外的值，则发布 Snowflake Native App 可能会向使用者账户中可查看事件表的任何用户公开对隐藏存储过程的调用。

有关 trace_level 和 log_level 的受支持值的信息，请参阅 设置跟踪级别 和 设置日志级别。

最初安装 Snowflake Native App 时，它使用清单文件中定义的日志级别。如果在后续升级中更改了日志级别，则新的日志级别将在升级过程完成后生效。

日志和跟踪级别只能在清单文件中设置。不允许使用者使用 ALTER APPLICATION 或 ALTER DATABASE 命令修改日志级别。

类似地，应用程序会忽略日志记录级别的任何会话级别设置。

配置账户以存储共享事件

要存储日志和共享事件，提供商必须选择一个账户来保存事件表。这可以是提供商可访问的任何账户。但是，如果组织有多个提供商发布应用程序包，请考虑使用专用于存储来自使用者的共享事件的 Snowflake 账户。

以下限制适用于存储共享事件的账户：

  • 您必须使用 ORGADMIN 角色将账户设置为用于存储事件的账户。

  • 该账户必须拥有 :ref:` 活动事件表 <label-nativeapps_provider_logging_procedures>`。

  • 指定的账户不能是以下任一账户：

    • 被锁定或暂停的账户。

    • 读者账户。

    • 试用账户。

    • Snowflake 管理账户。

备注

提供商只能在使用者安装应用程序的同一区域中收集日志和共享事件。提供商必须在使用者为应用程序配置事件共享的每个区域设置一个账户来存储共享事件。

将账户设置为事件账户

要将某个账户设置为某个区域的事件账户，请调用 SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION 系统函数：

CALL SYSTEM$SET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

其中：

snowflake_region

指定账户所在的区域，例如： AWS_US_WEST_2, AWS_US_EAST_1。

region_group

指定区域组，例如： PUBLIC。有关详细信息，请参阅 区域组。

account_name

指定账户名称。如果在指定区域中已将其他账户设置为事件账户，则运行此命令会将事件账户更改为此处指定的账户。

取消将账户设置为事件账户

要取消将某个账户设置为某个区域的事件账户，请调用 SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION 系统函数：

CALL SYSTEM$UNSET_EVENT_SHARING_ACCOUNT_FOR_REGION('<snowflake_region>', '<region_group>', '<account_name>')
Copy

其中：

snowflake_region

指定账户所在的区域，例如： AWS_US_WEST_2, AWS_US_EAST_1。

region_group

指定区域组，例如： PUBLIC。

account_name

指定账户名称。

查看提供商组织中的事件账户

要显示提供商组织中的事件账户，请调用 SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS 系统函数：

CALL SYSTEM$SHOW_EVENT_SHARING_ACCOUNTS()
Copy

备注

您必须使用该 ORGADMIN 角色来调用此函数。

此系统函数返回一个 JSON 格式的字符串，它包含组织内的事件账户列表。由于元数据需要一些时间才能传播到所有区域，因此在用户为组织设置/取消设置事件账户后，此函数在显示最新事件账户时可能会遇到一些延迟。

查看应用程序包中定义的日志记录和跟踪事件级别

使用 DESCRIBE APPLICATION 命令查看已安装应用程序的日志记录级别，如以下命令所示：

DESC APPLICATION HelloSnowflake;
Copy

使用 SHOW VERSIONS 命令查看应用程序包中定义的应用程序版本的日志记录级别，如下例所示：

SHOW VERSIONS
  IN APPLICATION PACKAGE HelloSnowflake;
Copy

查看事件表中的日志和事件

要查看事件表中存储的日志和事件，请使用 SELECT 命令，如下例所示：

SELECT * FROM EVENT_DB.EVENT_SCHEMA.MY_EVENT_TABLE
Copy

提供商可用的共享事件信息

以下部分介绍了 Native Apps Framework 与提供商共享的信息。

与提供商共享的应用程序事件上下文

为了帮助提供商轻松识别共享事件的来源，以下字段被填充至与提供商共享时事件表的 RESOURCE_ATTRIBUTES 列：

  • snow.application.package.name

  • snow.application.consumer.organization

  • snow.application.consumer.name

  • snow.listing.name

  • snow.listing.global_name

未与提供商共享的字段

为了保护使用者信息，来自 RESOURCE_ATTRIBUTES 列的以下字段不与提供商共享：

  • snow.database.id

  • snow.database.name

  • snow.schema.id

  • snow.executable.id

  • snow.owner.name

  • snow.owner.id

  • snow.warehouse.name

  • snow.warehouse.id

  • snow.query.id

  • snow.session.id

  • snow.session.role.primary.name

  • snow.session.role.primary.id

  • snow.user.name

  • snow.user.id

  • db.user

Snowflake 会以以下字段形式共享 snow.database.name 和 snow.query.id 字段的哈希值 (SHA-1)，而不是直接与提供商共享这两个字段：

  • snow.database.hash

  • snow.query.hash

Snowflake 提供用于掩盖这些属性的 SHA-1 函数。使用者可以计算数据库名称和查询 ID 的哈希值，并在联系提供商时将其用作参考值。

确定是否在使用者账户中启用了事件共享

某些情况下，提供商可能需要确定是否已在使用者账户中启用事件共享。例如，如果事件表不可用，提供商可能需要禁用应用程序功能。

要确定是否在使用者账户中启用了事件共享，提供商可在定义应用程序逻辑时调用以下系统函数：

  • IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER

    如果应用程序启用了事件共享，并且使用者账户中提供了活跃事件表，则返回 TRUE。否则返回 FALSE。

  • IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT

    如果应用程序与作为其基础的应用程序包安装在相同的账户中，则返回 TRUE。否则返回 FALSE。

备注

只能从应用程序内部调用这些系统函数。请参阅 确定是否使用 Python Permission SDK 启用了事件共享 和 确定是否使用 SQL 启用了事件共享

确定是否使用 Python Permission SDK 启用了事件共享

Python Permission SDK 提供以下函数，以确定使用者账户中是否启用了事件共享：

  • is_event_sharing_enabled()

    如果 SHARE_EVENTS_WITH_PROVIDER 属性为 true，并且使用者账户配置了活跃事件表，则返回 TRUE。否则返回 FALSE。

  • is_application_local_to_package()

    如果应用程序与应用程序包位于同一账户中，则返回 TRUE。否则返回 FALSE。

确定是否使用 SQL 启用了事件共享

以下示例演示在使用者账户中启用了事件共享时，如何仅调用存储过程。

请考虑以下 SQL 存储过程，它会创建函数，以计算两个数字之和：

CREATE OR ALTER VERSIONED SCHEMA app_schema;

CREATE OR REPLACE PROCEDURE app_schema.hidden_sum(num1 float, num2 float)
RETURNS FLOAT
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
  DECLARE
    SUM FLOAT;
  BEGIN
    SYSTEM$LOG('INFO', 'CALCULATE THE SUM OF TWO NUMBERS');
    SUM := :NUM1 + :NUM2;
    RETURN SUM;
  END;
$$;
Copy

添加到应用程序的设置脚本中时，这些 SQL 命令会在应用程序安装时在使用者账户中创建 hidden_sum 存储过程。但是，此存储过程对使用者不可见，因为系统不会在存储过程中向应用程序角色授予 USAGE 权限。

以下示例演示如何基于 IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER 和 IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT 系统函数，调用 hidden_sum 存储过程。

CREATE OR REPLACE PROCEDURE app_schema.sum(num1 float, num2 float)
RETURNS STRING
LANGUAGE SQL
EXECUTE AS OWNER
AS $$
    BEGIN
      IF (SYSTEM$IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT() or SYSTEM$IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER()) THEN
        CALL APP_SCHEMA.HIDDEN_SUM(:NUM1, :NUM2);
      ELSE
        -- notify consumers that they need to enable event sharing
        RETURN 'Sorry you can\'t access the API, please enable event sharing.'
      END IF;
    END;
$$;


CREATE APPLICATION ROLE IF NOT EXISTS ADMIN_ROLE;
GRANT USAGE ON SCHEMA APP_SCHEMA TO APPLICATION ROLE ADMIN_ROLE;
Copy

在此示例中，sum 存储过程会测试 IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER 和 IS_APPLICATION_INSTALLED_FROM_SAME_ACCOUNT 存储过程的值。如果它们的值之一是 true，sum 存储过程将调用 hidden_sum 存储过程。

使用 Python Permission SDK 请求从使用者进行事件共享

提供商可以使用 Python Permission SDK 创建一个 Streamlit 应用程序，以提示使用者在其账户中启用事件共享。

SDK 提供 request_event_sharing() 方法，它会在 Snowsight 中显示一个对话框，提示使用者在其账户中启用事件共享。如果使用者账户中不存在事件表，该对话框将允许使用者设置事件表（如果他们正在使用 ACCOUNTADMIN 角色）。

示例：使用 Python Permission SDK 及事件表

以下 Streamlit 示例显示了如何使用 Python Permission SDK 执行以下操作：

  • 确定是否启用了事件共享。

  • 如果启用了事件共享，则调用 critical_feature_that_requires_event_sharing() 函数。

  • 如果未启用事件共享，则调用 request_event_sharing() 函数，在 Snowsight 中显示一个对话框，提示使用者启用事件共享。

import streamlit as st
import snowflake.permissions as permissions

def critical_feature_that_requires_event_sharing():
  st.write("critical_feature_that_requires_event_sharing")

def main():
  if permissions.is_event_sharing_enabled() or permissions.is_application_local_to_package():
     critical_feature_that_requires_event_sharing()
  else:
     permissions.request_event_sharing()

if __name__ == "__main__":
  main()
Copy

在此示例中，只有在以下一项条件为真时，才会调用 critical_feature_that_requires_event_sharing() 方法：

  • 已启用事件共享，并且事件表存在。

  • Snowflake Native App 安装在与应用程序包相同的账户中。

如果两个条件都不是 true，Streamlit 应用程序将调用 request_event_sharing() 方法，提示使用者选择事件表。

有关更多信息，请参阅 确定是否在使用者账户中启用了事件共享。

语言: 中文