本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

导出查询分析日志

AWS Clean Rooms 在 Apache Spark 上运行 SQL 查询。当查询失败或运行缓慢时，该查询的 Spark 日志会包含查找原因所需的执行细节。它们显示了哪个阶段失败了、工作是如何跨任务分配的、使用了多少内存以及时间花在了哪里。

查询针对多个协作成员提供的数据运行。因此，原始 Spark 日志可以泄露有关其他成员数据的信息，例如表名、存储位置和数据值。出于这个原因， AWS Clean Rooms 不给你原始日志。取而代之的是，它会生成一个经过编辑的副本，其中对客户数据和成员元数据进行了编辑。 AWS Clean Rooms 将该副本导出到您拥有的 Amazon S3 存储桶中。然后，您可以使用自己选择的工具（例如 Spark 历史服务器）分析导出的日志。

先决条件

在导出查询日志之前，必须满足以下所有条件：

并非所有查询都支持日志导出。有关不支持的案例，请参阅注意事项和限制。

您无需为日志导出创建 IAM 角色。 AWS Clean Rooms 使用您自己的身份写入导出的日志，因此它仅在您自己的权限已经允许的情况下写入日志。作为最低权限的做法，仅授予对用于导出日志的存储桶和密钥前缀的写入权限。

导出查询日志

日志导出是异步的。当您开始导出时，立即 AWS Clean Rooms 返回导出 ID 和状态为IN_PROGRESS，然后在后台编辑和复制日志。

在开始导出之前， AWS Clean Rooms 将一个名validationSuccess为的零字节对象写入目标存储桶，以确认它可以在那里写入。如果此检查失败，则请求会立即因验证错误而失败，而不是稍后在后台失败。

Console

导出查询日志（控制台）

1. 登录 AWS 管理控制台 并打开AWS Clean Rooms 控制台。

2. 在左侧导航窗格中，选择协作。

3. 选择包含查询的协作。

4. 选择分析选项卡。

5. 请执行以下任一操作：

   • 在查询表中，选择查询，选择操作，然后选择导出查询分析日志。

   • 选择查询以打开其详细信息页面，然后选择导出分析日志。

6. 在对话框中，选择目标 Amazon S3 存储桶和密钥前缀（可选）。

7. 选择导出。

如果 “导出查询分析日志” 选项不可用，控制台会解释原因。下表列出了这些消息以及如何解决这些消息。

Message	解决方案
在导出日志之前，查询必须达到终端状态。	等待查询完成运行。
您无法导出查询分析日志。	要求协作成员提交变更请求，为您的会员资格添加权限。
使用差异隐私的查询不支持日志导出。	无。日志导出不适用于这些查询。
只有查询运行者或查询付款人才能导出分析日志。	要求运行查询或付费的成员导出日志。

查询详细信息页面包含一个导出历史记录表，其中列出了每次导出及其状态。选择导出失败以查看错误，或选择查看目标以在 Amazon S3 中打开导出的日志。

API

导出查询日志 (API)

致电StartAnalysisLogExport，指定成员资格、受保护的查询和目的地。

aws cleanrooms start-analysis-log-export \
    --membership-identifier membership-id \
    --analysis-id protected-query-id \
    --analysis-type PROTECTED_QUERY \
    --result-configuration '{
        "outputConfiguration": {
            "s3": {
                "bucket": "amzn-s3-demo-bucket",
                "keyPrefix": "query-logs/"
            }
        }
    }'

响应返回一个包含 a analysisLogExportId 和 a status 的analysisLogExport对象IN_PROGRESS。

要检查导出情况，请GetAnalysisLogExport使用成员身份标识符和出口标识符进行呼叫，然后轮询直到状态为SUCCESS或FAILED。当导出失败时，响应会包含一个包含代码和消息的error字段。

aws cleanrooms get-analysis-log-export \
    --membership-identifier membership-id \
    --analysis-log-export-identifier analysis-log-export-id

要列出会员的出口信息，请致电ListAnalysisLogExports。您可以使用按查询筛选结果analysisIdentifier，也可以使用按导出状态筛选结果status。status过滤器接受IN_PROGRESSSUCCESSFAILED、或，一次取一个值。这些是导出本身的状态，而不是您导出日志的查询的状态。结果将进行分页。

aws cleanrooms list-analysis-log-exports \
    --membership-identifier membership-id \
    --analysis-identifier protected-query-id \
    --status SUCCESS

对于给定的查询和目标，一次只能激活一个导出。如果您在同一查询和相同 Amazon S3 目的地的另一次导出仍在进行中时开始导出，则请求会因验证错误而失败。要一次导出两次同一个查询，请在第二次导出时使用不同的密钥前缀。

您可以独立于其他成员导出。如果你和另一个成员都有能力并且都运行或支付了同一个查询的费用，那么你们每个人都可以将日志导出到自己的目的地。

导出日志的写入位置

AWS Clean Rooms 使用以下结构在您指定的存储桶和密钥前缀下写入导出的日志：

s3://your-bucket/key-prefix/collaboration=collaboration-id/analysis=protected-query-id/analysis-log-export-id/

由于路径包含导出 ID，因此多次导出同一个查询不会覆盖先前导出的日志。

导出内容包含经过编辑的查询的 Spark 事件日志。该日志是一组结构化的 JSON 记录，涵盖任务、阶段、任务、时间和查询计划。Spark 本身会写入这种事件日志格式。您可以使用任何读取 Spark 事件日志的工具（包括您自己的工具）处理导出。 AWS Clean Rooms 不为导出的日志提供查看器。在导出目录中，记录遵循 Spark 用于滚动事件日志的布局。名为的目录eventlog_v2_protected-query-id包含一个或多个events_appstatus_文件以及一个记录应用程序完成情况的文件。目录和文件名使用受保护的查询 ID，而不是内部 AWS Clean Rooms 标识符。

Spark 历史服务器就是这样一种工具。要在 Spark 历史服务器中查看导出内容，请将一个实例指向查询的eventlog_v2_目录。例如，6ba7b810-9dad-11d1-80b4-00c04fd430c8将查询导出到amzn-s3-demo-bucket带有密钥前缀的存储桶query-logs/会生成以下结果。

s3://amzn-s3-demo-bucket/query-logs/
  collaboration=f47ac10b-58cc-4372-a567-0e02b2c3d479/
    analysis=6ba7b810-9dad-11d1-80b4-00c04fd430c8/
      a1b2c3d4-e5f6-7890-abcd-ef1234567890/
        eventlog_v2_6ba7b810-9dad-11d1-80b4-00c04fd430c8/
          events_1_6ba7b810-9dad-11d1-80b4-00c04fd430c8
          appstatus_6ba7b810-9dad-11d1-80b4-00c04fd430c8

在此示例中，将 Spark 历史服务器日志目录设置为以下内容。指向该eventlog_v2_目录只能呈现您导出的查询。直接从 Amazon S3 读取日志需要 S3A 连接器，因此请使用该s3a://架构。Spark 历史服务器运行的凭据需要对存储桶的读取权限。

spark.history.fs.logDirectory s3a://amzn-s3-demo-bucket/query-logs/collaboration=f47ac10b-58cc-4372-a567-0e02b2c3d479/analysis=6ba7b810-9dad-11d1-80b4-00c04fd430c8/a1b2c3d4-e5f6-7890-abcd-ef1234567890/eventlog_v2_6ba7b810-9dad-11d1-80b4-00c04fd430c8/

使用 Spark 历史服务器版本 3.5.0 或更高版本。您负责设置和运行自己的实例。有关运行 Spark 历史服务器实例的信息，请参阅 Apache Spark 网站上的 “事后查看”。

日志导出疑难解答

注意事项和限制

有关适用于日志导出的配额，包括可以同时运行的导出次数，请参阅的配额 AWS Clean Rooms。