本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 导出查询分析日志
AWS Clean Rooms 在 Apache Spark 上运行 SQL 查询。当查询失败或运行缓慢时，该查询的 Spark 日志会包含查找原因所需的执行细节。它们显示了哪个阶段失败了、工作是如何跨任务分配的、使用了多少内存以及时间花在了哪里。
查询针对多个协作成员提供的数据运行。因此，原始 Spark 日志可以泄露有关其他成员数据的信息，例如表名、存储位置和数据值。出于这个原因， AWS Clean Rooms 不给你原始日志。取而代之的是，它会生成一个*经过编辑的*副本，其中对客户数据和成员元数据进行了编辑。 AWS Clean Rooms 将该副本导出到您拥有的 Amazon S3 存储桶中。然后，您可以使用自己选择的工具（例如 Spark 历史服务器）分析导出的日志。
**重要**
导出的日志已被编辑。移除数据值，并将计数和大小报告为近似值，因此它们不会透露协作中数据的详细信息。因此，导出的日志与 Spark 作业在外部生成的日志不匹配 AWS Clean Rooms。在解释它们之前，请先阅读[了解经过编辑的日志](export-analysis-logs-contents.md)。
## 先决条件
在导出查询日志之前，必须满足以下所有条件：
+ 您的会员资格具有会员资格。`CAN_EXPORT_QUERY_ANALYSIS_LOG`每个协作成员都必须批准变更请求才能授予此权限。有关更多信息，请参阅 [更新成员技能](change-requests.md#update-member-abilities-change-request)。
+ 您是查询运行者或查询的付款人。仅有这种能力是不够的：您只能导出自己运行的或付费的查询的日志。
+ 查询已达到终端状态。您可以导出状态为`SUCCESS`、`FAILED``CANCELLED`、或的查询日志`TIMED_OUT`。当查询仍在运行时，您无法导出日志。
并非所有查询都支持日志导出。有关不支持的案例，请参阅[注意事项和限制](#export-analysis-logs-limitations)。
您无需为日志导出创建 IAM 角色。 AWS Clean Rooms 使用您自己的身份写入导出的日志，因此它仅在您自己的权限已经允许的情况下写入日志。作为最低权限的做法，仅授予对用于导出日志的存储桶和密钥前缀的写入权限。
**注意**
如果目标存储桶 SSE-KMS 与客户管理的密钥一起使用，则您必须拥有使用该密钥的权限。否则，导出请求会立即失败。
## 导出查询日志
日志导出是异步的。当您开始导出时，立即 AWS Clean Rooms 返回导出 ID 和状态为`IN_PROGRESS`，然后在后台编辑和复制日志。
在开始导出之前， AWS Clean Rooms 将一个名`validationSuccess`为的零字节对象写入目标存储桶，以确认它可以在那里写入。如果此检查失败，则请求会立即因验证错误而失败，而不是稍后在后台失败。
------
#### [ Console ]
**导出查询日志（控制台）**
1. 登录 AWS 管理控制台 并打开[AWS Clean Rooms 控制台](https://console.aws.amazon.com/cleanrooms/home)。
1. 在左侧导航窗格中，选择**协作**。
1. 选择包含查询的协作。
1. 选择**分析**选项卡。
1. 请执行以下任一操作：
+ 在查询表中，选择查询，选择**操作**，然后选择**导出查询分析日志**。
+ 选择查询以打开其详细信息页面，然后选择**导出分析日志**。
1. 在对话框中，选择目标 Amazon S3 存储桶和密钥前缀（可选）。
1. 选择**导出**。
如果 “**导出查询分析日志**” 选项不可用，控制台会解释原因。下表列出了这些消息以及如何解决这些消息。
| 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_PROGRESS``SUCCESS``FAILED`、或，一次取一个值。这些是导出本身的状态，而不是您导出日志的查询的状态。结果将进行分页。
```
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 网站上的 “事[后](https://spark.apache.org/docs/latest/monitoring.html#viewing-after-the-fact)查看”。
## 日志导出疑难解答
请求失败，因为你没有权限导出日志
您的会员资格没有此`CAN_EXPORT_QUERY_ANALYSIS_LOG`权限。协作成员必须提交变更请求才能添加该能力，并且所有成员都必须批准。有关更多信息，请参阅 [更新成员技能](change-requests.md#update-member-abilities-change-request)。
请求失败，因为无法写入存储桶
验证存储桶是否存在，它与协作处于同一 AWS 区域 位置，以及您是否有权写入该存储桶。如果存储桶策略拒绝`s3:PutObject`或限制对特定 VPC 终端节点的写入，则 AWS Clean Rooms 无法写入该存储桶。
如果存储桶 SSE-KMS 与客户管理的密钥一起使用，则此错误也可能意味着您无权使用该密钥。确认密钥策略允许您通过 Amazon S3 调用`kms:GenerateDataKey`和`kms:Decrypt`通过 Amazon S3。
导出失败，因为查询从未运行过
该查询未在 Spark 上运行就达到了终端状态，因此没有生成任何日志。当查询未通过验证或在开始之前被取消时，就会发生这种情况。导出失败，错误代码为，`LOGS_NOT_AVAILABLE`并显示一条消息，报告没有可用于查询的查询执行日志。没有什么可出口的。
请求失败，因为查询是在日志导出可用之前运行的
编辑后的日志是在查询运行时生成的。在日志导出之前运行的查询在 prodect AWS Clean Rooms ed none 中可用，因此没有可导出的内容。要获取相同分析的日志，请再次运行查询并导出新运行的日志。
由于超出配额，请求失败
您已达到可以同时进行的最大导出次数。等待正在进行的导出完成，然后重试。
导出开始但随后失败
初始权限检查仅确认在您开始导出时 AWS Clean Rooms 可以写入存储桶的内容。如果您的权限发生变化，或者如果在导出运行期间撤消了用于导出的证书，则导出在开始后会失败。`GetAnalysisLogExport`致电查看错误，解决原因并开始新的导出。
导出失败并报告内部错误
内部错误可能意味着没有为查询生成任何日志。您可以重试导出。
导出的日志似乎不完整
如果查询因进程内存不足而结束，则可能会丢失某些日志输出，因为无法恢复在突然停止的主机上保存的日志。已经写入的日志仍会导出。
存储桶中有一个零字节的`validationSuccess`对象
AWS Clean Rooms 使用您指定的密钥前缀写入此对象，以验证它是否可以在开始导出之前写入您的目的地。它与导出的日志是分开的，后者写在导出自己的目录下，您可以将其删除。用斜杠结尾你的密钥前缀，这样这个对象就会在前缀内而不是在前缀旁边创建。
## 注意事项和限制
+ 您可以导出 2026 年 8 月 11 日之后运行的 SQL 查询的日志。日志导出不支持 PySpark 作业。
+ 对于验证失败或在达到`STARTED`状态之前被取消的查询，不支持日志导出。
+ 使用差异隐私的查询不支持日志导出。有关更多信息，请参阅 [AWS Clean Rooms 差异隐私](differential-privacy.md)。
+ 日志导出的目标存储桶必须与协作存储桶相同 AWS 区域 。 Cross-Region 不支持导出。
+ 保护日志导出的目标存储桶是您的责任。如果您需要记录谁读取了导出的日志，则阻止对存储桶的公开访问，并启用服务器访问日志记录。
+ AWS Clean Rooms 不接受用于导出日志的 AWS KMS 密钥。导出的日志使用目标 Amazon S3 存储桶的默认加密配置进行加密。要使用客户管理的密钥对其进行加密，请在导出之前将存储桶的默认加密配置为使用该密钥。
+ 日志导出仅支持达到终端状态的查询：`SUCCESS``FAILED`、`CANCELLED`、或`TIMED_OUT`。
+ 导出开始后您无法取消导出。
有关适用于日志导出的配额，包括可以同时运行的导出次数，请参阅[的配额 AWS Clean Rooms](quotas.md)。