Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Uso de la biblioteca de procesamiento de CloudTrail
La biblioteca de procesamiento de CloudTrail es una biblioteca Java que ofrece una forma sencilla de procesar los registros de AWS CloudTrail. Proporcione los detalles de configuración de la cola de SQS de CloudTrail y escriba código para procesar eventos. La biblioteca de procesamiento de CloudTrail se ocupa del resto. Sondea la cola de Amazon SQS, lee y analiza los mensajes de la cola, descarga archivos de registro de CloudTrail, analiza los eventos de los archivos de registros y pasa los eventos a su código como objetos Java.
La biblioteca de procesamiento de CloudTrail es altamente escalable y tolerante a errores. Se ocupa del procesamiento paralelo de archivos de registro, de modo que pueden procesarse tantos registros como sea necesario. Gestiona los errores de red relacionados con tiempos de espera y recursos inaccesibles.
El siguiente tema muestra cómo utilizar la biblioteca de procesamiento de CloudTrail para procesar registros de CloudTrail en los proyectos Java.
La biblioteca se suministra como un proyecto de código abierto con licencia de Apache y está disponible en GitHub: https://github.com/aws/aws-cloudtrail-processing-library
Requisitos mínimos
Para utilizar la biblioteca de procesamiento de CloudTrail, debe disponer de lo siguiente:
Procesamiento de registros de CloudTrail
Procesar registros de CloudTrail en la aplicación de Java:
Agregar la biblioteca de procesamiento de CloudTrail al proyecto
Para utilizar la biblioteca de procesamiento de CloudTrail, debe agregarla a la variable classpath del proyecto de Java.
Contenido
Agregar la biblioteca a un proyecto Apache Ant
Agregar la biblioteca de procesamiento de CloudTrail a un proyecto Apache Ant
-
Descargue o clone el código fuente de la biblioteca de procesamiento de CloudTrail desde GitHub:
-
Cree el archivo .jar desde la fuente tal y como se describe en README (LÉAME)
: mvn clean install -Dgpg.skip=true
-
Copie el archivo resultante .jar en el proyecto y añádalo al archivo
build.xml
del proyecto. Por ejemplo:<classpath> <pathelement path="${classpath}"/> <pathelement location="lib/aws-cloudtrail-processing-library-1.6.1.jar"/> </classpath>
Agregar la biblioteca a un proyecto Apache Maven
La biblioteca de procesamiento de CloudTrail está disponible para Apache Mavenpom.xml
de proyectos.
Agregar la biblioteca de procesamiento de CloudTrail a un proyecto Maven
-
Abra su archivo
pom.xml
de proyecto Maven y añada la siguiente dependencia:<dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-cloudtrail-processing-library</artifactId> <version>1.6.1</version> </dependency>
Agregar la biblioteca a un proyecto Eclipse
Agregar la biblioteca de procesamiento de CloudTrail a un proyecto Eclipse
-
Descargue o clone el código fuente de la biblioteca de procesamiento de CloudTrail desde GitHub:
-
Cree el archivo .jar desde la fuente tal y como se describe en README (LÉAME)
: mvn clean install -Dgpg.skip=true
-
Copie el archivo compilado aws-cloudtrail-processing-library-1.6.1.jar en un directorio del proyecto (por lo general,
lib
). -
Haga clic con el nombre de su proyecto Project Explorer de Eclipse, elija Build Path y, a continuación, elija Configure
-
En la ventana Java Build Path, elija la pestaña Libraries.
-
Seleccione Agregar archivos JAR… y vaya a la ruta donde copió aws-cloudtrail-processing-library-1.6.1.jar.
-
Elija OK para completar la adición de la
.jar
a su proyecto.
Agregar la biblioteca a un proyecto IntelliJ
Agregar la biblioteca de procesamiento de CloudTrail a un proyecto IntelliJ
-
Descargue o clone el código fuente de la biblioteca de procesamiento de CloudTrail desde GitHub:
-
Cree el archivo .jar desde la fuente tal y como se describe en README (LÉAME)
: mvn clean install -Dgpg.skip=true
-
En File, seleccione Project Structure.
-
Elija Modules y, a continuación, elija Dependencies.
-
Elija + JARS or Directories (+ JARS o directorios) y, a continuación, vaya a la ruta en la que hubiera creado el
aws-cloudtrail-processing-library-1.6.1.jar
. -
Elija Apply y, a continuación, elija OK para completar la adición de la
.jar
a su proyecto.
Configuración de la biblioteca de procesamiento de CloudTrail
Puede configurar la biblioteca de procesamiento de CloudTrail al crear un archivo de propiedades de classpath que se cargará en el tiempo de ejecución o mediante la creación de un objeto ClientConfiguration
y al establecer las opciones de configuración de forma manual.
Proporcionar un archivo de propiedades
Puede escribir un archivo de propiedades classpath que proporcione las opciones de configuración para la aplicación. El siguiente ejemplo muestra el archivo de opciones que puede definir:
# AWS access key. (Required) accessKey = your_access_key # AWS secret key. (Required) secretKey = your_secret_key # The SQS URL used to pull CloudTrail notification from. (Required) sqsUrl = your_sqs_queue_url # The SQS end point specific to a region. sqsRegion = us-east-1 # A period of time during which Amazon SQS prevents other consuming components # from receiving and processing that message. visibilityTimeout = 60 # The S3 region to use. s3Region = us-east-1 # Number of threads used to download S3 files in parallel. Callbacks can be # invoked from any thread. threadCount = 1 # The time allowed, in seconds, for threads to shut down after # AWSCloudTrailEventProcessingExecutor.stop() is called. If they are still # running beyond this time, they will be forcibly terminated. threadTerminationDelaySeconds = 60 # The maximum number of AWSCloudTrailClientEvents sent to a single invocation # of processEvents(). maxEventsPerEmit = 10 # Whether to include raw event information in CloudTrailDeliveryInfo. enableRawEventInfo = false # Whether to delete SQS message when the CloudTrail Processing Library is unable to process the notification. deleteMessageUponFailure = false
Se requieren los siguientes parámetros:
-
sqsUrl
: proporciona la URL para extraer las notificaciones de CloudTrail. Si no especifica este valor,AWSCloudTrailProcessingExecutor
toma unaIllegalStateException
. -
accessKey
: un identificador único para la cuenta, como AKIAIOSFODNN7EXAMPLE. -
secretKey
: un identificador único para la cuenta, como wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY.
Los parámetros accessKey
y secretKey
proporcionan sus credenciales de AWS a la biblioteca, para que esta pueda obtener acceso a AWS en su nombre.
Los valores predeterminados del resto de parámetros los establece la biblioteca. Para obtener más información, consulte la Referencia de la biblioteca de procesamiento de AWS CloudTrail.
Creación de una ClientConfiguration
En lugar de establecer opciones a través de las propiedades de classpath, puede proporcionar opciones para AWSCloudTrailProcessingExecutor
inicializando y definiendo opciones en un objeto ClientConfiguration
, como se muestra en el ejemplo siguiente:
ClientConfiguration basicConfig = new ClientConfiguration( "http://sqs.us-east-1.amazonaws.com/123456789012/queue2", new DefaultAWSCredentialsProviderChain()); basicConfig.setEnableRawEventInfo(true); basicConfig.setThreadCount(4); basicConfig.setnEventsPerEmit(20);
Implementación del procesador de eventos
Para procesar los registros de CloudTrail, debe implementar un EventsProcessor
que reciba los datos del registro de CloudTrail. A continuación se muestra una implementación de ejemplo:
public class SampleEventsProcessor implements EventsProcessor { public void process(List<CloudTrailEvent> events) { int i = 0; for (CloudTrailEvent event : events) { System.out.println(String.format("Process event %d : %s", i++, event.getEventData())); } } }
Cuando se implementa un EventsProcessor
, debe poner en práctica la devolución de llamada process()
que AWSCloudTrailProcessingExecutor
utiliza para enviarle eventos de CloudTrail. Los eventos se suministran en una lista de objetos CloudTrailClientEvent
.
El objeto CloudTrailClientEvent
proporciona un CloudTrailEvent
y CloudTrailEventMetadata
que puede utilizar para leer el evento de CloudTrail y enviar información.
Este sencillo ejemplo imprime la información de eventos para todos los eventos pasados a SampleEventsProcessor
. En su propia implementación, puede procesar registros según estime más conveniente. AWSCloudTrailProcessingExecutor
sigue enviando eventos a su EventsProcessor
siempre que tenga eventos que enviar y se siga ejecutando.
Invocación y ejecución del ejecutor de procesos
Después de escribir un EventsProcessor
y establecer los valores de configuración para la biblioteca de procesamiento de CloudTrail (ya sea en un archivo de propiedades o mediante el uso de la clase ClientConfiguration
), puede utilizar estos elementos a fin de iniciar y utilizar un AWSCloudTrailProcessingExecutor
.
Utilizar AWSCloudTrailProcessingExecutor
para procesar eventos de CloudTrail
-
Cree una instancia para el objeto
AWSCloudTrailProcessingExecutor.Builder
. El constructor deBuilder
toma un objetoEventsProcessor
y un nombre de archivo de propiedades de classpath. -
Llame al método predeterminado
build()
deBuilder
para configurar y obtener un objetoAWSCloudTrailProcessingExecutor
. -
Utilice los métodos
start()
ystop()
deAWSCloudTrailProcessingExecutor
para comenzar y finalizar el procesamiento de eventos de CloudTrail.
public class SampleApp { public static void main(String[] args) throws InterruptedException { AWSCloudTrailProcessingExecutor executor = new AWSCloudTrailProcessingExecutor.Builder(new SampleEventsProcessor(), "/myproject/cloudtrailprocessing.properties").build(); executor.start(); Thread.sleep(24 * 60 * 60 * 1000); // let it run for a while (optional) executor.stop(); // optional } }
Temas avanzados
Temas
Filtrado de los eventos que se van a procesar
De forma predeterminada, todos los registros del bucket de S3 de la cola de Amazon SQS y todos los eventos que contienen se envían al EventsProcessor
. La biblioteca de procesamiento de CloudTrail proporciona interfaces opcionales que puede implementar a fin de filtrar las fuentes que se utilizan para obtener registros de CloudTrail y filtrar los eventos que le interesa procesar.
SourceFilter
-
Puede implementar la interfaz
SourceFilter
para elegir si procesa o no los registros desde un origen que se haya proporcionado.SourceFilter
declara un método único de devolución de llamada,filterSource()
, que recibe un objetoCloudTrailSource
. Para evitar procesar eventos desde un origen, devuelvefalse
desdefilterSource()
.La biblioteca de procesamiento de CloudTrail llama al método
filterSource()
después de que esta sondea si hay registros en la cola de Amazon SQS. Esto ocurre antes de que la biblioteca comience el filtrado de eventos o el procesamiento de los registros.A continuación se muestra una implementación de ejemplo:
public class SampleSourceFilter implements SourceFilter{ private static final int MAX_RECEIVED_COUNT = 3; private static List<String> accountIDs ; static { accountIDs = new ArrayList<>(); accountIDs.add("123456789012"); accountIDs.add("234567890123"); } @Override public boolean filterSource(CloudTrailSource source) throws CallbackException { source = (SQSBasedSource) source; Map<String, String> sourceAttributes = source.getSourceAttributes(); String accountId = sourceAttributes.get( SourceAttributeKeys.ACCOUNT_ID.getAttributeKey()); String receivedCount = sourceAttributes.get( SourceAttributeKeys.APPROXIMATE_RECEIVE_COUNT.getAttributeKey()); int approximateReceivedCount = Integer.parseInt(receivedCount); return approximateReceivedCount <= MAX_RECEIVED_COUNT && accountIDs.contains(accountId); } }
Si no proporciona su propio
SourceFilter
, en ese caso se utilizaráDefaultSourceFilter
, lo que permite procesar todos los orígenes (siempre devuelvetrue
). EventFilter
-
Puede implementar la interfaz
EventFilter
para elegir si un evento de CloudTrail se envía alEventsProcessor
.EventFilter
declara un método único de devolución de llamada,filterEvent()
, que recibe un objetoCloudTrailEvent
. Para evitar que se procese el evento, devuelvefalse
desdefilterEvent()
.La biblioteca de procesamiento de CloudTrail llama al método
filterEvent()
después de que la biblioteca sondea si hay registros en la cola Amazon SQS y después del filtrado de la fuente. Esto ocurre antes de que la biblioteca comience el procesamiento de eventos de los registros.Consulte la siguiente implementación de ejemplo:
public class SampleEventFilter implements EventFilter{ private static final String EC2_EVENTS = "ec2.amazonaws.com"; @Override public boolean filterEvent(CloudTrailClientEvent clientEvent) throws CallbackException { CloudTrailEvent event = clientEvent.getEvent(); String eventSource = event.getEventSource(); String eventName = event.getEventName(); return eventSource.equals(EC2_EVENTS) && eventName.startsWith("Delete"); } }
Si no proporciona su propio
EventFilter
, en ese caso se utilizaráDefaultEventFilter
, lo que permite procesar todos los eventos (siempre devuelvetrue
).
Procesamiento de eventos de datos
Cuando CloudTrail procesa eventos de datos, conserva los números en su formato original, ya sea un entero (int
) o un float
(un número que contiene un decimal). En eventos que tienen enteros en los campos de un evento de datos, CloudTrail ha procesado históricamente estos números como flotantes. Actualmente, CloudTrail procesa números en estos campos y mantiene su formato original.
Como práctica recomendada, con el fin de evitar la interrupción de las automatizaciones, sea flexible en cualquier código o automatización que utilice para procesar o filtrar eventos de datos de CloudTrail y permita números int
y float
. Para obtener los mejores resultados, utilice la versión 1.4.0 o posterior de la biblioteca de procesamiento de CloudTrail.
En el siguiente fragmento de ejemplo se muestra un número float
, 2.0
, para el parámetro desiredCount
en el bloque ResponseParameters
de un evento de datos.
"eventName": "CreateService", "awsRegion": "us-east-1", "sourceIPAddress": "000.00.00.00", "userAgent": "console.amazonaws.com", "requestParameters": { "clientToken": "EXAMPLE", "cluster": "default", "desiredCount": 2.0 ...
En el siguiente fragmento de ejemplo se muestra un número int
, 2
, para el parámetro desiredCount
en el bloque ResponseParameters
de un evento de datos.
"eventName": "CreateService", "awsRegion": "us-east-1", "sourceIPAddress": "000.00.00.00", "userAgent": "console.amazonaws.com", "requestParameters": { "clientToken": "EXAMPLE", "cluster": "default", "desiredCount": 2 ...
Notificación del progreso
Implemente la interfaz ProgressReporter
para personalizar los informes de progreso de la biblioteca de procesamiento de CloudTrail. ProgressReporter
declara dos métodos: reportStart()
y reportEnd()
, a los que se llama al principio y al final de las siguientes operaciones:
-
Sondeo de mensajes desde Amazon SQS
-
Análisis de mensajes desde Amazon SQS
-
Procesamiento de una fuente de Amazon SQS para registros de CloudTrail
-
Eliminación de mensajes desde Amazon SQS
-
Descarga de un archivo de registros de CloudTrail
-
Procesamiento del archivo de registros de CloudTrail
Ambos métodos reciben un objeto ProgressStatus
que contiene información sobre la operación realizada. El miembro progressState
es miembro de la enumeración ProgressState
que identifica la operación actual. Este miembro puede contener información adicional en el miembro progressInfo
. Por otra parte, cualquier objeto que se devuelva desde reportStart()
se pasa a reportEnd()
, de forma que podrá proporcionar información contextualizada como, por ejemplo, el momento en que se comenzó a procesar el evento.
A continuación viene una implementación de ejemplo que proporciona información sobre cuánto tiempo tarda una operación en completarse:
public class SampleProgressReporter implements ProgressReporter { private static final Log logger = LogFactory.getLog(DefaultProgressReporter.class); @Override public Object reportStart(ProgressStatus status) { return new Date(); } @Override public void reportEnd(ProgressStatus status, Object startDate) { System.out.println(status.getProgressState().toString() + " is " + status.getProgressInfo().isSuccess() + " , and latency is " + Math.abs(((Date) startDate).getTime()-new Date().getTime()) + " milliseconds."); } }
Si no implementa su propio ProgressReporter
, en ese caso se sustituirá por DefaultExceptionHandler
, que imprime el nombre del estado que se esté ejecutando.
Gestión de errores
Con la interfaz ExceptionHandler
puede controlar de forma especial las excepciones que se produzcan durante el procesamiento de los registros. ExceptionHandler
declara un método único de devolución de llamada, handleException()
, que recibe un objeto ProcessingLibraryException
con contexto sobre la excepción que se ha producido.
Puede utilizar el método ProcessingLibraryException
de getStatus()
transferido para saber qué operación se ejecutó cuando se produjo la excepción y obtener información adicional sobre el estado de la operación. ProcessingLibraryException
se deriva de la clase Exception
estándar de Java, por lo que también puede recuperar información sobre la excepción invocando a cualquiera de los métodos de excepción.
Consulte la siguiente implementación de ejemplo:
public class SampleExceptionHandler implements ExceptionHandler{ private static final Log logger = LogFactory.getLog(DefaultProgressReporter.class); @Override public void handleException(ProcessingLibraryException exception) { ProgressStatus status = exception.getStatus(); ProgressState state = status.getProgressState(); ProgressInfo info = status.getProgressInfo(); System.err.println(String.format( "Exception. Progress State: %s. Progress Information: %s.", state, info)); } }
Si no proporciona su propio ExceptionHandler
, en ese caso se sustituirá por DefaultExceptionHandler
, que imprime un mensaje de error estándar.
nota
Si el parámetro deleteMessageUponFailure
es true
, la biblioteca de procesamiento de CloudTrail no distingue las excepciones generales de los errores de procesamiento y puede eliminar mensajes de la cola.
-
Por ejemplo, utilice la marca
SourceFilter
para filtrar los mensajes por marca de tiempo. -
Sin embargo, no tiene los permisos necesarios para acceder al bucket de S3 que recibe los archivos de registros de CloudTrail. Dado que no dispone de los permisos necesarios, se lanza un
AmazonServiceException
. La biblioteca de procesamiento de CloudTrail incluye esto en unaCallBackException
. -
DefaultExceptionHandler
registra esto como un error, pero no identifica la causa raíz, que es el hecho de que no dispone de los permisos necesarios. La biblioteca de procesamiento de CloudTrail considera esto un error de procesamiento y elimina el mensaje, aún si este incluye un archivo de registros de CloudTrail válido.
Si desea filtrar los mensajes con SourceFilter
, verifique que su ExceptionHandler
puede distinguir las excepciones de servicio de los errores de procesamiento.
Recursos adicionales
Para obtener más información sobre la biblioteca de procesamiento de CloudTrail, consulte lo siguiente:
-
El proyecto GitHub de la biblioteca de procesamiento de CloudTrail
, que incluye el código de muestra que ilustra cómo implementar una aplicación de la biblioteca de procesamiento de CloudTrail. -
Documentación del paquete Java de la biblioteca de procesamiento de CloudTrail.