Exportación de registros de análisis de consultas

AWS Clean Rooms ejecuta consultas SQL en Apache Spark. Cuando una consulta falla o se ejecuta lentamente, los registros de Spark de esa consulta contienen los detalles de ejecución que necesitas para encontrar la causa. Muestran en qué fase se produjo el error, cómo se distribuyó el trabajo entre las tareas, cuánta memoria se utilizó y en qué se gastó el tiempo.

Una consulta abarca los datos aportados por varios miembros de la colaboración. Por lo tanto, los registros de Raw Spark pueden revelar información sobre los datos de otro miembro, como los nombres de las tablas, las ubicaciones de almacenamiento y los valores de los datos. Por ese motivo, AWS Clean Rooms no te proporciona los registros sin procesar. En su lugar, produce una copia redactada en la que se redactan los datos de los clientes y los metadatos de los miembros. AWS Clean Rooms exporta esa copia a un bucket de Amazon S3 de su propiedad. A continuación, analiza los registros exportados con las herramientas que prefiera, como Spark History Server.

importante

Los registros exportados se redactan. Se eliminan los valores de los datos y los recuentos y tamaños se registran como aproximaciones para que no revelen detalles sobre los datos de la colaboración. Como resultado, los registros exportados no coinciden con los registros que produce un trabajo de Spark fuera de AWS Clean Rooms ellos. Antes de interpretarlos, leeEntender los registros redactados.

Requisitos previos

Para poder exportar los registros de una consulta, debe cumplirse todo lo siguiente:

• Tu membresía tiene la capacidad de ser CAN_EXPORT_QUERY_ANALYSIS_LOG miembro. Todos los miembros de la colaboración deben aprobar una solicitud de cambio para conceder esta capacidad. Para obtener más información, consulte Actualiza las habilidades de los miembros.

• Usted es el ejecutor de la consulta o el pagador de la consulta. Tener esta capacidad no basta por sí solo: solo puede exportar los registros de las consultas que haya realizado o por las que haya pagado.

• La consulta ha alcanzado un estado terminal. Puede exportar los registros de una consulta con el estado de SUCCESSFAILED,CANCELLED, oTIMED_OUT. No puedes exportar los registros mientras la consulta esté en ejecución.

La exportación de registros no está disponible para todas las consultas. Para conocer los casos que no se admiten, consulteConsideraciones y limitaciones.

No es necesario crear un rol de IAM para la exportación de registros. AWS Clean Rooms escribe los registros exportados con tu propia identidad, por lo que solo escribe los registros cuando tus propios permisos ya lo permiten. Como práctica de mínimo privilegio, concede acceso de escritura únicamente al bucket y al prefijo de clave que utilices para los registros exportados.

nota

Si el bucket de destino se usa SSE-KMS con una clave gestionada por el cliente, debes tener permiso para usar esa clave. Si no lo haces, la solicitud de exportación fallará de inmediato.

Exportación de registros para una consulta

La exportación de registros es asincrónica. Al iniciar una exportación, AWS Clean Rooms regresa inmediatamente con un identificador de exportación y un estado deIN_PROGRESS, y luego redacta y copia los registros en segundo plano.

Antes de iniciar la exportación, AWS Clean Rooms escribe un objeto de cero bytes con el nombre validationSuccess de tu bucket de destino para confirmar que puede escribir allí. Si esta comprobación falla, la solicitud falla inmediatamente y se produce un error de validación, en lugar de fallar más adelante en segundo plano.

Console

Para exportar los registros de una consulta (consola)

1. Inicie sesión en la AWS Clean Rooms consola Consola de administración de AWS y ábrala.

2. En el panel de navegación izquierdo, elija Colaboraciones.

3. Elija la colaboración que contiene la consulta.

4. Elija la pestaña Análisis.

5. Haga una de estas dos operaciones:

   • En la tabla de consultas, seleccione la consulta, elija Acciones y, a continuación, elija Exportar registros de análisis de consultas.

   • Elija la consulta para abrir su página de detalles y, a continuación, elija Exportar registros de análisis.

6. En el cuadro de diálogo, elija el bucket de Amazon S3 de destino y, si lo desea, un prefijo clave.

7. Seleccione Exportar.

Si la opción Exportar los registros de análisis de consultas no está disponible, la consola explica el motivo. En la tabla siguiente se enumeran los mensajes y cómo resolverlos.

Mensaje	Resolución
La consulta debe alcanzar un estado terminal antes de poder exportar los registros.	Espere a que la consulta termine de ejecutarse.
No puede exportar los registros de análisis de consultas.	Pídele a un miembro de la colaboración que envíe una solicitud de cambio para añadir la posibilidad a tu membresía.
La exportación de registros no es compatible con las consultas que utilizan la privacidad diferencial.	Ninguna. La exportación de registros no está disponible para estas consultas.
Solo el ejecutor de consultas o el pagador de la consulta pueden exportar los registros de análisis.	Pide al miembro que ejecutó la consulta o pagó por ella que exporte los registros.

La página de detalles de la consulta incluye una tabla del historial de exportaciones en la que se muestra cada exportación y su estado. Seleccione una exportación fallida para ver el error o seleccione Ver destino para abrir los registros exportados en Amazon S3.

API

Para exportar los registros de una consulta (API)

Llama StartAnalysisLogExport especificando la membresía, la consulta protegida y tu 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/"
            }
        }
    }'

La respuesta devuelve un analysisLogExport objeto que contiene un analysisLogExportId signo y un status deIN_PROGRESS.

Para comprobar el estado de una exportación, llama GetAnalysisLogExport con el identificador de pertenencia y el identificador de exportación y sondea hasta que el estado sea SUCCESS oFAILED. Cuando se produce un error en la exportación, la respuesta incluye un error campo con un código y un mensaje.

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

Para ver una lista de las exportaciones de una membresía, llamaListAnalysisLogExports. Puedes filtrar los resultados por consulta usando analysisIdentifier y por el estado de la exportación usandostatus. El status filtro acepta IN_PROGRESS SUCCESSFAILED, o y toma un valor cada vez. Estos son los estados de la exportación en sí, no de la consulta cuyos registros ha exportado. Los resultados están paginados.

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

Solo puede haber una exportación activa a la vez para una consulta y un destino determinados. Si inicia una exportación mientras otra exportación para la misma consulta y el mismo destino de Amazon S3 aún está en curso, la solicitud no se realizará correctamente y se producirá un error de validación. Para exportar la misma consulta dos veces a la vez, utilice un prefijo de clave diferente para la segunda exportación.

La exportación se realiza de forma independiente de los demás miembros. Si tú y otro miembro tenéis la posibilidad y habéis realizado o pagado la misma consulta, cada uno de vosotros puede exportar los registros a su propio destino.

Dónde se escriben los registros exportados

AWS Clean Rooms escribe los registros exportados en el bucket y el prefijo de clave que especifiques, con la siguiente estructura:

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

Como la ruta incluye el identificador de exportación, exportar la misma consulta más de una vez no sobrescribe los registros de una exportación anterior.

Una exportación contiene el registro de eventos de Spark redactado para la consulta. Este registro es un conjunto de registros JSON estructurados que abarcan los trabajos, las etapas, las tareas, los tiempos y los planes de consulta. El propio Spark escribe este formato de registro de eventos. Puedes procesar una exportación con cualquier herramienta que lea los registros de eventos de Spark, incluidas tus propias herramientas. AWS Clean Rooms no proporciona un visor para los registros exportados. En el directorio de exportación, los registros siguen el diseño que usa Spark para un registro de eventos continuo. Un directorio denominado eventlog_v2_protected-query-id contiene uno o más events_ archivos y un appstatus_ archivo que registra que la solicitud se completó. Los nombres de directorio y archivo utilizan el identificador de consulta protegido en lugar de un AWS Clean Rooms identificador interno.

Spark History Server es una de esas herramientas. Para ver una exportación en Spark History Server, coloca una instancia en el eventlog_v2_ directorio de la consulta. Por ejemplo, una exportación de una consulta 6ba7b810-9dad-11d1-80b4-00c04fd430c8 al bucket amzn-s3-demo-bucket con el prefijo clave query-logs/ produce lo siguiente.

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

En este ejemplo, defina el directorio de registro del servidor Spark History de la siguiente manera. Al apuntar al eventlog_v2_ directorio, solo se muestra la consulta que has exportado. Para leer los registros directamente desde Amazon S3 se requiere el conector S3A, así que utilice el s3a:// esquema. Las credenciales con las que se ejecuta Spark History Server necesitan acceso de lectura 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 la versión 3.5.0 o posterior de Spark History Server. Eres responsable de configurar y ejecutar tu propia instancia. Para obtener información sobre cómo ejecutar una instancia de Spark History Server, consulta Cómo ver después del hecho en el sitio web de Apache Spark.

Solución de problemas y exportación de registros

Se produce un error en la solicitud porque no tienes permiso para exportar los registros

Tu membresía no lo CAN_EXPORT_QUERY_ANALYSIS_LOG permite. Un miembro de la colaboración debe enviar una solicitud de cambio para añadir la capacidad y todos los miembros deben aprobarla. Para obtener más información, consulte Actualiza las habilidades de los miembros.

La solicitud falla porque no se puede escribir en el bucket

Comprueba que el bucket existe, que está en el Región de AWS mismo lugar que la colaboración y que tienes permiso para escribir en él. Si la política de bucket deniega s3:PutObject o restringe las escrituras en un punto final de la VPC específico, no AWS Clean Rooms podrás escribir en el bucket.

Si el bucket se usa SSE-KMS con una clave gestionada por el cliente, este error también puede significar que no tienes permiso para usar esa clave. Confirma que la política de claves te permite llamar kms:GenerateDataKey y kms:Decrypt usar Amazon S3.

La exportación falla porque la consulta nunca se ejecutó

La consulta llegó a un estado terminal sin ejecutarse en Spark, por lo que no se generó ningún registro. Esto ocurre cuando una consulta no se valida o se cancela antes de que comience. La exportación falla y aparece un código de error de LOGS_NOT_AVAILABLE y un mensaje en el que se indica que no hay registros de ejecución de la consulta disponibles para la consulta. No hay nada que exportar.

La solicitud falla porque la consulta se ejecutó antes de que la exportación del registro estuviera disponible

Los registros redactados se producen mientras se ejecuta una consulta. Una consulta que se ejecutó antes de que la exportación de registros estuviera disponible no AWS Clean Rooms produjo ninguna, por lo que no hay nada que exportar. Para obtener los registros del mismo análisis, vuelva a ejecutar la consulta y exporte los registros para la nueva ejecución.

Se produce un error en la solicitud porque se ha superado una cuota

Has alcanzado el número máximo de exportaciones que pueden estar en curso al mismo tiempo. Espere a que finalice una exportación en curso y vuelva a intentarlo.

La exportación se inicia, pero luego falla

La verificación inicial de permisos confirma que solo AWS Clean Rooms puede escribir en tu bucket en el momento en que comiences la exportación. Si tus permisos cambian o si las credenciales utilizadas para la exportación se revocan mientras la exportación está en ejecución, la exportación fallará una vez iniciada. Llame GetAnalysisLogExport para ver el error, resolver la causa e iniciar una nueva exportación.

Se produce un error en la exportación e informa de un error interno

Un error interno puede indicar que no se ha generado ningún registro para la consulta. Puede volver a intentar la exportación.

Los registros exportados parecen incompletos

Si la consulta finalizó porque un proceso se quedó sin memoria, es posible que falte alguna salida del registro, ya que los registros guardados en un host que se detiene bruscamente no se recuperan. Los registros que ya estaban escritos se siguen exportando.

Hay un validationSuccess objeto de cero bytes en el bucket

AWS Clean Rooms escribe este objeto en el prefijo clave que especificaste para comprobar que puede escribir en tu destino antes de iniciar la exportación. Es independiente de los registros exportados, que se escriben en el propio directorio de la exportación, y puedes eliminarlo. Termine el prefijo clave con una barra para que este objeto se cree dentro del prefijo y no al lado de él.

Consideraciones y limitaciones

• Puedes exportar los registros de las consultas SQL ejecutadas después del 11 de agosto de 2026. La exportación de registros no admite PySpark trabajos.

• La exportación de registros no se admite para las consultas que no se validaron o que se cancelaron antes de alcanzar el STARTED estado.

• La exportación de registros no es compatible con las consultas que utilizan la privacidad diferencial. Para obtener más información, consulte AWS Clean Rooms Privacidad diferencial.

• El bucket de destino para la exportación de registros debe estar en el Región de AWS mismo lugar que el de la colaboración. Cross-Region no se admite la exportación.

• Es su responsabilidad proteger el bucket de destino para la exportación de registros. Bloquea el acceso público al depósito y habilita el registro de acceso al servidor si necesitas un registro de quién lee los registros exportados.

• AWS Clean Rooms no acepta una AWS KMS clave para la exportación de registros. Los registros exportados se cifran con la configuración de cifrado predeterminada del bucket de Amazon S3 de destino. Para cifrarlos con una clave gestionada por el cliente, configure el cifrado predeterminado del bucket para usar esa clave antes de la exportación.

• La exportación de registros solo admite consultas que hayan alcanzado un estado terminal:SUCCESS, FAILEDCANCELLED, oTIMED_OUT.

• No puedes cancelar una exportación una vez iniciada.

Para conocer las cuotas que se aplican a la exportación de registros, incluido el número de exportaciones que se pueden realizar al mismo tiempo, consulteCuotas para AWS Clean Rooms.