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 CloudTrail de traitement est une bibliothèque Java qui fournit un moyen simple de traiter AWS CloudTrail journaux. Vous fournissez les détails de configuration de votre CloudTrail SQS file d'attente et vous écrivez du code pour traiter les événements. La bibliothèque CloudTrail de traitement s'occupe du reste. Il interroge votre SQS file d'attente Amazon, 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, procédez comme suit :

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

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.

Ajout de la bibliothèque à un projet Eclipse

Ajout de la bibliothèque à un projet IntelliJ

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 :

Les secretKey paramètres accessKey et fournissent votre AWS informations d'identification de la bibliothèque afin que celle-ci puisse 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 de plus amples informations, veuillez consulter le .AWS CloudTrail Référence de bibliothèque de traitement.

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.

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 du compartiment S3 de votre SQS file d'attente Amazon et tous les événements qu'ils contiennent sont envoyés à votreEventsProcessor. 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.

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 :

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.

Ressources supplémentaires

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