Utilizzo della libreria CloudTrail di elaborazione - AWS CloudTrail
Requisiti minimiRegistri di elaborazione CloudTrail Argomenti avanzatiRisorse aggiuntive

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo della libreria CloudTrail di elaborazione

La CloudTrail Processing Library è una libreria Java che fornisce un modo semplice per elaborare AWS CloudTrail i log. Fornisci dettagli di configurazione sulla CloudTrail SQS coda e scrivi codice per elaborare gli eventi. La CloudTrail Processing Library fa il resto. Esamina la tua SQS coda Amazon, legge e analizza i messaggi in coda, scarica i file di CloudTrail registro, analizza gli eventi nei file di registro e passa gli eventi al tuo codice come oggetti Java.

La CloudTrail Processing Library è altamente scalabile e tollerante ai guasti. Gestisce l'elaborazione parallela dei file di log in modo da consentirti di elaborare qualsiasi numero di log in base alle tue specifiche esigenze. Gestisce inoltre gli errori di rete correlati a timeout di rete e risorse non accessibili.

L'argomento seguente mostra come utilizzare la CloudTrail Processing Library per elaborare i CloudTrail log nei progetti Java.

La libreria viene fornita come progetto open source con licenza Apache, disponibile su:. GitHub https://github.com/aws/aws-cloudtrail-processing-library La libreria include il codice di esempio che puoi utilizzare come base per i tuoi progetti.

Requisiti minimi

Per utilizzare la CloudTrail Processing Library, è necessario disporre di quanto segue:

Registri di elaborazione CloudTrail

Per elaborare CloudTrail i log nell'applicazione Java:

  1. Aggiungere la CloudTrail Processing Library al progetto

  2. Configurazione della libreria di elaborazione CloudTrail

  3. Implementazione del processore di eventi

  4. Creazione di un'istanza ed esecuzione dell'executor di elaborazione

Aggiungere la CloudTrail Processing Library al progetto

Per utilizzare la CloudTrail Processing Library, aggiungila al classpath del tuo progetto Java.

Aggiunta della libreria a un progetto Apache Ant

Per aggiungere la CloudTrail Processing Library a un progetto Apache Ant

  1. Scarica o clona il codice sorgente della CloudTrail Processing Library da: GitHub

  2. Crea il file.jar dal codice sorgente come descritto in: README

    mvn clean install -Dgpg.skip=true

  3. Copiare il file con estensione .jar risultante nel progetto e aggiungerlo al file build.xml del progetto. Per esempio:

    
<classpath>
  <pathelement path="${classpath}"/>
  <pathelement location="lib/aws-cloudtrail-processing-library-1.6.1.jar"/>
</classpath>

Aggiunta della libreria a un progetto Apache Maven

La CloudTrail Processing Library è disponibile per Apache Maven. È possibile aggiungerla al progetto scrivendo un'unica dipendenza nel file pom.xml del progetto.

Per aggiungere la CloudTrail Processing Library a un progetto Maven

  • Aprire il file pom.xml del progetto Maven e aggiungere la seguente dipendenza:

    
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-cloudtrail-processing-library</artifactId>
    <version>1.6.1</version>
</dependency>

Aggiunta della libreria a un progetto Eclipse

Per aggiungere la CloudTrail Processing Library a un progetto Eclipse

  1. Scarica o clona il codice sorgente della CloudTrail Processing Library da: GitHub

  2. Crea il file.jar dal codice sorgente come descritto in: README

    mvn clean install -Dgpg.skip=true

  3. Copia il aws-cloudtrail-processing-library -1.6.1.jar creato in una directory del tuo progetto (in genere). lib

  4. Fare clic con il pulsante destro del mouse sul nome del progetto nella finestra Project Explorer (Explorer progetti) di Eclipse, scegliere Build Path (Percorso di compilazione) e quindi scegliere Configure (Configura).

  5. Nella finestra Java Build Path (Percorso di compilazione Java) scegliere la scheda Libraries (Librerie).

  6. Scegli Aggiungi... JARs e vai al percorso in cui hai copiato aws-cloudtrail-processing-library -1.6.1.jar.

  7. Scegliere OK per completare l'aggiunta del file .jar al progetto.

Aggiunta della libreria a un progetto IntelliJ

Per aggiungere la CloudTrail Processing Library a un progetto IntelliJ

  1. Scarica o clona il codice sorgente della CloudTrail Processing Library da: GitHub

  2. Crea il file.jar dal codice sorgente come descritto in: README

    mvn clean install -Dgpg.skip=true

  3. In File, scegliere Project Structure (Struttura progetto).

  4. Scegliere Modules (Moduli), quindi Dependencies (Dipendenze).

  5. Scegli + JARS o Directories e poi vai al percorso in cui hai creato il. aws-cloudtrail-processing-library-1.6.1.jar

  6. Scegliere Apply (Applica) e quindi OK per completare l'aggiunta del file .jar al progetto.

Configurazione della libreria di elaborazione CloudTrail

È possibile configurare la CloudTrail Processing Library creando un file delle proprietà del percorso di classe che viene caricato in fase di esecuzione oppure creando un ClientConfiguration oggetto e impostando le opzioni manualmente.

Specificare un file delle proprietà

Puoi scrivere un file delle proprietà del classpath per specificare le opzioni di configurazione da passare all'applicazione. Il file di esempio seguente mostra le opzioni che è possibile impostare:

# 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

I parametri seguenti sono obbligatori:

  • sqsUrl— Fornisce la fonte URL da cui estrarre le CloudTrail notifiche. Se non specifichi questo valore, AWSCloudTrailProcessingExecutor restituisce un'eccezione IllegalStateException.

  • accessKey— Un identificatore univoco per il tuo account, ad esempioAKIAIOSFODNN7EXAMPLE.

  • secretKey— Un identificatore univoco per il tuo account, ad esempio wJalr XUtnFEMI MDENG /K7/. bPxRfi CYEXAMPLEKEY

I secretKey parametri accessKey and forniscono AWS le credenziali dell'utente alla libreria, in modo che quest'ultima possa accedervi AWS per conto dell'utente.

Le impostazioni di default per gli altri parametri vengono definite dalla libreria. Per ulteriori informazioni, consulta Documentazione di riferimento della libreria di elaborazione AWS CloudTrail.

Creare un ClientConfiguration

Anziché impostare le opzioni nelle proprietà del classpath, puoi specificare le opzioni per AWSCloudTrailProcessingExecutor mediante l'inizializzazione e l'impostazione delle opzioni in un oggetto ClientConfiguration, come illustrato nel seguente esempio:

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

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

Implementazione del processore di eventi

Per elaborare CloudTrail i registri, è necessario implementare un file EventsProcessor che riceva i dati di CloudTrail registro. Di seguito è riportato un esempio di implementazione: 

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

Quando si implementa unEventsProcessor, si implementa il process() callback che AWSCloudTrailProcessingExecutor utilizza per inviarti CloudTrail eventi. Gli eventi vengono forniti in un elenco di oggetti CloudTrailClientEvent.

L'CloudTrailClientEventoggetto fornisce un CloudTrailEvent e CloudTrailEventMetadata che è possibile utilizzare per leggere le informazioni sull' CloudTrail evento e sulla consegna.

Questo semplice esempio stampa le informazioni sugli eventi per ogni evento passato a SampleEventsProcessor. Nell'ambito dell'implementazione in questione puoi elaborare i log in base alle specifiche esigenze di lavoro. L'oggetto AWSCloudTrailProcessingExecutor continua a inviare gli eventi all'oggetto EventsProcessor a condizione che disponga di eventi da inviare e che sia ancora in esecuzione.

Creazione di un'istanza ed esecuzione dell'executor di elaborazione

Dopo aver scritto EventsProcessor e impostato i valori di configurazione per la CloudTrail Processing Library (in un file di proprietà o utilizzando la ClientConfiguration classe), potete utilizzare questi elementi per inizializzare e utilizzare unAWSCloudTrailProcessingExecutor.

Da utilizzare AWSCloudTrailProcessingExecutor per elaborare eventi CloudTrail

  1. Creare un'istanza di un oggetto AWSCloudTrailProcessingExecutor.Builder. Il costruttore di Builderrichiede un oggetto EventsProcessor e un nome di file delle proprietà del classpath.

  2. Chiamare il metodo factory build() di Builder per configurare e recuperare un oggetto AWSCloudTrailProcessingExecutor.

  3. Usa i AWSCloudTrailProcessingExecutor stop() metodi start() e per iniziare e terminare CloudTrail l'elaborazione degli eventi.

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

Argomenti avanzati

Filtro degli eventi da elaborare

Per impostazione predefinita, tutti i log nel bucket S3 di Amazon SQS Queue e tutti gli eventi in essi contenuti vengono inviati al tuo. EventsProcessor La CloudTrail Processing Library fornisce interfacce opzionali che puoi implementare per filtrare le fonti utilizzate per ottenere CloudTrail i log e filtrare gli eventi che ti interessa elaborare.

SourceFilter

Puoi implementare l'interfaccia SourceFilter per scegliere se elaborare i log provenienti dall'origine specificata. SourceFilter dichiara un singolo metodo di callback, filterSource(), che riceve un oggetto CloudTrailSource. Per evitare che gli eventi provenienti da un'origine vengano elaborati, impostare la restituzione di false da filterSource().

La CloudTrail Processing Library chiama il filterSource() metodo dopo che la libreria ha richiesto i log sulla coda AmazonSQS. Ciò si verifica prima che la libreria inizi il filtraggio degli eventi o l'elaborazione dei log.

Di seguito è riportato un esempio di implementazione:

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

Se non specifichi l'interfaccia SourceFilter, viene utilizzato DefaultSourceFilter, che permette l'elaborazione di tutte le origini (restituirà sempre true).

EventFilter

Puoi implementare l'EventFilterinterfaccia per scegliere se inviare un CloudTrail evento al tuo. EventsProcessor EventFilterdichiara un singolo metodo di callbackfilterEvent(), che riceve un CloudTrailEvent oggetto. Per evitare che l'evento venga elaborato, impostare la restituzione di false da filterEvent().

La CloudTrail Processing Library chiama il filterEvent() metodo dopo che la libreria ha interrogato i log sulla SQS coda di Amazon e dopo il filtraggio dei sorgenti. Ciò si verifica prima che la libreria inizi l'elaborazione dei log.

Di seguito è riportato un esempio di implementazione:

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

Se non specifichi l'interfaccia EventFilter, viene utilizzato DefaultEventFilter, che permette l'elaborazione di tutti gli eventi (restituirà sempre true).

Elaborazione di eventi di dati

Quando CloudTrail elabora gli eventi relativi ai dati, conserva i numeri nel loro formato originale, sia esso un numero intero (int) o un (un numero che contiene un float decimale). Negli eventi che contengono numeri interi nei campi di un evento di dati, CloudTrail storicamente elaborava questi numeri come float. Attualmente, CloudTrail elabora i numeri in questi campi mantenendo il formato originale.

Come best practice, per evitare di interrompere le automazioni, sii flessibile in qualsiasi codice o automazione che utilizzi per elaborare o filtrare gli eventi CloudTrail relativi ai dati e consenti sia int i float numeri formattati che i numeri. Per ottenere risultati ottimali, utilizzate la versione 1.4.0 o successiva della Processing Library. CloudTrail

L'esempio di frammento seguente mostra un numero formattato come float,2.0, per il parametro desiredCount nel blocco ResponseParameters di un evento di dati.

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

L'esempio di frammento seguente mostra un numero formattato come int,2, per il parametro desiredCount nel blocco ResponseParameters di un evento di dati.

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

Creazione di report sull'avanzamento

Implementa l'ProgressReporterinterfaccia per personalizzare la segnalazione dei progressi della CloudTrail Processing Library. ProgressReporterdichiara due metodi: reportStart() ereportEnd(), che vengono chiamati all'inizio e alla fine delle seguenti operazioni:

  • Messaggi di sondaggio da Amazon SQS

  • Analisi dei messaggi da Amazon SQS

  • Elaborazione di un SQS codice sorgente Amazon per i CloudTrail log

  • Eliminazione di messaggi da Amazon SQS

  • Scaricamento di un CloudTrail file di registro

  • Elaborazione di un file di CloudTrail registro

Entrambi i metodi ricevono un oggetto ProgressStatus contenente le informazioni sull'operazione eseguita. Il membro progressState contiene un membro dell'enumerazione ProgressState che identifica l'operazione corrente. Questo utente può contenere ulteriori informazioni sul membro progressInfo. Inoltre, qualsiasi oggetto restituito da reportStart() viene passato a reportEnd(). In questo modo puoi fornire informazioni contestuali, ad esempio l'ora di inizio dell'elaborazione dell'evento.

Di seguito è riportata un'implementazione di esempio che fornisce informazioni sul tempo richiesto per il completamento di un'operazione:

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 non implementi l'interfaccia ProgressReporter, viene utilizzato DefaultExceptionHandler, che stampa il nome dello stato in esecuzione.

Gestione degli errori

L'interfaccia ExceptionHandler ti consente di implementare una funzionalità di gestione speciale quando si verifica un'eccezione durante l'elaborazione dei log. ExceptionHandler dichiara un singolo metodo di callback, handleException(), che riceve un oggetto ProcessingLibraryException contenente il contesto relativo all'eccezione verificata.

Puoi utilizzare il metodo getStatus() dell'oggetto ProcessingLibraryException passato per scoprire quale operazione è stata eseguita quando si è verificata l'eccezione e per recuperare ulteriori informazioni sullo stato dell'operazione. L'oggetto ProcessingLibraryException è derivato dalla classe Java standard Exception. Puoi pertanto recuperare informazioni sull'eccezione anche richiamando qualsiasi metodo dell'eccezione.

Di seguito è riportato un esempio di implementazione:

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 non specifichi l'interfaccia ExceptionHandler, viene utilizzato DefaultExceptionHandler, che stampa un messaggio di errore standard.

Nota

Se il deleteMessageUponFailure parametro ètrue, la CloudTrail Processing Library non distingue le eccezioni generali dagli errori di elaborazione e può eliminare i messaggi in coda.

  1. Ad esempio, utilizzare SourceFilter per filtrare i messaggi in base al time stamp.

  2. Tuttavia, non disponi delle autorizzazioni necessarie per accedere al bucket S3 che riceve i file di registro. CloudTrail Poiché non si dispone delle autorizzazioni necessarie, viene generata un'eccezione AmazonServiceException. La CloudTrail Processing Library lo racchiude in un. CallBackException

  3. DefaultExceptionHandler registra questa situazione come un errore, ma non ne identifica la causa, ovvero che non si dispone delle autorizzazioni necessarie. La CloudTrail Processing Library lo considera un errore di elaborazione ed elimina il messaggio, anche se il messaggio include un file di registro valido CloudTrail .

Se si desidera filtrare i messaggi con SourceFilter, verificare che ExceptionHandler sia in grado di distinguere le eccezioni del servizio dagli errori di elaborazione.

Risorse aggiuntive

Per ulteriori informazioni sulla CloudTrail Processing Library, vedere quanto segue: