匯出查詢分析日誌

AWS Clean Rooms 在 Apache Spark 上執行 SQL 查詢。當查詢失敗或執行速度緩慢時，該查詢的 Spark 日誌會包含尋找原因所需的執行詳細資訊。它們會顯示哪個階段失敗、工作在任務間的分配方式、使用的記憶體量，以及花費的時間。

查詢會跨多個協同合作成員貢獻的資料執行。因此，原始 Spark 日誌可以顯示其他成員資料的相關資訊，例如資料表名稱、儲存位置和資料值。因此， AWS Clean Rooms 不會為您提供原始日誌。相反地，它會產生修訂的副本，其中客戶資料和成員中繼資料會修訂。 AWS Clean Rooms 匯出會複製到您擁有的 Amazon S3 儲存貯體。然後，您可以使用您選擇的工具分析匯出的日誌，例如 Spark 歷史記錄伺服器。

重要

匯出的日誌會遭到修訂。資料值會移除，計數和大小會報告為近似值，因此不會顯示協同合作中資料的詳細資訊。因此，匯出的日誌與 Spark 任務在外部產生的日誌不相符 AWS Clean Rooms。解譯之前，請閱讀了解已修訂的日誌。

先決條件

您必須先符合下列所有條件，才能匯出查詢的日誌：

您的成員資格具有CAN_EXPORT_QUERY_ANALYSIS_LOG成員能力。每個協同合作成員都必須核准變更請求，才能授予此能力。如需詳細資訊，請參閱更新成員功能。
您是查詢執行器或查詢的付款人。擁有功能本身並不足夠：您只能針對您執行或付費的查詢匯出日誌。
查詢已達到結束狀態。您可以匯出狀態為 SUCCESS、CANCELLED、 FAILED或的查詢日誌TIMED_OUT。當查詢仍在執行時，您無法匯出日誌。

日誌匯出不適用於每個查詢。如需不支援的案例，請參閱考量和限制。

您不需要為日誌匯出建立 IAM 角色。會使用您自己的身分 AWS Clean Rooms 寫入匯出的日誌，因此它只會在您自己的許可已允許的情況下寫入日誌。作為最低權限實務，僅授予您用於匯出日誌的儲存貯體和金鑰字首的寫入存取權。

注意

如果目的地儲存貯體搭配客戶受管金鑰使用 SSE-KMS，您必須具有使用該金鑰的許可。如果沒有，匯出請求會立即失敗。

匯出查詢的日誌

日誌匯出是非同步的。當您啟動匯出時，會立即 AWS Clean Rooms 傳回匯出 ID 和狀態為 IN_PROGRESS，然後在背景修訂和複製日誌。

開始匯出之前，會將名為的零位元組物件 AWS Clean Rooms 寫入目的地validationSuccess儲存貯體，以確認可以寫入該儲存貯體。如果此檢查失敗，請求會立即失敗並出現驗證錯誤，而不是稍後在背景失敗。

Console

匯出查詢的日誌（主控台）

登入 AWS 管理主控台並開啟 AWS Clean Rooms 主控台。
在左側導覽窗格中，選擇協同合作。
選擇包含查詢的協同合作。
選擇分析索引標籤。
執行下列任何一項：
- 在查詢表格中，選取查詢，選擇動作，然後選擇匯出查詢分析日誌。
- 選擇查詢以開啟其詳細資訊頁面，然後選擇匯出分析日誌。
在對話方塊中，選擇目的地 Amazon S3 儲存貯體，以及選擇性的金鑰字首。
選擇 Export (匯出)。

如果匯出查詢分析日誌選項無法使用，主控台會說明原因。下表列出訊息及其解決方式。

訊息	Resolution
查詢必須達到結束狀態，才能匯出日誌。	等待查詢完成執行。
您無法匯出查詢分析日誌。	要求協作成員提交變更請求，將功能新增至您的成員資格。
使用差異隱私權的查詢不支援日誌匯出。	無。這些查詢無法使用日誌匯出。
只有查詢執行器或查詢付款人可以匯出分析日誌。	要求執行查詢或支付查詢費用的成員匯出日誌。

查詢詳細資訊頁面包含匯出歷史記錄表，其中列出每個匯出及其狀態。選擇失敗的匯出以查看錯誤，或選擇檢視目的地以在 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/"
            }
        }
    }'

回應會傳回包含 analysisLogExportId和 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_目錄。例如，amzn-s3-demo-bucket使用金鑰字首將查詢匯出6ba7b810-9dad-11d1-80b4-00c04fd430c8至儲存貯體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 History Server 使用執行的登入資料需要對儲存貯體的讀取存取權。


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 History Server 3.5.0 版或更新版本。您負責設定和執行自己的執行個體。如需有關執行 Spark 歷史記錄伺服器執行個體的資訊，請參閱 Apache Spark 網站上的事後檢視。

對日誌匯出進行故障診斷

請求失敗，因為您沒有匯出日誌的許可

您的成員資格沒有 CAN_EXPORT_QUERY_ANALYSIS_LOG功能。協同合作成員必須提交變更請求才能新增功能，且所有成員都必須核准。如需詳細資訊，請參閱更新成員功能。

請求失敗，因為無法將儲存貯體寫入

確認儲存貯體存在、與協同合作 AWS 區域位於相同位置，而且您具有寫入儲存貯體的許可。如果儲存貯體政策拒絕 s3:PutObject，或限制寫入特定 VPC 端點，則 AWS Clean Rooms 無法寫入儲存貯體。

如果儲存貯體搭配客戶受管金鑰使用 SSE-KMS，此錯誤可能也表示您沒有使用該金鑰的許可。確認金鑰政策允許您kms:Decrypt透過 Amazon S3 呼叫 kms:GenerateDataKey和。

匯出失敗，因為查詢從未執行

查詢在 Spark 上未執行的情況下達到結束狀態，因此不會產生日誌。當查詢驗證失敗或在啟動之前取消時，就會發生這種情況。匯出失敗，錯誤碼為，LOGS_NOT_AVAILABLE且訊息報告沒有查詢執行日誌可供查詢使用。沒有可匯出的項目。

請求失敗，因為查詢在日誌匯出可用之前執行

已修訂的日誌會在查詢執行時產生。在日誌匯出變為可用之前執行的查詢不會 AWS Clean Rooms 產生任何結果，因此無需匯出任何內容。若要取得相同分析的日誌，請再次執行查詢，並匯出新執行的日誌。

請求失敗，因為超過配額

您已達到可同時進行的最大匯出數量。等待進行中匯出完成，然後重試。

匯出開始但接著失敗

初始許可檢查只會確認 AWS Clean Rooms 可在您開始匯出時寫入您的儲存貯體。如果您的許可變更，或在匯出執行時撤銷用於匯出的登入資料，則匯出會在啟動後失敗。呼叫 GetAnalysisLogExport 查看錯誤、解決原因，並開始新的匯出。

匯出失敗並報告內部錯誤

內部錯誤可能表示查詢未產生日誌。您可以重試匯出。

匯出的日誌顯示不完整

如果查詢因為程序耗盡記憶體而結束，則可能會遺失某些日誌輸出，因為在主機上存放且突然停止的日誌無法復原。已寫入的日誌仍會匯出。

儲存貯體中有零位元組validationSuccess物件

AWS Clean Rooms 會在您指定的金鑰字首寫入此物件，以確認它可以在開始匯出之前寫入目的地。它與匯出的日誌是分開的，這些日誌是在匯出本身的目錄下寫入的，而且您可以將其刪除。以斜線結束您的金鑰字首，讓此物件在字首內而非旁邊建立。

考量和限制

您可以匯出 2026 年 8 月 11 日之後執行的 SQL 查詢日誌。日誌匯出不支援 PySpark 任務。
對於驗證失敗或在達到 STARTED 狀態之前取消的查詢，不支援日誌匯出。
使用差異隱私權的查詢不支援日誌匯出。如需詳細資訊，請參閱AWS Clean Rooms 差異隱私權。
日誌匯出的目的地儲存貯體必須與協同合作 AWS 區域位於相同的中。不支援跨區域匯出。
保護目的地儲存貯體以進行日誌匯出是您的責任。封鎖對儲存貯體的公開存取，如果您需要誰讀取匯出日誌的記錄，請啟用伺服器存取記錄。
AWS Clean Rooms 不接受用於日誌匯出的 AWS KMS 金鑰。匯出的日誌會使用目的地 Amazon S3 儲存貯體的預設加密組態進行加密。若要使用客戶受管金鑰進行加密，請在匯出之前設定儲存貯體的預設加密使用該金鑰。
日誌匯出僅支援達到終端狀態的查詢：SUCCESS、CANCELLED、 FAILED或 TIMED_OUT。
您無法在匯出啟動後取消匯出。

如需適用於日誌匯出的配額，包括可同時執行的匯出數量，請參閱的配額 AWS Clean Rooms。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

檢視查詢詳細資訊

了解已修訂的日誌