Esportazione dei log di analisi delle query

AWS Clean Rooms esegue query SQL su Apache Spark. Quando una query fallisce o viene eseguita lentamente, i log di Spark relativi a tale query contengono i dettagli di esecuzione necessari per trovare la causa. Mostrano quale fase non è riuscita, come è stato distribuito il lavoro tra le attività, quanta memoria è stata utilizzata e dove è stato impiegato il tempo.

Una query viene eseguita tra i dati forniti da diversi membri della collaborazione. I log grezzi di Spark possono quindi rivelare informazioni sui dati di un altro membro, come nomi di tabelle, posizioni di archiviazione e valori dei dati. Per questo motivo, AWS Clean Rooms non fornisce i log grezzi. Produce invece una copia oscurata in cui i dati dei clienti e i metadati dei membri vengono oscurati. AWS Clean Rooms esporta quella copia in un bucket Amazon S3 di tua proprietà. Quindi analizzi i log esportati con gli strumenti di tua scelta, come Spark History Server.

Importante

I log esportati vengono cancellati. I valori dei dati vengono rimossi e i conteggi e le dimensioni vengono riportati come approssimazioni in modo che non rivelino dettagli sui dati della collaborazione. Di conseguenza, i log esportati non corrispondono ai log prodotti da un job Spark all'esterno. AWS Clean Rooms Prima di interpretarli, leggi. Informazioni sui log oscurati

Prerequisiti

Prima di poter esportare i log per una query, è necessario che siano vere tutte le seguenti condizioni:

• La tua iscrizione ha l'abilità di CAN_EXPORT_QUERY_ANALYSIS_LOG socio. Ogni membro della collaborazione deve approvare una richiesta di modifica per concedere questa capacità. Per ulteriori informazioni, consulta Aggiorna le abilità dei membri.

• Sei l'autore della query o il pagatore della query. Avere questa capacità non è sufficiente da solo: puoi esportare i log solo per le query che hai eseguito o per le quali hai pagato.

• La richiesta ha raggiunto lo stato terminale. È possibile esportare i log per una query con lo stato SUCCESSFAILED,CANCELLED, oTIMED_OUT. Non è possibile esportare i log mentre una query è ancora in esecuzione.

L'esportazione dei log non è disponibile per tutte le query. Per i casi non supportati, consultaConsiderazioni e limitazioni.

Non è necessario creare un ruolo IAM per l'esportazione dei log. AWS Clean Rooms scrive i log esportati utilizzando la tua identità, quindi scrive i log solo dove le tue autorizzazioni lo consentono già. Come pratica con privilegi minimi, concedi l'accesso in scrittura solo al bucket e al prefisso di chiave utilizzati per i log esportati.

Nota

Se il bucket di destinazione utilizza SSE-KMS una chiave gestita dal cliente, devi disporre dell'autorizzazione per utilizzare tale chiave. In caso contrario, la richiesta di esportazione fallisce immediatamente.

Esportazione dei log per una query

L'esportazione dei log è asincrona. Quando si avvia un'esportazione, viene AWS Clean Rooms restituita immediatamente con un ID di esportazione e uno stato diIN_PROGRESS, quindi oscura e copia i registri in background.

Prima di iniziare l'esportazione, AWS Clean Rooms scrive un oggetto a zero byte denominato nel bucket validationSuccess di destinazione per confermare che possa scrivervi. Se questo controllo fallisce, la richiesta fallisce immediatamente con un errore di convalida invece di fallire più tardi in background.

Console

Per esportare i log per una query (console)

1. Accedi Console di gestione AWS e apri la AWS Clean Rooms console.

2. Nel riquadro di navigazione a sinistra, scegli Collaborazioni.

3. Scegli la collaborazione che contiene la query.

4. Scegli la scheda Analisi.

5. Esegui una delle operazioni seguenti:

   • Nella tabella delle interrogazioni, seleziona l'interrogazione, scegli Azioni, quindi scegli Esporta registri di analisi delle query.

   • Scegli la query per aprire la relativa pagina dei dettagli, quindi scegli Esporta registri di analisi.

6. Nella finestra di dialogo, scegli il bucket Amazon S3 di destinazione e, facoltativamente, un prefisso chiave.

7. Scegli Export (Esporta).

Se l'opzione Esporta i log di analisi delle query non è disponibile, la console ne spiega il motivo. La tabella seguente elenca i messaggi e come risolverli.

Messaggio	Risoluzione
La query deve raggiungere lo stato di terminale prima di poter esportare i log.	Attendi il termine dell'esecuzione della query.
Non è possibile esportare i log di analisi delle query.	Chiedi a un membro della collaborazione di inviare una richiesta di modifica per aggiungere la possibilità alla tua iscrizione.
L'esportazione dei log non è supportata per le query che utilizzano la privacy differenziale.	Nessuna. L'esportazione dei log non è disponibile per queste query.
Solo chi esegue la query o chi paga la query può esportare i log di analisi.	Chiedi al membro che ha eseguito o pagato la query di esportare i log.

La pagina dei dettagli della query include una tabella della cronologia delle esportazioni che elenca ogni esportazione e il relativo stato. Scegli un'esportazione non riuscita per visualizzare l'errore o scegli Visualizza destinazione per aprire i log esportati in Amazon S3.

API

Per esportare i log per una query (API)

ChiamaStartAnalysisLogExport, specificando l'appartenenza, l'interrogazione protetta e la destinazione.

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

La risposta restituisce un analysisLogExport oggetto contenente un analysisLogExportId e un status diIN_PROGRESS.

Per verificare un'esportazione, chiama GetAnalysisLogExport con l'identificativo di appartenenza e l'identificatore di esportazione ed esegui il polling finché lo stato non è o. SUCCESS FAILED Quando un'esportazione fallisce, la risposta include un error campo con un codice e un messaggio.

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

Per elencare le esportazioni relative a un abbonamento, chiamaListAnalysisLogExports. È possibile filtrare i risultati in base all'uso analysisIdentifier della query e in base allo stato dell'esportazione utilizzandostatus. Il status filtro accetta IN_PROGRESSSUCCESS,FAILED, o e accetta un valore alla volta. Questi sono gli stati dell'esportazione stessa, non della query di cui sono stati esportati i log. I risultati sono suddivisi in pagine.

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

Può essere attiva una sola esportazione alla volta per una determinata query e destinazione. Se avvii un'esportazione mentre è ancora in corso un'altra esportazione per la stessa query e la stessa destinazione Amazon S3, la richiesta ha esito negativo e si verifica un errore di convalida. Per esportare la stessa query due volte contemporaneamente, utilizza un prefisso di chiave diverso per la seconda esportazione.

Esporti indipendentemente dagli altri membri. Se tu e un altro membro ne avete la possibilità e avete eseguito o pagato la stessa query, ognuno di voi può esportare i log verso la propria destinazione.

Dove vengono scritti i log esportati

AWS Clean Rooms scrive i log esportati con il bucket e il prefisso chiave specificati, utilizzando la seguente struttura:

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

Poiché il percorso include l'ID di esportazione, l'esportazione della stessa query più di una volta non sovrascrive i log di un'esportazione precedente.

Un'esportazione contiene il registro degli eventi Spark redatto per la query. Questo registro è un insieme di record JSON strutturati che coprono lavori, fasi, attività, tempistiche e piani di interrogazione. Spark stesso scrive questo formato di registro degli eventi. Puoi elaborare un'esportazione con qualsiasi strumento che legga i registri degli eventi di Spark, inclusi i tuoi strumenti. AWS Clean Rooms non fornisce un visualizzatore per i log esportati. All'interno della directory di esportazione, i record seguono il layout utilizzato da Spark per un registro degli eventi a rotazione. Una directory denominata eventlog_v2_protected-query-id contiene uno o più events_ file e un appstatus_ file che registra il completamento dell'applicazione. I nomi delle directory e dei file utilizzano l'ID di interrogazione protetto anziché un AWS Clean Rooms identificatore interno.

Spark History Server è uno di questi strumenti. Per visualizzare un'esportazione in Spark History Server, punta un'istanza nella eventlog_v2_ directory della query. Ad esempio, un'esportazione di una query 6ba7b810-9dad-11d1-80b4-00c04fd430c8 nel bucket amzn-s3-demo-bucket con il prefisso della chiave query-logs/ produce quanto segue.

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 questo esempio, imposta la directory di log di Spark History Server su quanto segue. Se si punta alla eventlog_v2_ directory, viene visualizzata solo l'interrogazione esportata. La lettura dei log direttamente da Amazon S3 richiede il connettore S3A, quindi utilizza lo schema. s3a:// Le credenziali con cui viene eseguito Spark History Server richiedono l'accesso in lettura al 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/

Usa Spark History Server versione 3.5.0 o successiva. Sei responsabile della configurazione e dell'esecuzione della tua istanza. Per informazioni sull'esecuzione di un'istanza di Spark History Server, vedi Visualizzazione a posteriori sul sito Web di Apache Spark.

Risoluzione dei problemi relativi all'esportazione dei log

La richiesta ha esito negativo perché non si dispone dell'autorizzazione per esportare i log

La tua iscrizione non è CAN_EXPORT_QUERY_ANALYSIS_LOG abilitata. Un membro della collaborazione deve inviare una richiesta di modifica per aggiungere l'abilità e tutti i membri devono approvarla. Per ulteriori informazioni, consulta Aggiorna le abilità dei membri.

La richiesta ha esito negativo perché non è possibile scrivere sul bucket

Verifica che il bucket esista, che faccia parte della Regione AWS collaborazione e che tu disponga dell'autorizzazione per scriverci. Se la policy del bucket s3:PutObject nega o limita le scritture su un endpoint VPC specifico, non AWS Clean Rooms puoi scrivere nel bucket.

Se il bucket utilizza SSE-KMS una chiave gestita dal cliente, questo errore potrebbe anche significare che non sei autorizzato a utilizzare quella chiave. Verifica che la policy chiave ti consenta di chiamare kms:GenerateDataKey e kms:Decrypt tramite Amazon S3.

L'esportazione non riesce perché la query non è mai stata eseguita

La query ha raggiunto lo stato terminale senza essere eseguita su Spark, quindi non è stato prodotto alcun registro. Ciò accade quando una query fallisce la convalida o viene annullata prima di iniziare. L'esportazione ha esito negativo con un codice di errore LOGS_NOT_AVAILABLE e un messaggio che segnala che non sono disponibili registri di esecuzione della query per la query. Non c'è nulla da esportare.

La richiesta ha esito negativo perché la query è stata eseguita prima che l'esportazione del registro fosse disponibile

I log oscurati vengono prodotti durante l'esecuzione di una query. Una query eseguita prima che l'esportazione dei log diventasse disponibile non AWS Clean Rooms ha prodotto alcuna, quindi non c'è nulla da esportare. Per ottenere i log per la stessa analisi, esegui nuovamente la query ed esporta i log per la nuova esecuzione.

La richiesta ha esito negativo perché è stata superata una quota

Hai raggiunto il numero massimo di esportazioni che possono essere in corso contemporaneamente. Attendi il completamento di un'esportazione in corso, quindi riprova.

L'esportazione inizia ma poi fallisce

La verifica iniziale delle autorizzazioni conferma solo che AWS Clean Rooms posso scrivere nel tuo bucket nel momento in cui inizi l'esportazione. Se le tue autorizzazioni cambiano o se le credenziali utilizzate per l'esportazione vengono revocate mentre l'esportazione è in esecuzione, l'esportazione non riesce dopo l'avvio. Chiama GetAnalysisLogExport per visualizzare l'errore, risolvere la causa e avviare una nuova esportazione.

L'esportazione non riesce e riporta un errore interno

Un errore interno potrebbe significare che non è stato prodotto alcun registro per la query. Puoi riprovare l'esportazione.

I log esportati appaiono incompleti

Se la query è terminata perché un processo ha esaurito la memoria, potrebbe mancare un output di registro, perché i log conservati su un host che si arresta bruscamente non vengono ripristinati. I log già scritti vengono ancora esportati.

C'è un oggetto a zero byte nel bucket validationSuccess

AWS Clean Rooms scrive questo oggetto con il prefisso chiave specificato, per verificare che sia in grado di scrivere a destinazione prima di iniziare un'esportazione. È separato dai log esportati, che vengono scritti nella directory dell'esportazione, ed è possibile eliminarlo. Termina il prefisso della chiave con una barra in modo che questo oggetto venga creato all'interno del prefisso anziché accanto ad esso.

Considerazioni e limitazioni

• È possibile esportare i log per le query SQL eseguite dopo l'11 agosto 2026. L'esportazione dei log non supporta PySpark i job.

• L'esportazione dei log non è supportata per le query che non sono state convalidate o sono state annullate prima di raggiungere lo stato. STARTED

• L'esportazione dei log non è supportata per le query che utilizzano la privacy differenziale. Per ulteriori informazioni, consulta AWS Clean Rooms Privacy differenziale.

• Il bucket di destinazione per l'esportazione dei log deve coincidere con la collaborazione Regione AWS . Cross-Region l'esportazione non è supportata.

• La protezione del bucket di destinazione per l'esportazione dei log è tua responsabilità. Blocca l'accesso pubblico al bucket e abilita la registrazione degli accessi al server se hai bisogno di registrare chi legge i log esportati.

• AWS Clean Rooms non accetta una AWS KMS chiave per l'esportazione dei log. I log esportati vengono crittografati utilizzando la configurazione di crittografia predefinita del bucket Amazon S3 di destinazione. Per crittografarli con una chiave gestita dal cliente, configura la crittografia predefinita del bucket in modo da utilizzare tale chiave prima dell'esportazione.

• L'esportazione dei log supporta solo le query che hanno raggiunto uno stato terminale:SUCCESS,FAILED, CANCELLED o. TIMED_OUT

• Non è possibile annullare un'esportazione dopo l'avvio.

Per le quote applicabili all'esportazione dei log, incluso il numero di esportazioni che possono essere eseguite contemporaneamente, vediQuote per AWS Clean Rooms.