View a markdown version of this page

Exportação de registros de análise de consultas - AWS Clean Rooms
Pré-requisitosExportar logsLocalização do registroSolução de problemasConsiderações e limitações

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Exportação de registros de análise de consultas

AWS Clean Rooms executa consultas SQL no Apache Spark. Quando uma consulta falha ou é executada lentamente, os registros do Spark dessa consulta contêm os detalhes de execução necessários para encontrar a causa. Eles mostram qual estágio falhou, como o trabalho foi distribuído entre as tarefas, quanta memória foi usada e onde o tempo foi gasto.

Uma consulta é executada em dados fornecidos por vários membros da colaboração. Portanto, os registros brutos do Spark podem revelar informações sobre os dados de outro membro, como nomes de tabelas, locais de armazenamento e valores de dados. Por esse motivo, AWS Clean Rooms não fornece os registros brutos. Em vez disso, ele produz uma cópia editada na qual os dados do cliente e os metadados dos membros são editados. AWS Clean Rooms exporta essa cópia para um bucket do Amazon S3 que você possui. Em seguida, você analisa os registros exportados com as ferramentas de sua escolha, como o Spark History Server.

Importante

Os registros exportados são editados. Os valores dos dados são removidos e as contagens e os tamanhos são relatados como aproximações para que não revelem detalhes sobre os dados na colaboração. Como resultado, os registros exportados não coincidem com os registros que um trabalho do Spark produz fora deles. AWS Clean Rooms Antes de interpretá-los, leiaEntendendo os registros editados.

Pré-requisitos

Antes de exportar registros para uma consulta, todas as afirmações a seguir devem ser verdadeiras:

  • Sua associação tem a capacidade de ser CAN_EXPORT_QUERY_ANALYSIS_LOG membro. Cada membro da colaboração deve aprovar uma solicitação de mudança para conceder essa habilidade. Para obter mais informações, consulte Atualizar as habilidades dos membros.

  • Você é o executor da consulta ou o pagador da consulta. Ter a habilidade por si só não é suficiente: você pode exportar registros somente para consultas que você executou ou pelas quais pagou.

  • A consulta atingiu um estado terminal. Você pode exportar registros para uma consulta com um status de SUCCESSFAILED,CANCELLED, ouTIMED_OUT. Você não pode exportar registros enquanto uma consulta ainda está em execução.

A exportação de registros não está disponível para todas as consultas. Para os casos que não são suportados, consulteConsiderações e limitações.

Você não precisa criar uma função do IAM para exportação de registros. AWS Clean Rooms grava os registros exportados usando sua própria identidade, então ele grava os registros somente onde suas próprias permissões já permitem. Como prática com menos privilégios, conceda acesso de gravação somente ao bucket e ao prefixo da chave que você usa para os registros exportados.

nota

Se o bucket de destino for usado SSE-KMS com uma chave gerenciada pelo cliente, você deverá ter permissão para usar essa chave. Se você não fizer isso, a solicitação de exportação falhará imediatamente.

Exportação de registros para uma consulta

A exportação de registros é assíncrona. Quando você inicia uma exportação, AWS Clean Rooms retorna imediatamente com uma ID de exportação e um status deIN_PROGRESS, depois edita e copia os registros em segundo plano.

Antes de iniciar a exportação, AWS Clean Rooms grava um objeto de zero byte nomeado em seu bucket de destino validationSuccess para confirmar que ele pode ser gravado lá. Se essa verificação falhar, a solicitação falhará imediatamente com um erro de validação, em vez de falhar posteriormente em segundo plano.

Console
Para exportar registros para uma consulta (console)

  1. Faça login no Console de gerenciamento da AWS e abra o AWS Clean Rooms console.

  2. No painel de navegação à esquerda, escolha Colaborações.

  3. Escolha a colaboração que contém a consulta.

  4. Escolha a guia Análise.

  5. Realize um dos procedimentos a seguir:

    • Na tabela de consultas, selecione a consulta, escolha Ações e escolha Exportar registros de análise de consultas.

    • Escolha a consulta para abrir sua página de detalhes e, em seguida, escolha Exportar registros de análise.

  6. Na caixa de diálogo, escolha o bucket de destino do Amazon S3 e, opcionalmente, um prefixo de chave.

  7. Escolha Exportar.

Se a opção Exportar registros de análise de consultas não estiver disponível, o console explica o motivo. A tabela a seguir lista as mensagens e como resolvê-las.

Mensagem Resolução
A consulta deve atingir um estado terminal antes que os registros possam ser exportados. Aguarde até que a consulta termine de ser executada.
Você não tem a capacidade de exportar registros de análise de consultas. Peça a um membro da colaboração que envie uma solicitação de alteração adicionando a habilidade à sua associação.
A exportação de registros não é suportada para consultas que usam privacidade diferencial. Nenhum. A exportação de registros não está disponível para essas consultas.
Somente o executor da consulta ou o pagador da consulta pode exportar registros de análise. Peça ao membro que executou ou pagou pela consulta que exporte os registros.

A página de detalhes da consulta inclui uma tabela do histórico de exportação listando cada exportação e seu status. Escolha uma exportação com falha para ver o erro ou escolha Exibir destino para abrir os registros exportados no Amazon S3.

API

Para exportar registros para uma consulta (API)

LigueStartAnalysisLogExport, especificando a associação, a consulta protegida e seu destino.

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 resposta retorna um analysisLogExport objeto contendo um analysisLogExportId e um status deIN_PROGRESS.

Para verificar uma exportação, ligue GetAnalysisLogExport com o identificador de associação e o identificador de exportação e faça uma pesquisa até que o status seja SUCCESS ouFAILED. Quando uma exportação falha, a resposta inclui um error campo com um código e uma mensagem.

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

Para listar as exportações de uma associação, ligueListAnalysisLogExports. Você pode filtrar os resultados por consulta usando analysisIdentifier e pelo status da exportação usandostatus. O status filtro aceitaIN_PROGRESS,SUCCESS, ouFAILED, e assume um valor por vez. Esses são os status da exportação em si, não da consulta cujos registros você exportou. Os resultados são paginados.

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

Somente uma exportação pode estar ativa por vez para uma determinada consulta e destino. Se você iniciar uma exportação enquanto outra exportação para a mesma consulta e o mesmo destino do Amazon S3 ainda estiver em andamento, a solicitação falhará com um erro de validação. Para exportar a mesma consulta duas vezes ao mesmo tempo, use um prefixo de chave diferente para a segunda exportação.

Você exporta independentemente dos outros membros. Se você e outro membro tiverem a habilidade e executarem ou pagarem pela mesma consulta, cada um de vocês poderá exportar os registros para seu próprio destino.

Onde os registros exportados são gravados

AWS Clean Rooms grava os registros exportados sob o intervalo e o prefixo da chave que você especificar, usando a seguinte estrutura:

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

Como o caminho inclui o ID de exportação, exportar a mesma consulta mais de uma vez não substitui os registros de uma exportação anterior.

Uma exportação contém o registro de eventos do Spark editado para a consulta. Esse registro é um conjunto de registros JSON estruturados que abrangem trabalhos, estágios, tarefas, horários e planos de consulta. O próprio Spark grava esse formato de registro de eventos. Você pode processar uma exportação com qualquer ferramenta que leia os registros de eventos do Spark, incluindo suas próprias ferramentas. AWS Clean Rooms não fornece um visualizador para os registros exportados. No diretório de exportação, os registros seguem o layout que o Spark usa para um registro contínuo de eventos. Um diretório chamado eventlog_v2_protected-query-id contém um ou mais events_ arquivos e um appstatus_ arquivo que registra que o aplicativo foi concluído. Os nomes do diretório e do arquivo usam o ID da consulta protegida em vez de um AWS Clean Rooms identificador interno.

O Spark History Server é uma dessas ferramentas. Para ver uma exportação no Spark History Server, aponte uma instância para o eventlog_v2_ diretório da consulta. Por exemplo, uma exportação de consulta 6ba7b810-9dad-11d1-80b4-00c04fd430c8 para o bucket amzn-s3-demo-bucket com o prefixo de chave query-logs/ produz o seguinte.

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

Neste exemplo, defina o diretório de log do Spark History Server como o seguinte. Apontar para o eventlog_v2_ diretório renderiza somente a consulta que você exportou. A leitura dos registros diretamente do Amazon S3 requer o conector S3A, então use o esquema. s3a:// As credenciais com as quais o Spark History Server é executado precisam de acesso de leitura ao 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/

Use o Spark History Server versão 3.5.0 ou posterior. Você é responsável por configurar e executar sua própria instância. Para obter informações sobre como executar uma instância do Spark History Server, consulte Visualizando após o fato no site do Apache Spark.

Solução de problemas na exportação de registros

A solicitação falha porque você não tem permissão para exportar registros

Sua associação não tem a CAN_EXPORT_QUERY_ANALYSIS_LOG capacidade. Um membro da colaboração deve enviar uma solicitação de alteração para adicionar a habilidade, e todos os membros devem aprová-la. Para obter mais informações, consulte Atualizar as habilidades dos membros.

A solicitação falha porque não é possível gravar no bucket

Verifique se o bucket existe, se é o Região da AWS mesmo da colaboração e se você tem permissão para gravar nele. Se a política do bucket negar s3:PutObject ou restringir as gravações em um endpoint VPC específico, não AWS Clean Rooms poderá gravar no bucket.

Se o bucket for usado SSE-KMS com uma chave gerenciada pelo cliente, esse erro também pode significar que você não tem permissão para usar essa chave. Confirme se a política de chaves permite que você ligue kms:GenerateDataKey e use kms:Decrypt o Amazon S3.

A exportação falha porque a consulta nunca foi executada

A consulta atingiu um estado terminal sem ser executada no Spark, então nenhum registro foi produzido. Isso acontece quando uma consulta falha na validação ou é cancelada antes de começar. A exportação falha com um código de erro LOGS_NOT_AVAILABLE e uma mensagem informando que nenhum registro de execução de consulta está disponível para a consulta. Não há nada para exportar.

A solicitação falha porque a consulta foi executada antes da exportação do log estar disponível

Os registros editados são produzidos enquanto uma consulta é executada. Uma consulta executada antes da exportação do log se tornar disponível em não AWS Clean Rooms produziu nenhuma, então não há nada para exportar. Para obter registros para a mesma análise, execute a consulta novamente e exporte os registros para a nova execução.

A solicitação falha porque uma cota foi excedida

Você atingiu o número máximo de exportações que podem estar em andamento ao mesmo tempo. Aguarde a conclusão de uma exportação em andamento e tente novamente.

A exportação começa, mas depois falha

A verificação de permissão inicial confirma que somente quem AWS Clean Rooms pode gravar em seu bucket no momento em que você inicia a exportação. Se suas permissões mudarem ou se as credenciais usadas para a exportação forem revogadas enquanto a exportação estiver em execução, a exportação falhará após o início. Ligue GetAnalysisLogExport para ver o erro, resolver a causa e iniciar uma nova exportação.

A exportação falha e relata um erro interno

Um erro interno pode significar que nenhum registro foi produzido para a consulta. Você pode tentar exportar novamente.

Os registros exportados parecem incompletos

Se a consulta terminou porque um processo ficou sem memória, pode estar faltando alguma saída de log, porque os registros mantidos em um host que para abruptamente não são recuperados. Os registros que já foram gravados ainda são exportados.

Há um validationSuccess objeto de zero byte no bucket

AWS Clean Rooms grava esse objeto no prefixo de chave que você especificou, para verificar se ele pode gravar no seu destino antes de iniciar uma exportação. Ele é separado dos registros exportados, que são gravados no próprio diretório da exportação, e você pode excluí-lo. Finalize o prefixo da chave com uma barra para que esse objeto seja criado dentro do prefixo e não ao lado dele.

Considerações e limitações

  • Você pode exportar registros para consultas SQL executadas após 11 de agosto de 2026. A exportação de registros não oferece suporte a PySpark trabalhos.

  • A exportação de registros não é suportada para consultas que falharam na validação ou foram canceladas antes de atingirem o STARTED status.

  • A exportação de registros não é suportada para consultas que usam privacidade diferencial. Para obter mais informações, consulte AWS Clean Rooms Privacidade diferencial.

  • O bucket de destino para exportação de registros deve ser o Região da AWS mesmo da colaboração. Cross-Region a exportação não é suportada.

  • Proteger o bucket de destino para exportação de registros é de sua responsabilidade. Bloqueie o acesso público ao bucket e ative o registro de acesso ao servidor se precisar de um registro de quem lê os registros exportados.

  • AWS Clean Rooms não aceita uma AWS KMS chave para exportação de registros. Os registros exportados são criptografados usando a configuração de criptografia padrão do bucket Amazon S3 de destino. Para criptografá-los com uma chave gerenciada pelo cliente, configure a criptografia padrão do bucket para usar essa chave antes de exportar.

  • A exportação de registros suporta somente consultas que atingiram um estado terminal:SUCCESS,, FAILEDCANCELLED, ouTIMED_OUT.

  • Você não pode cancelar uma exportação depois que ela começar.

Para cotas que se aplicam à exportação de registros, incluindo o número de exportações que podem ser executadas ao mesmo tempo, consulteCotas para AWS Clean Rooms.