Utilisation de la bibliothèque CloudTrail de traitement - AWS CloudTrail
Configuration requise CloudTrail Journaux de traitementRubriques avancéesRessources supplémentaires

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation de la bibliothèque CloudTrail de traitement

La bibliothèque de CloudTrail traitement est une bibliothèque Java qui permet de traiter facilement AWS CloudTrail les journaux. Vous fournissez les détails de configuration de votre file d'attente CloudTrail SQS et vous écrivez du code pour traiter les événements. La bibliothèque CloudTrail de traitement s'occupe du reste. Il interroge votre file d'attente Amazon SQS, lit et analyse les messages de file d'attente, télécharge les fichiers CloudTrail journaux, analyse les événements contenus dans les fichiers journaux et transmet les événements à votre code sous forme d'objets Java.

La bibliothèque CloudTrail de traitement est hautement évolutive et tolérante aux pannes. Elle gère le traitement parallèle des fichiers journaux de telle sorte que vous puissiez traiter autant de journaux que nécessaire. Elle gère les défaillances du réseau liées aux délais de réseau et aux ressources inaccessibles.

La rubrique suivante explique comment utiliser la bibliothèque de CloudTrail traitement pour traiter CloudTrail les journaux dans vos projets Java.

La bibliothèque est fournie sous forme de projet open source sous licence Apache, disponible sur :. GitHub https://github.com/aws/aws-cloudtrail-processing-library La source de la bibliothèque contient des exemples de code que vous pouvez utiliser comme base pour vos propres projets.

Configuration requise

Pour utiliser la bibliothèque CloudTrail de traitement, vous devez disposer des éléments suivants :

CloudTrail Journaux de traitement

Pour traiter CloudTrail les journaux dans votre application Java :

  1. Ajouter la bibliothèque CloudTrail de traitement à votre projet

  2. Configuration de la bibliothèque CloudTrail de traitement

  3. Implémentation du processeur des événements

  4. Instanciation et traitement de l’exécution de traitement

Ajouter la bibliothèque CloudTrail de traitement à votre projet

Pour utiliser la bibliothèque CloudTrail de traitement, ajoutez-la au chemin de classe de votre projet Java.

Ajout de la bibliothèque à un projet Apache Ant

Pour ajouter la bibliothèque CloudTrail de traitement à un projet Apache Ant

  1. Téléchargez ou clonez le code source de la bibliothèque de CloudTrail traitement depuis GitHub :

  2. Créez le fichier .jar à partir de la source comme décrit dans la section README (LISEZ-MOI) :

    mvn clean install -Dgpg.skip=true

  3. Copiez le fichier .jar résultant dans votre projet et ajoutez-le au fichier build.xml de votre projet. Par exemple :

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

Ajout de la bibliothèque à un projet Apache Maven

La bibliothèque CloudTrail de traitement est disponible pour Apache Maven. L’ajouter à votre projet est aussi simple que d’écrire une seule dépendance dans le fichier pom.xml de votre projet.

Pour ajouter la bibliothèque CloudTrail de traitement à un projet Maven

  • Ouvrez le fichier pom.xml du projet Maven et ajoutez les dépendances suivantes :

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

Ajout de la bibliothèque à un projet Eclipse

Pour ajouter la bibliothèque CloudTrail de traitement à un projet Eclipse

  1. Téléchargez ou clonez le code source de la bibliothèque de CloudTrail traitement depuis GitHub :

  2. Créez le fichier .jar à partir de la source comme décrit dans la section README (LISEZ-MOI) :

    mvn clean install -Dgpg.skip=true

  3. Copiez le fichier aws-cloudtrail-processing-library -1.6.1.jar intégré dans un répertoire de votre projet (généralement). lib

  4. Cliquez avec le bouton droit sur le nom de votre projet dans l’Explorateur de projets Eclipse, choisissez Build Path, puis Configure

  5. Dans la fenêtre Java Build Path, cliquez sur l’onglet Libraries.

  6. Choisissez Ajouter des fichiers JAR... et naviguez jusqu'au chemin où vous avez copié aws-cloudtrail-processing-library -1.6.1.jar.

  7. Cliquez sur OK pour terminer l’ajout du fichier .jar à votre projet.

Ajout de la bibliothèque à un projet IntelliJ

Pour ajouter la bibliothèque CloudTrail de traitement à un projet IntelliJ

  1. Téléchargez ou clonez le code source de la bibliothèque de CloudTrail traitement depuis GitHub :

  2. Créez le fichier .jar à partir de la source comme décrit dans la section README (LISEZ-MOI) :

    mvn clean install -Dgpg.skip=true

  3. Dans File, choisissez Projet Structure.

  4. Choisissez Modules, puis Dependencies.

  5. Choisissez + JARS ou Répertoires, puis accédez au chemin où vous avez créé le fichier aws-cloudtrail-processing-library-1.6.1.jar.

  6. Choisissez Apply (Appliquer), puis cliquez sur OK pour terminer l’ajout du .jar à votre projet.

Configuration de la bibliothèque CloudTrail de traitement

Vous pouvez configurer la bibliothèque de CloudTrail traitement en créant un fichier de propriétés de chemin de classe chargé lors de l'exécution, ou en créant un ClientConfiguration objet et en définissant les options manuellement.

Fourniture d’un fichier de propriétés

Vous pouvez écrire un fichier de propriétés de chemin de classe qui fournit des options de configuration à votre application. L’exemple suivant montre les options que vous pouvez définir :

# 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

Les paramètres suivants sont obligatoires :

  • sqsUrl— Fournit l'URL à partir de laquelle vous pouvez extraire vos CloudTrail notifications. Si vous ne spécifiez pas cette valeur, AWSCloudTrailProcessingExecutor lève une IllegalStateException.

  • accessKey : Identifiant unique pour votre compte, comme .AKIAIOSFODNN7EXAMPLE.

  • secretKey— Un identifiant unique pour votre compte, tel que bPxRfi WJALRxUTNFEMI/K7MDENG/CYEXAMPLEKEY.

Les secretKey paramètres accessKey et fournissent vos AWS informations d'identification à la bibliothèque afin que celle-ci puisse y accéder AWS en votre nom.

Les paramètres par défaut pour les autres paramètres sont définis par la bibliothèque. Pour plus d’informations, consultez la Référence de bibliothèque de traitement AWS CloudTrail.

Création d'un ClientConfiguration

Au lieu de définir les options dans les propriétés de chemin de classe, vous pouvez fournir des options à la classe AWSCloudTrailProcessingExecutor en initialisant et en définissant des options dans un objet ClientConfiguration, comme indiqué dans l'exemple suivant :

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

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

Implémentation du processeur des événements

Pour traiter CloudTrail les journaux, vous devez implémenter un EventsProcessor système qui reçoit les données des CloudTrail journaux. Voici un exemple d’implémentation : 

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

Lorsque vous implémentez unEventsProcessor, vous implémentez le process() rappel qu'il AWSCloudTrailProcessingExecutor utilise pour vous envoyer CloudTrail des événements. Les événements sont fournis dans une liste d’objets CloudTrailClientEvent.

L'CloudTrailClientEventobjet fournit un CloudTrailEvent et CloudTrailEventMetadata que vous pouvez utiliser pour lire les informations relatives à l' CloudTrail événement et à la livraison.

Cet exemple simple imprime les informations d’événement pour chaque événement transmis à SampleEventsProcessor. Dans votre propre implémentation, vous pouvez traiter les journaux selon vos besoins. L’objet AWSCloudTrailProcessingExecutor continue à envoyer des événements à votre EventsProcessor tant que celui-ci contient des événements d’envoi et qu’il est en cours d’exécution.

Instanciation et traitement de l’exécution de traitement

Après avoir écrit EventsProcessor et défini les valeurs de configuration de la bibliothèque de CloudTrail traitement (soit dans un fichier de propriétés, soit à l'aide de la ClientConfiguration classe), vous pouvez utiliser ces éléments pour initialiser et utiliser unAWSCloudTrailProcessingExecutor.

À utiliser AWSCloudTrailProcessingExecutor pour traiter CloudTrail des événements

  1. Instanciez un objet AWSCloudTrailProcessingExecutor.Builder. Le constructeur du Builder prend un objet EventsProcessor et un nom de fichier de propriétés de chemin de classe.

  2. Appelez la méthode factory Builder de l’objet build() pour configurer et obtenir un objet AWSCloudTrailProcessingExecutor.

  3. Utilisez les AWSCloudTrailProcessingExecutor stop() méthodes start() et les méthodes pour démarrer et terminer le traitement des CloudTrail événements.

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

Rubriques avancées

Filtration des événements à traiter

Par défaut, tous les journaux contenus dans le compartiment S3 de la file d’attente Amazon SQS et tous les événements qu’ils contiennent sont envoyés à l’objet EventsProcessor. La bibliothèque de CloudTrail traitement fournit des interfaces facultatives que vous pouvez implémenter pour filtrer les sources utilisées pour obtenir les CloudTrail journaux et pour filtrer les événements que vous souhaitez traiter.

SourceFilter

Vous pouvez implémenter l’interface SourceFilter pour choisir si vous souhaitez traiter les journaux provenant d’une source fournie. SourceFilter déclare une méthode de rappel unique, filterSource(), qui reçoit un objet CloudTrailSource. Pour conserver des événements provenant d’une source en cours de traitement, renvoyez la valeur false de filterSource().

La bibliothèque CloudTrail de traitement appelle la filterSource() méthode une fois qu'elle a demandé des journaux dans la file d'attente Amazon SQS. Cet événement se produit avant que la bibliothèque commence le filtrage ou le traitement des journaux.

Voici un exemple d’implémentation :

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 vous ne fournissez pas votre propre SourceFilter, DefaultSourceFilter est alors utilisé, ce qui permet de traiter toutes les sources (renvoie toujours la valeur true).

EventFilter

Vous pouvez implémenter l'EventFilterinterface pour choisir si un CloudTrail événement est envoyé à votreEventsProcessor. EventFilterdéclare une méthode de rappel uniquefilterEvent(), qui reçoit un CloudTrailEvent objet. Pour empêcher le traitement de l’événement, renvoyez la valeur false à partir de la méthode filterEvent().

La bibliothèque CloudTrail de traitement appelle la filterEvent() méthode après avoir demandé des journaux dans la file d'attente Amazon SQS et après le filtrage des sources. Cet événement se produit avant que la bibliothèque commence le traitement des journaux.

Voir l’exemple d’implémentation suivant :

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 vous ne fournissez pas votre propre EventFilter, DefaultEventFilter est alors utilisé, ce qui permet de traiter tous les événements (renvoie toujours la valeur true).

Traitement des événements de données

Lors du CloudTrail traitement des événements de données, il conserve les nombres dans leur format d'origine, qu'il s'agisse d'un entier (int) ou d'un float (un nombre contenant une décimale). Dans les événements contenant des nombres entiers dans les champs d'un événement de données, ces nombres CloudTrail étaient traditionnellement traités comme des nombres flottants. Actuellement, CloudTrail traite les numéros dans ces champs en conservant leur format d'origine.

Pour éviter de perturber vos automatisations, faites preuve de flexibilité dans le code ou l'automatisation que vous utilisez pour traiter ou filtrer les événements liés aux CloudTrail données, et autorisez les deux int et les nombres float formatés. Pour de meilleurs résultats, utilisez la version 1.4.0 ou supérieure de la bibliothèque de CloudTrail traitement.

L’exemple d’extrait suivant montre un numéro formaté float, 2.0, pour le paramètre desiredCount dans le bloc ResponseParameters d’un événement de données.

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

L'exemple d'extrait suivant montre un numéro formaté int, 2, pour le paramètre desiredCount dans le bloc ResponseParameters d'un événement de données.

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

Rapports d’avancement

Implémentez l'ProgressReporterinterface pour personnaliser les rapports sur la progression de la bibliothèque de CloudTrail traitement. ProgressReporterdéclare deux méthodes : reportStart() etreportEnd(), qui sont appelées au début et à la fin des opérations suivantes :

  • Interrogation des messages provenant d’Amazon SQS

  • Analyse des messages provenant d’Amazon SQS

  • Traitement d'une source Amazon SQS pour les journaux CloudTrail

  • Suppression des messages provenant d’Amazon SQS

  • Téléchargement d'un fichier CloudTrail journal

  • Traitement d'un fichier CloudTrail journal

Ces deux méthodes reçoivent un objet ProgressStatus qui contient des informations sur l’opération exécutée. Le membre progressState contient un membre de l'énumération ProgressState qui identifie l’opération en cours. Ce membre peut contenir des informations supplémentaires dans le membre progressInfo. En outre, tout objet que vous renvoyez à partir de reportStart() est transmis à reportEnd(), de sorte que vous puissiez fournir des informations contextuelles, telles que l'heure de début du traitement de l'événement.

Voici un exemple d'implémentation qui fournit des informations concernant la durée d'une opération :

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 vous n'implémentez pas votre propre interface ProgressReporter, l'objet DefaultExceptionHandler, qui affiche le nom de l'état en cours d'exécution, est utilisé à la place.

Gestion des erreurs

L'interface ExceptionHandler vous permet de fournir un traitement spécial lorsqu'une exception se produit pendant le traitement des journaux. ExceptionHandler déclare une méthode de rappel unique, handleException(), qui reçoit un objet ProcessingLibraryException avec un contexte concernant l'exception qui s'est produite.

Vous pouvez utiliser la méthode getStatus() de l'objet ProcessingLibraryException transmis pour découvrir l'opération qui était en cours d'exécution lorsque l'exception s'est produite et obtenir des informations supplémentaires sur l'état de l'opération. L'objet ProcessingLibraryException est dérivé de la classe Exception standard de Java ; vous pouvez donc également récupérer des informations sur l'exception en appelant l'une des méthodes d'exception.

Voir l'exemple d'implémentation suivant :

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 vous ne fournissez pas votre propre interface ExceptionHandler, l'objet DefaultExceptionHandler, qui affiche un message d'erreur standard, sera utilisé à la place.

Note

Si le deleteMessageUponFailure paramètre est défini comme teltrue, la bibliothèque de CloudTrail traitement ne fait pas la distinction entre les exceptions générales et les erreurs de traitement et peut supprimer les messages de file d'attente.

  1. Vous utilisez par exemple le SourceFilter pour filtrer les messages par horodatage.

  2. Toutefois, vous ne disposez pas des autorisations requises pour accéder au compartiment S3 qui reçoit les fichiers CloudTrail journaux. Etant donné que vous n'avez pas les autorisations requises, une AmazonServiceException est renvoyée. La bibliothèque CloudTrail de traitement l'intègre dans un CallBackException fichier.

  3. L'objet DefaultExceptionHandler journalise cela comme une erreur, mais ne permet pas d'identifier la cause première, à savoir que vous n'avez pas les autorisations requises. La bibliothèque CloudTrail de traitement considère qu'il s'agit d'une erreur de traitement et supprime le message, même s'il contient un fichier CloudTrail journal valide.

Si vous souhaitez filtrer les messages avec SourceFilter, vérifiez que votre service ExceptionHandler peut faire la distinction entre les exceptions et les erreurs de traitement.

Ressources supplémentaires

Pour plus d'informations sur la bibliothèque CloudTrail de traitement, consultez les rubriques suivantes :