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á.

Como usar a biblioteca de processamento do CloudTrail

A Biblioteca de processamento do CloudTrail é uma biblioteca Java que fornece uma maneira simples de processar logs do AWS CloudTrail. Forneça detalhes de configuração sobre a sua fila do SQS do CloudTrail e escreva o código para processar eventos. A Biblioteca de Processamento do CloudTrail cuida do resto. Ela consulta a sua fila do Amazon SQS, lê e analisa as mensagens da fila, faz downloads de arquivos de log do CloudTrail, analisa eventos nos arquivos de log e passa os eventos para o seu código como objetos Java.

A Biblioteca de Processamento do CloudTrail é altamente escalável e tolerante a falhas. Ela lida com processamento paralelo de arquivos de log para que você possa processar quantos logs precisar. Ela lida com falhas de rede relacionadas a limites de tempo da rede e recursos inacessíveis.

O tópico a seguir mostra como usar a Biblioteca de Processamento do CloudTrail para processar logs do CloudTrail em seus projetos Java.

A biblioteca é fornecida como um projeto de código aberto licenciado para Apache, disponível no GitHub: https://github.com/aws/aws-cloudtrail-processing-library. O código-fonte da biblioteca inclui código de exemplo que você pode usar como base para os seus próprios projetos.

Requisitos mínimos

Para usar a Biblioteca de Processamento do CloudTrail, é necessário ter o seguinte:

Processamento de logs do CloudTrail

Para processar logs do CloudTrail na sua aplicação Java:

Adicionar a Biblioteca de Processamento do CloudTrail ao seu projeto

Para usar a Biblioteca de Processamento do CloudTrail, adicione-a ao classpath do seu projeto Java.

Adicionar a biblioteca a um projeto Apache Ant

Adicionar a biblioteca a um projeto Apache Maven

A Biblioteca de Processamento do CloudTrail está disponível para o Apache Maven. Você pode adicioná-la ao seu projeto escrevendo uma única dependência no arquivo pom.xml do seu projeto.

Adicionar a biblioteca a um projeto Eclipse

Adicionar a biblioteca a um projeto IntelliJ

Configurar a Biblioteca de Processamento do CloudTrail

É possível configurar a Biblioteca de Processamento do CloudTrail ao criar um arquivo de propriedades de caminho de classe que é carregado em runtime ou ao criar um objeto ClientConfiguration e definir as opções manualmente.

Fornecer um arquivo de propriedades

Você pode criar um arquivo de propriedades classpath que fornece opções de configuração ao seu aplicativo. O seguinte exemplo de arquivo mostra as opções que você pode 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

Os seguintes parâmetros são obrigatórios:

Os parâmetros accessKey e secretKey fornecem as suas credenciais AWS para a biblioteca, permitindo que ela acesse AWS em seu nome.

O padrão para os outros parâmetros são definidos pela biblioteca. Para obter mais informações, consulte a Referência da Biblioteca de Processamento do AWS CloudTrail.

Criar uma ClientConfiguration

Em vez de definir opções nas propriedades do classpath, você pode fornecer opções ao AWSCloudTrailProcessingExecutor inicializando e definindo opções em um objeto ClientConfiguration, como mostra este exemplo:

ClientConfiguration basicConfig = new ClientConfiguration(
    "http://sqs.us-east-1.amazonaws.com/123456789012/queue2",
    new DefaultAWSCredentialsProviderChain());

basicConfig.setEnableRawEventInfo(true);
basicConfig.setThreadCount(4);
basicConfig.setnEventsPerEmit(20);

Implementar o processador de eventos

Para processar logs do CloudTrail, é necessário implementar um EventsProcessor que recebe os dados de log do CloudTrail. Este é um exemplo de nome de implementação:

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()));
        }
    }
}

Ao implementar um EventsProcessor, você implementa o retorno de chamada process() que AWSCloudTrailProcessingExecutor usa para enviar eventos do CloudTrail para você. Os eventos são fornecidos em uma lista de objetos CloudTrailClientEvent.

O objeto CloudTrailClientEvent fornece CloudTrailEvent e CloudTrailEventMetadata que você pode usar para ler o evento do CloudTrail e as informações de fornecimento.

Esse exemplo simples imprime as informações de cada evento transmitido ao SampleEventsProcessor. Em sua própria implementação, você pode processar logs de acordo com a sua necessidade. O AWSCloudTrailProcessingExecutor continua enviando eventos ao seu EventsProcessor, desde que tenha eventos para enviar e ainda esteja em execução.

Instalar e executar o executor de processamento

Depois de criar um EventsProcessor e definir os valores de configuração para a Biblioteca de Processamento do CloudTrail (em um arquivo de propriedades ou usando a classe ClientConfiguration), você poderá usar esses elementos para inicializar e usar um AWSCloudTrailProcessingExecutor.

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
  }
}

Tópicos avançados

Filtrar os eventos a serem processados

Por padrão, todos os logs no bucket do S3 da sua fila do Amazon SQS e todos os eventos que eles contêm são enviados para o EventsProcessor. A Biblioteca de Processamento do CloudTrail fornece interfaces opcionais que você pode implementar para filtrar as origens usadas para obter os logs do CloudTrail e para filtrar os eventos que você tem interesse em processar.

Processar eventos de dados

Quando o CloudTrail processa eventos de dados, ele preserva os números em seu formato original, seja ele um inteiro (int) ou um float (um número que contém um decimal). Em eventos que têm inteiros nos campos de um evento de dados, o CloudTrail processou historicamente esses números como floats. Atualmente, o CloudTrail processa números nesses campos mantendo seu formato original.

Como prática recomendada, para evitar quebrar suas automações, seja flexível em qualquer código ou automação que você esteja usando para processar ou filtrar eventos de dados do CloudTrail e permita os números int e float formatados. Para obter melhores resultados, use a versão 1.4.0 ou superior da Biblioteca de Processamento do CloudTrail.

O snippet de exemplo a seguir mostra um número formatado float (2.0) para o parâmetro desiredCount no bloco de evento de dados ResponseParameters.

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2.0
...

O snippet de exemplo a seguir mostra um número formatado int (2) para o parâmetro desiredCount no bloco de evento de dados ResponseParameters.

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2
...

Informar o progresso

Implemente a interface ProgressReporter para personalizar os relatórios de progresso da Biblioteca de Processamento do CloudTrail. O ProgressReporter declara dois métodos: reportStart() e reportEnd(), que são chamados no início e no fim das seguintes operações:

Os dois métodos recebem um objeto ProgressStatus que contém informações sobre a operação executada. O membro progressState contém um membro da enumeração ProgressState que identifica a operação atual. Esse membro pode conter informações adicionais no membro progressInfo. Além disso, qualquer objeto que você retornar de reportStart() será transmitido para reportEnd(), a fim de que você possa fornecer informações contextuais, como o horário em que o evento começou a ser processado.

Veja a seguir um exemplo de implementação que fornece informações sobre quanto tempo uma operação levou para ser concluída:

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.");
  }
}

Se você não implementar seu próprio ProgressReporter, DefaultExceptionHandler, que imprime o nome do estado que está em execução, será usado.

Tratamento de erros

A interface ExceptionHandler permite que você dê um tratamento especial quando ocorre uma exceção durante o processamento de log. ExceptionHandler declara um único método de retorno de chamada, handleException(), que recebe um objeto ProcessingLibraryException com contexto sobre a exceção que ocorreu.

Você pode usar o método de ProcessingLibraryException, getStatus(), transferido para descobrir qual operação foi executada quando a exceção ocorreu e obter informações adicionais sobre o status da operação. ProcessingLibraryException deriva-se da classe padrão Exception de Java, portanto, você também pode recuperar informações sobre a exceção chamando qualquer um dos métodos de exceção.

Veja este exemplo de implementação:

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));
  }
}

Se você não fornecer seu próprio ExceptionHandler, DefaultExceptionHandler, que imprime uma mensagem de erro padrão, será usado.

Recursos adicionais

Para obter mais informações sobre a Biblioteca de Processamento do CloudTrail, consulte: