View a markdown version of this page

クエリ分析ログのエクスポート - AWS Clean Rooms
前提条件ログのエクスポートログの場所トラブルシューティング考慮事項と制限事項

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

クエリ分析ログのエクスポート

AWS Clean Rooms は Apache Spark で SQL クエリを実行します。クエリが失敗するか、実行が遅い場合、そのクエリの Spark ログには、原因を見つけるために必要な実行の詳細が含まれます。失敗したステージ、タスク間での作業の分散方法、使用されたメモリの量、費やされた時間が表示されます。

クエリは、複数のコラボレーションメンバーから提供されたデータ全体で実行されます。したがって、Raw Spark ログは、テーブル名、ストレージの場所、データ値など、別のメンバーのデータに関する情報を明らかにすることができます。そのため、 AWS Clean Rooms は raw ログを提供しません。代わりに、顧客データとメンバーメタデータが秘匿化される秘匿化コピーが生成されます。 は、所有する Amazon S3 バケットにコピーを AWS Clean Rooms エクスポートします。次に、Spark History Server などの任意のツールを使用して、エクスポートされたログを分析します。

重要

エクスポートされたログは編集されます。データ値は削除され、数とサイズは近似値として報告されるため、コラボレーション内のデータに関する詳細は表示されません。その結果、エクスポートされたログは、Spark ジョブが の外部で生成するログと一致しません AWS Clean Rooms。解釈する前に、「」を参照してください秘匿化ログについて。

前提条件

クエリのログをエクスポートする前に、次のすべてが true である必要があります。

  • メンバーシップにはCAN_EXPORT_QUERY_ANALYSIS_LOGメンバー権限があります。この機能を付与するには、すべてのコラボレーションメンバーが変更リクエストを承認する必要があります。詳細については、「メンバー機能の更新」を参照してください。

  • ユーザーは、クエリの実行者またはクエリの支払い者です。機能だけでは不十分です。ログをエクスポートできるのは、実行したクエリまたは有料のクエリのみです。

  • クエリが終了状態になりました。ステータスが 、SUCCESS、FAILED、CANCELLEDまたは のクエリのログをエクスポートできますTIMED_OUT。クエリの実行中にログをエクスポートすることはできません。

ログのエクスポートは、すべてのクエリで利用できるわけではありません。サポートされていないケースについては、「」を参照してください考慮事項と制限事項。

ログエクスポート用の IAM ロールを作成する必要はありません。 は、エクスポートされたログを独自の ID を使用して AWS Clean Rooms 書き込みます。そのため、ログは、独自のアクセス許可が既に許可されている場合にのみ書き込みます。最小特権のプラクティスとして、エクスポートされたログに使用するバケットとキープレフィックスにのみ書き込みアクセスを許可します。

注記

レプリケート先バケットがカスタマーマネージドキーで SSE-KMS を使用する場合は、そのキーを使用するためのアクセス許可が必要です。そうしないと、エクスポートリクエストはすぐに失敗します。

クエリのログのエクスポート

ログのエクスポートは非同期です。エクスポートを開始すると、 はエクスポート ID と のステータスですぐに AWS Clean Rooms 戻りIN_PROGRESS、 はログを編集してバックグラウンドでコピーします。

エクスポートを開始する前に、 は という名前のゼロバイトオブジェクトを送信先バケットvalidationSuccessに AWS Clean Rooms 書き込み、そこに書き込めることを確認します。このチェックが失敗した場合、リクエストは後でバックグラウンドで失敗するのではなく、検証エラーですぐに失敗します。

Console
クエリのログをエクスポートするには (コンソール)

  1. にサインイン AWS マネジメントコンソール し、 AWS Clean Rooms コンソールを開きます。

  2. 左のナビゲーションペインで、[コラボレーション] を選択します。

  3. クエリを含むコラボレーションを選択します。

  4. [分析] タブを選択します。

  5. 次のいずれかを実行します。

    • クエリのテーブルで、クエリを選択し、アクションを選択し、クエリ分析ログのエクスポートを選択します。

    • クエリを選択して詳細ページを開き、分析ログのエクスポートを選択します。

  6. ダイアログボックスで、送信先の Amazon S3 バケットを選択し、オプションでキープレフィックスを選択します。

  7. [エクスポート] を選択します。

クエリ分析ログのエクスポートオプションが使用できない場合は、コンソールでその理由を説明します。次の表に、メッセージとその解決方法を示します。

メッセージ 解決策
クエリは、ログをエクスポートする前に終了状態に到達する必要があります。 クエリの実行が完了するまで待ちます。
クエリ分析ログをエクスポートすることはできません。 メンバーシップに機能を追加する変更リクエストを送信するようにコラボレーションメンバーに依頼します。
差分プライバシーを使用するクエリでは、ログのエクスポートはサポートされていません。 なし。ログのエクスポートは、これらのクエリでは使用できません。
分析ログをエクスポートできるのは、クエリの実行者またはクエリの支払い者のみです。 クエリを実行または支払ったメンバーに、ログをエクスポートするよう依頼します。

クエリの詳細ページには、各エクスポートとそのステータスを一覧表示するエクスポート履歴テーブルが表示されます。失敗したエクスポートを選択してエラーを表示するか、送信先を表示を選択して 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、一度に 1 つの値を取ります。これらは、ログをエクスポートしたクエリのステータスではなく、エクスポート自体のステータスです。結果はページ分割されます。

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

特定のクエリと送信先に対して一度にアクティブにできるエクスポートは 1 つだけです。同じクエリと同じ Amazon S3 送信先の別のエクスポートがまだ進行中にエクスポートを開始すると、リクエストは検証エラーで失敗します。同じクエリを一度に 2 回エクスポートするには、2 回目のエクスポートに別のキープレフィックスを使用します。

他のメンバーとは別にエクスポートします。自分と別のメンバーの両方が同じクエリを実行または支払われた場合、それぞれが自分の送信先にログをエクスポートできます。

エクスポートされたログが書き込まれる場所

AWS Clean Rooms は、次の構造を使用して、指定したバケットとキープレフィックスの下にエクスポートされたログを書き込みます。

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

パスにはエクスポート ID が含まれているため、同じクエリを複数回エクスポートしても、以前のエクスポートのログは上書きされません。

エクスポートには、クエリの編集済み Spark イベントログが含まれます。このログは、ジョブ、ステージ、タスク、タイミング、クエリプランをカバーする構造化された JSON レコードのセットです。Spark 自体はこのイベントログ形式を書き込みます。独自の tooling など、Spark イベントログを読み取る任意のツールを使用してエクスポートを処理できます。エクスポートされたログのビューワーは提供 AWS Clean Rooms されません。エクスポートディレクトリ内では、レコードは Spark がローリングイベントログに使用するレイアウトに従います。という名前のディレクトリeventlog_v2_protected-query-idには、1 つ以上のevents_ファイルと、アプリケーションが完了したことを記録する appstatus_ ファイルが保持されます。ディレクトリ名とファイル名は、内部 AWS Clean Rooms 識別子ではなく、保護されたクエリ ID を使用します。

Spark History Server はそのようなツールの 1 つです。Spark History Server でエクスポートを表示するには、クエリの 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 History Server ログディレクトリを次のように設定します。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 History Server インスタンスの実行については、Apache Spark ウェブサイトの「事後表示」を参照してください。

ログのエクスポートのトラブルシューティング

ログをエクスポートするアクセス許可がないため、リクエストは失敗します

メンバーシップにはCAN_EXPORT_QUERY_ANALYSIS_LOG機能がありません。コラボレーションメンバーは変更リクエストを送信して機能を追加し、すべてのメンバーが承認する必要があります。詳細については、「メンバー機能の更新」を参照してください。

バケットを に書き込むことができないため、リクエストは失敗します

バケットが存在し、コラボレーション AWS リージョン と同じ にあり、バケットに書き込むアクセス許可があることを確認します。バケットポリシーが を拒否した場合s3:PutObject、または特定の VPC エンドポイントへの書き込みを制限した場合、 AWS Clean Rooms はバケットに書き込むことができません。

バケットがカスタマーマネージドキーで SSE-KMS を使用している場合、このエラーは、そのキーを使用するアクセス許可がないことを意味します。キーポリシーで Amazon S3 kms:Decrypt経由で kms:GenerateDataKeyおよび を呼び出すことができることを確認します。 Amazon S3

クエリが実行されなかったため、エクスポートが失敗する

クエリは Spark で を実行せずに終了状態になったため、ログは生成されませんでした。これは、クエリが検証に失敗するか、開始する前にキャンセルされた場合に発生します。エクスポートは失敗し、 のエラーコードLOGS_NOT_AVAILABLEと、クエリ実行ログがクエリに使用できないことを示すメッセージが表示されます。エクスポートするものはありません。

ログエクスポートが利用可能になる前にクエリが実行されたため、リクエストは失敗します

秘匿化ログは、クエリの実行中に生成されます。ログのエクスポートが で使用可能になる前に実行されたクエリでは、 AWS Clean Rooms 何も生成されないため、エクスポートするものはありません。同じ分析のログを取得するには、クエリを再度実行し、新しい実行のログをエクスポートします。

クォータを超えたためリクエストが失敗する

同時に進行中のエクスポートの最大数に達しました。進行中のエクスポートが終了するのを待ってから、再試行します。

エクスポートは開始されますが、失敗します

最初のアクセス許可チェックでは、エクスポートを開始した時点で AWS Clean Rooms がバケットに書き込めることを確認します。アクセス許可が変更された場合、またはエクスポートの実行中にエクスポートに使用した認証情報が取り消された場合、エクスポートの開始後にエクスポートは失敗します。GetAnalysisLogExport を呼び出してエラーを確認し、原因を解決して、新しいエクスポートを開始します。

エクスポートが失敗し、内部エラーが報告される

内部エラーは、クエリのログが生成されなかったことを意味します。エクスポートを再試行できます。

エクスポートされたログが不完全であるように見える

プロセスがメモリ不足のためにクエリが終了した場合、突然停止したホストに保持されているログは復旧されないため、一部のログ出力が欠落している可能性があります。既に書き込まれたログは引き続きエクスポートされます。

バケットに 0 バイトのvalidationSuccessオブジェクトがある

AWS Clean Rooms は、指定したキープレフィックスにこのオブジェクトを書き込み、エクスポートを開始する前に送信先に書き込めることを確認します。これはエクスポートされたログとは別のもので、エクスポート独自のディレクトリに書き込まれているため、削除できます。キープレフィックスをスラッシュで終了して、このオブジェクトが横ではなくプレフィックス内に作成されるようにします。

考慮事項と制限事項

  • 2026 年 8 月 11 日以降に実行された SQL クエリのログをエクスポートできます。ログのエクスポートは PySpark ジョブをサポートしていません。

  • ログのエクスポートは、検証に失敗したクエリ、または STARTEDステータスに達する前にキャンセルされたクエリではサポートされていません。

  • 差分プライバシーを使用するクエリでは、ログのエクスポートはサポートされていません。詳細については、「AWS Clean Rooms 差分プライバシー」を参照してください。

  • ログエクスポートの送信先バケットは、コラボレーション AWS リージョン と同じ にある必要があります。クロスリージョンエクスポートはサポートされていません。

  • ログエクスポートの送信先バケットを保護するのはユーザーの責任です。バケットへのパブリックアクセスをブロックし、エクスポートされたログを読み取るユーザーのレコードが必要な場合はサーバーアクセスログ記録を有効にします。

  • AWS Clean Rooms はログのエクスポートに AWS KMS キーを受け入れません。エクスポートされたログは、送信先の Amazon S3 バケットのデフォルトの暗号化設定を使用して暗号化されます。カスタマーマネージドキーで暗号化するには、エクスポートする前にそのキーを使用するようにバケットのデフォルトの暗号化を設定します。

  • ログエクスポートは、終了状態に達したクエリ、SUCCESS、FAILED、CANCELLEDまたは のみをサポートしますTIMED_OUT。

  • エクスポートの開始後はキャンセルできません。

同時に実行できるエクスポートの数など、ログエクスポートに適用されるクォータについては、「」を参照してくださいのクォータ AWS Clean Rooms。