Exportieren von Abfrageanalyseprotokollen

AWS Clean Rooms führt SQL-Abfragen auf Apache Spark aus. Wenn eine Abfrage fehlschlägt oder langsam ausgeführt wird, enthalten die Spark-Protokolle für diese Abfrage die Ausführungsdetails, die Sie benötigen, um die Ursache zu finden. Sie zeigen, welche Phase fehlgeschlagen ist, wie die Arbeit auf die Aufgaben verteilt wurde, wie viel Speicher verwendet wurde und wo Zeit aufgewendet wurde.

Eine Abfrage bezieht sich auf Daten, die von mehreren Kollaborationsmitgliedern beigesteuert wurden. Raw Spark-Logs können daher Informationen über die Daten eines anderen Mitglieds enthalten, wie Tabellennamen, Speicherorte und Datenwerte. Aus diesem Grund werden Ihnen die Rohprotokolle AWS Clean Rooms nicht angezeigt. Stattdessen wird eine redigierte Kopie erstellt, in der Kundendaten und Mitgliedermetadaten redigiert werden. AWS Clean Rooms exportiert diese Kopie in einen Amazon S3-Bucket, den Sie besitzen. Anschließend analysieren Sie die exportierten Protokolle mit den Tools Ihrer Wahl, z. B. dem Spark History Server.

Wichtig

Exportierte Protokolle werden redigiert. Datenwerte werden entfernt, und Anzahl und Größe werden als Näherungswerte angegeben, sodass keine Details zu den Daten in der Zusammenarbeit preisgegeben werden. Daher stimmen die exportierten Logs nicht mit den Logs überein, die ein Spark-Job außerhalb davon AWS Clean Rooms erzeugt. Bevor Sie sie interpretieren, lesen SieGrundlegendes zu redigierten Protokollen.

Voraussetzungen

Bevor Sie Protokolle für eine Abfrage exportieren können, müssen alle folgenden Bedingungen erfüllt sein:

• Ihre Mitgliedschaft beinhaltet die CAN_EXPORT_QUERY_ANALYSIS_LOG Mitgliedschaftsfähigkeit. Jedes Kollaborationsmitglied muss eine Änderungsanfrage genehmigen, um diese Fähigkeit zu gewähren. Weitere Informationen finden Sie unter Aktualisieren Sie die Fähigkeiten der Mitglieder.

• Sie sind der Abfragerunner oder der Zahler der Abfrage. Diese Fähigkeit allein reicht nicht aus: Sie können Logs nur für Abfragen exportieren, die Sie selbst ausgeführt haben oder für die Sie bezahlt haben.

• Die Abfrage hat einen Endzustand erreicht. Sie können Protokolle für eine Abfrage mit dem StatusSUCCESS, FAILEDCANCELLED, oder exportierenTIMED_OUT. Sie können keine Protokolle exportieren, solange eine Abfrage noch läuft.

Der Protokollexport ist nicht für jede Abfrage verfügbar. Die Fälle, die nicht unterstützt werden, finden Sie unterÜberlegungen und Einschränkungen.

Sie müssen keine IAM-Rolle für den Protokollexport erstellen. AWS Clean Rooms schreibt die exportierten Protokolle unter Verwendung Ihrer eigenen Identität, sodass die Protokolle nur dann geschrieben werden, wenn Ihre eigenen Berechtigungen dies bereits zulassen. Gewähren Sie Schreibzugriff nur für den Bucket und das Schlüsselpräfix, die Sie für exportierte Logs verwenden, um möglichst wenig Rechte zu haben.

Anmerkung

Wenn der Ziel-Bucket einen vom Kunden verwalteten Schlüssel verwendet SSE-KMS , müssen Sie die Berechtigung haben, diesen Schlüssel zu verwenden. Wenn Sie dies nicht tun, schlägt die Exportanforderung sofort fehl.

Exportieren von Protokollen für eine Abfrage

Der Protokollexport erfolgt asynchron. Wenn Sie einen Export starten, AWS Clean Rooms kehrt er sofort mit einer Export-ID und dem Status von IN_PROGRESS zurück. Anschließend werden die Protokolle im Hintergrund redigiert und kopiert.

Bevor Sie den Export starten, AWS Clean Rooms schreiben Sie ein Null-Byte-Objekt mit dem Namen validationSuccess in Ihren Ziel-Bucket, um zu bestätigen, dass es dort schreiben kann. Schlägt diese Prüfung fehl, schlägt die Anfrage sofort mit einem Validierungsfehler fehl, anstatt später im Hintergrund.

Console

Um Protokolle für eine Abfrage zu exportieren (Konsole)

1. Melden Sie sich bei der an AWS-Managementkonsole und öffnen Sie die AWS Clean Rooms Konsole.

2. Wählen Sie im linken Navigationsbereich Collaborations aus.

3. Wählen Sie die Kollaboration aus, die die Abfrage enthält.

4. Wählen Sie die Registerkarte „Analyse“.

5. Führen Sie eine der folgenden Aufgaben aus:

   • Wählen Sie in der Abfragetabelle die Abfrage aus, wählen Sie Aktionen und dann Abfrageanalyseprotokolle exportieren aus.

   • Wählen Sie die Abfrage aus, um ihre Detailseite zu öffnen, und wählen Sie dann Analyseprotokolle exportieren aus.

6. Wählen Sie im Dialogfeld den Amazon S3-Ziel-Bucket und optional ein Schlüsselpräfix aus.

7. Wählen Sie Export aus.

Wenn die Option Abfrageanalyseprotokolle exportieren nicht verfügbar ist, erklärt die Konsole den Grund dafür. In der folgenden Tabelle sind die Meldungen und deren Behebung aufgeführt.

Fehlermeldung	Auflösung
Die Abfrage muss einen Terminalstatus erreicht haben, bevor Protokolle exportiert werden können.	Warten Sie, bis die Abfrage abgeschlossen ist.
Sie haben nicht die Möglichkeit, Abfrageanalyseprotokolle zu exportieren.	Bitten Sie ein Mitglied der Kollaboration, eine Änderungsanfrage einzureichen, um Ihre Mitgliedschaft um diese Funktion zu erweitern.
Der Protokollexport wird für Abfragen, die differenziellen Datenschutz verwenden, nicht unterstützt.	Keine. Der Protokollexport ist für diese Abfragen nicht verfügbar.
Nur der Abfragerunner oder der Zahler der Abfrage können Analyseprotokolle exportieren.	Bitten Sie das Mitglied, das die Abfrage ausgeführt oder bezahlt hat, die Protokolle zu exportieren.

Die Seite mit den Abfragedetails enthält eine Tabelle mit dem Exportverlauf, in der jeder Export und sein Status aufgeführt sind. Wählen Sie einen fehlgeschlagenen Export, um den Fehler anzuzeigen, oder wählen Sie Ziel anzeigen, um die exportierten Protokolle in Amazon S3 zu öffnen.

API

Um Protokolle für eine Abfrage (API) zu exportieren

Rufen Sie StartAnalysisLogExport an und geben Sie die Mitgliedschaft, die geschützte Abfrage und Ihr Ziel an.

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/"
            }
        }
    }'

Die Antwort gibt ein analysisLogExport Objekt zurück, das ein analysisLogExportId und ein status von enthältIN_PROGRESS.

Um einen Export zu überprüfen, rufen Sie GetAnalysisLogExport mit der Mitglieds-ID und der Export-ID auf und fragen Sie ab, bis der Status SUCCESS oder lautetFAILED. Wenn ein Export fehlschlägt, enthält die Antwort ein error Feld mit einem Code und einer Nachricht.

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

Rufen Sie an, um die Exporte für eine Mitgliedschaft aufzulistenListAnalysisLogExports. Sie können die Ergebnisse nach Abfrageverwendung analysisIdentifier und nach Status des Exports mithilfe filternstatus. Der status Filter akzeptiert IN_PROGRESSSUCCESS, oderFAILED, und verwendet jeweils einen Wert. Dies sind die Status des Exports selbst, nicht der Abfrage, deren Protokolle Sie exportiert haben. Die Ergebnisse sind paginiert.

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

Für eine bestimmte Abfrage und ein bestimmtes Ziel kann jeweils nur ein Export aktiv sein. Wenn Sie einen Export starten, während ein anderer Export für dieselbe Abfrage und dasselbe Amazon S3-Ziel noch läuft, schlägt die Anfrage mit einem Validierungsfehler fehl. Um dieselbe Abfrage zweimal gleichzeitig zu exportieren, verwenden Sie für den zweiten Export ein anderes Schlüsselpräfix.

Sie exportieren unabhängig von anderen Mitgliedern. Wenn Sie und ein anderes Mitglied die Möglichkeit haben und beide dieselbe Abfrage ausgeführt oder dafür bezahlt haben, kann jeder von Ihnen die Protokolle an sein eigenes Ziel exportieren.

Wo die exportierten Logs geschrieben werden

AWS Clean Rooms schreibt die exportierten Logs unter den von Ihnen angegebenen Bucket und Schlüsselpräfix und verwendet dabei die folgende Struktur:

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

Da der Pfad die Export-ID enthält, werden beim mehrmaligen Exportieren derselben Abfrage die Protokolle eines früheren Exports nicht überschrieben.

Ein Export enthält das redigierte Spark-Ereignisprotokoll für die Abfrage. Dieses Protokoll besteht aus einer Reihe strukturierter JSON-Datensätze, die Jobs, Phasen, Aufgaben, Zeitpläne und Abfragepläne abdecken. Spark selbst schreibt dieses Event-Log-Format. Sie können einen Export mit jedem Tool verarbeiten, das Spark-Ereignisprotokolle liest, einschließlich Ihrer eigenen Tools. AWS Clean Rooms bietet keinen Viewer für exportierte Logs. Im Exportverzeichnis folgen die Datensätze dem Layout, das Spark für ein fortlaufendes Ereignisprotokoll verwendet. Ein Verzeichnis mit dem Namen eventlog_v2_protected-query-id enthält eine oder mehrere events_ Dateien sowie eine appstatus_ Datei, in der aufgezeichnet wird, dass die Anwendung abgeschlossen wurde. Die Verzeichnis- und Dateinamen verwenden die geschützte Abfrage-ID anstelle einer internen AWS Clean Rooms ID.

Spark History Server ist ein solches Tool. Um einen Export in Spark History Server anzuzeigen, verweisen Sie mit einer Instanz auf das eventlog_v2_ Verzeichnis für die Abfrage. Ein Export einer Abfrage in 6ba7b810-9dad-11d1-80b4-00c04fd430c8 den Bucket amzn-s3-demo-bucket mit dem Schlüsselpräfix query-logs/ erzeugt beispielsweise Folgendes.

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

In diesem Beispiel legen Sie das Spark History Server-Protokollverzeichnis wie folgt fest. Wenn Sie auf das eventlog_v2_ Verzeichnis zeigen, wird nur die Abfrage gerendert, die Sie exportiert haben. Für das direkte Lesen der Protokolle aus Amazon S3 ist der S3A-Connector erforderlich. Verwenden Sie daher das s3a:// Schema. Die Anmeldeinformationen, mit denen Spark History Server ausgeführt wird, benötigen Lesezugriff auf den Bucket.

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/

Verwenden Sie Spark History Server Version 3.5.0 oder höher. Sie sind für die Einrichtung und den Betrieb Ihrer eigenen Instanz verantwortlich. Informationen zum Ausführen einer Spark History Server-Instanz finden Sie unter Viewing after the fact auf der Apache Spark-Website.

Problembehandlung beim Protokollexport

Die Anfrage schlägt fehl, weil Sie nicht berechtigt sind, Protokolle zu exportieren

Ihre Mitgliedschaft bietet diese CAN_EXPORT_QUERY_ANALYSIS_LOG Möglichkeit nicht. Ein Kollaborationsmitglied muss eine Änderungsanfrage einreichen, um die Fähigkeit hinzuzufügen, und alle Mitglieder müssen sie genehmigen. Weitere Informationen finden Sie unter Aktualisieren Sie die Fähigkeiten der Mitglieder.

Die Anfrage schlägt fehl, weil nicht in den Bucket geschrieben werden kann

Stellen Sie sicher, dass der Bucket existiert, dass er mit der Kollaboration AWS-Region identisch ist und dass Sie die Berechtigung haben, in ihn zu schreiben. Wenn die Bucket-Richtlinie Schreibvorgänge auf einen bestimmten VPC-Endpunkt ablehnt oder einschränkt, AWS Clean Rooms können Sie nicht in den Bucket schreiben. s3:PutObject

Wenn der Bucket einen vom Kunden verwalteten Schlüssel verwendet SSE-KMS , kann dieser Fehler auch bedeuten, dass Sie nicht berechtigt sind, diesen Schlüssel zu verwenden. Bestätigen Sie, dass die Schlüsselrichtlinie es Ihnen ermöglicht, Amazon S3 anzurufen kms:GenerateDataKey und kms:Decrypt über Amazon S3 zu nutzen.

Der Export schlägt fehl, weil die Abfrage nie ausgeführt wurde

Die Abfrage erreichte einen Terminalstatus, ohne auf Spark ausgeführt zu werden, sodass keine Protokolle erstellt wurden. Dies passiert, wenn eine Abfrage die Validierung nicht besteht oder vor dem Start abgebrochen wird. Der Export schlägt mit dem Fehlercode LOGS_NOT_AVAILABLE und der Meldung fehl, dass für die Abfrage keine Protokolle zur Abfrageausführung verfügbar sind. Es gibt nichts zum Exportieren.

Die Anfrage schlägt fehl, weil die Abfrage ausgeführt wurde, bevor der Protokollexport verfügbar war

Redigierte Protokolle werden erstellt, während eine Abfrage ausgeführt wird. Eine Abfrage, die ausgeführt wurde, bevor der Protokollexport verfügbar wurde, hat keine AWS Clean Rooms erzeugt, sodass nichts exportiert werden kann. Um Protokolle für dieselbe Analyse abzurufen, führen Sie die Abfrage erneut aus und exportieren Sie die Protokolle für die neue Ausführung.

Die Anfrage schlägt fehl, weil ein Kontingent überschritten wurde

Sie haben die maximale Anzahl von Exporten erreicht, die gleichzeitig ausgeführt werden können. Warten Sie, bis ein laufender Export abgeschlossen ist, und versuchen Sie es dann erneut.

Der Export beginnt, schlägt dann aber fehl

Die anfängliche Berechtigungsprüfung bestätigt, dass nur in dem Moment, in dem Sie den Export starten, in Ihren Bucket schreiben AWS Clean Rooms kann. Wenn sich Ihre Berechtigungen ändern oder wenn die für den Export verwendeten Anmeldeinformationen gesperrt werden, während der Export ausgeführt wird, schlägt der Export fehl, nachdem er gestartet wurde. Rufen Sie GetAnalysisLogExport an, um den Fehler zu sehen, die Ursache zu beheben und einen neuen Export zu starten.

Der Export schlägt fehl und es wird ein interner Fehler gemeldet

Ein interner Fehler kann bedeuten, dass keine Protokolle für die Abfrage erstellt wurden. Sie können den Export erneut versuchen.

Die exportierten Protokolle scheinen unvollständig zu sein

Wenn die Abfrage beendet wurde, weil einem Prozess der Arbeitsspeicher ausgegangen ist, fehlen möglicherweise einige Protokollausgaben, da Protokolle, die auf einem Host gespeichert sind, der abrupt beendet wird, nicht wiederhergestellt werden. Die Protokolle, die bereits geschrieben wurden, werden weiterhin exportiert.

Im Bucket befindet sich ein validationSuccess Null-Byte-Objekt

AWS Clean Rooms schreibt dieses Objekt mit dem von Ihnen angegebenen Schlüsselpräfix, um zu überprüfen, ob es in Ihr Ziel schreiben kann, bevor Sie einen Export starten. Es ist getrennt von den exportierten Protokollen, die in das eigene Verzeichnis des Exports geschrieben werden, und Sie können es löschen. Beenden Sie Ihr Schlüsselpräfix mit einem Schrägstrich, sodass dieses Objekt innerhalb des Präfixes und nicht neben dem Präfix erstellt wird.

Überlegungen und Einschränkungen

• Sie können Protokolle für SQL-Abfragen exportieren, die nach dem 11. August 2026 ausgeführt wurden. Der Protokollexport unterstützt keine PySpark Jobs.

• Der Protokollexport wird nicht für Abfragen unterstützt, bei denen die Überprüfung fehlgeschlagen ist oder die vor Erreichen des STARTED Status abgebrochen wurden.

• Der Protokollexport wird für Abfragen, die differenziellen Datenschutz verwenden, nicht unterstützt. Weitere Informationen finden Sie unter AWS Clean Rooms Differenzierter Datenschutz.

• Der Ziel-Bucket für den Protokollexport muss sich im selben AWS-Region wie die Kollaboration befinden. Cross-Region Export wird nicht unterstützt.

• Es liegt in Ihrer Verantwortung, den Ziel-Bucket für den Log-Export zu sichern. Blockieren Sie den öffentlichen Zugriff auf den Bucket und aktivieren Sie die Protokollierung des Serverzugriffs, wenn Sie eine Aufzeichnung darüber benötigen, wer die exportierten Logs liest.

• AWS Clean Rooms akzeptiert keinen AWS KMS Schlüssel für den Protokollexport. Exportierte Protokolle werden mit der Standardverschlüsselungskonfiguration des Amazon S3-Ziel-Buckets verschlüsselt. Um sie mit einem vom Kunden verwalteten Schlüssel zu verschlüsseln, konfigurieren Sie die Standardverschlüsselung des Buckets so, dass dieser Schlüssel verwendet wird, bevor Sie exportieren.

• Der Protokollexport unterstützt nur Abfragen, die einen Terminalstatus erreicht haben: SUCCESSFAILED,CANCELLED, oderTIMED_OUT.

• Sie können einen Export nicht abbrechen, nachdem er gestartet wurde.

Informationen zu den Kontingenten, die für den Protokollexport gelten, einschließlich der Anzahl der Exporte, die gleichzeitig ausgeführt werden können, finden Sie unterKontingente für AWS Clean Rooms.