Kit AWS X-Ray SDK pour Java - AWS X-Ray
Sous-modulesPrérequisGestion des dépendancesSurveillance

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.

Kit AWS X-Ray SDK pour Java

The X-Ray SDK for Java est un ensemble de bibliothèques pour les applications Web Java qui fournissent des classes et des méthodes permettant de générer et d'envoyer des données de trace au daemon X-Ray. Les données de suivi incluent des informations sur les HTTP demandes entrantes traitées par l'application et les appels que l'application passe aux services en aval à l' AWS SDKaide des HTTP clients ou d'un connecteur SQL de base de données. Vous pouvez également créer des segments manuellement et ajouter des informations de débogage dans les annotations et les métadonnées.

The X-Ray SDK for Java est un projet open source. Vous pouvez suivre le projet et soumettre des problèmes et des pull requests sur GitHub : github.com/aws/ aws-xray-sdk-java

Commencez par ajouter AWSXRayServletFilter en tant que filtre servlet pour suivre les demandes entrantes. Un filtre de servlet crée un segment. Lorsque le segment est ouvert, vous pouvez utiliser les méthodes du SDK client pour ajouter des informations au segment et créer des sous-segments afin de suivre les appels en aval. Il enregistre SDK également automatiquement les exceptions générées par votre application lorsque le segment est ouvert.

À partir de la version 1.3, vous pouvez instrumenter votre application à l'aide de la programmation orientée aspect (AOP) dans Spring. Cela signifie que vous pouvez instrumenter votre application pendant qu'elle est en cours d'exécution AWS, sans ajouter de code au runtime de votre application.

Utilisez ensuite X-Ray SDK pour Java pour instrumenter vos AWS SDK for Java clients en incluant le sous-module SDK Instrumentor dans votre configuration de compilation. Chaque fois que vous appelez une ressource Service AWS ou une ressource en aval avec un client instrumenté, les informations relatives à l'appel sont SDK enregistrées dans un sous-segment. Services AWS et les ressources auxquelles vous accédez au sein des services apparaissent sous forme de nœuds en aval sur la carte de trace pour vous aider à identifier les erreurs et les problèmes de limitation sur les connexions individuelles.

Si vous ne souhaitez pas instrumenter tous les appels en aval Services AWS, vous pouvez omettre le sous-module Instrumentor et choisir les clients à instrumenter. Instrumentez les clients individuels en ajoutant un TracingHandler à un client AWS SDK de service.

D'autres sous-modules SDK de X-Ray for Java fournissent des instruments pour les appels en aval vers le HTTP Web APIs et les SQL bases de données. Vous pouvez utiliser les versions X-Ray SDK pour Java de HTTPClient et HTTPClientBuilder dans le HTTP sous-module Apache pour instrumenter les HTTP clients Apache. Pour instrumenter SQL les requêtes, ajoutez SDK l'intercepteur à votre source de données.

Après avoir commencé à utiliser leSDK, personnalisez son comportement en configurant l'enregistreur et le filtre de servlet. Vous pouvez ajouter des plug-ins pour enregistrer les données relatives aux ressources de calcul qui exécutent votre application, personnaliser le comportement d'échantillonnage en définissant des règles d'échantillonnage et définir le niveau de journalisation pour voir plus ou moins d'informations contenues SDK dans les journaux de votre application.

Enregistrez les informations supplémentaires sur les demandes et le travail que votre application effectue dans les annotations et les métadonnées. Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les expressions de filtre, de telle sorte que vous pouvez explorer les suivis qui contiennent des données spécifiques. Les entrées de métadonnées sont moins restrictives et peuvent enregistrer des objets et des tableaux entiers, c'est-à-dire tout ce qui peut être sérialisé. JSON

Annotations et métadonnées

Les annotations et les métadonnées sont du texte arbitraire que vous ajoutez aux segments avec le X-RaySDK. Les annotations sont indexées pour être utilisées avec les expressions de filtre. Les métadonnées ne sont pas indexées, mais peuvent être consultées dans le segment brut à l'aide de la console X-Ray ouAPI. Toute personne à qui vous accordez un accès en lecture à X-Ray peut consulter ces données.

Lorsque vous avez un grand nombre de clients instrumentés dans votre code, un seul segment de demande peut contenir un grand nombre de sous-segments, un par appel effectué à l'aide d'un client instrumenté. Vous pouvez organiser et grouper les sous-segments en enveloppant les appels clients dans des sous-segments personnalisés. Vous pouvez créer un sous-segment personnalisé pour une fonction complète ou une quelconque section du code, puis enregistrer les métadonnées et les annotations sur le sous-segment au lieu de tout écrire sur le segment parent.

Sous-modules

Vous pouvez télécharger le X-Ray SDK pour Java sur Maven. The X-Ray SDK for Java est divisé en sous-modules par cas d'utilisation, avec une nomenclature pour la gestion des versions :

Si vous utilisez Maven ou Gradle pour créer votre application, ajoutez X-Ray SDK for Java à votre configuration de compilation.

Pour la documentation de référence sur SDK les classes et méthodes, consultez AWS X-Ray SDKJava API Reference.

Prérequis

The X-Ray SDK pour Java nécessite Java 8 ou version ultérieure, Servlet API 3 AWS SDK, et Jackson.

SDKCela dépend des bibliothèques suivantes lors de la compilation et de l'exécution :

  • AWS SDKpour Java version 1.11.398 ou ultérieure

  • Servlet 3.1.0 API

Ces dépendances sont déclarées dans le SDK pom.xml fichier et sont incluses automatiquement si vous créez à l'aide de Maven ou Gradle.

Si vous utilisez une bibliothèque incluse dans X-Ray SDK pour Java, vous devez utiliser la version incluse. Par exemple, si vous dépendez déjà de Jackson au moment de l'exécution et que vous incluez des JAR fichiers dans votre déploiement pour cette dépendance, vous devez supprimer ces JAR fichiers car ils SDK JAR incluent leurs propres versions des bibliothèques Jackson.

Gestion des dépendances

The X-Ray SDK pour Java est disponible auprès de Maven :

  • Groupe — com.amazonaws

  • Artifact — aws-xray-recorder-sdk-bom

  • Version – 2.11.0

Si vous utilisez Maven pour créer votre application, ajoutez-la en SDK tant que dépendance dans votre pom.xml fichier.

Exemple pom.xml - dépendances
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.11.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-apache-http</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
  </dependency>
</dependencies>

Pour Gradle, ajoutez le SDK en tant que dépendance au moment de la compilation dans votre fichier. build.gradle

Exemple build.gradle - dépendances
dependencies {
  compile("org.springframework.boot:spring-boot-starter-web")
  testCompile("org.springframework.boot:spring-boot-starter-test")
  compile("com.amazonaws:aws-java-sdk-dynamodb")
  compile("com.amazonaws:aws-xray-recorder-sdk-core")
  compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk")
  compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor")
  compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
  compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
  compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
  testCompile("junit:junit:4.11")
}
dependencyManagement {
    imports {
        mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
        mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
    }
}

Si vous utilisez Elastic Beanstalk pour déployer votre application, vous pouvez utiliser Maven ou Gradle pour créer sur instance chaque fois que vous déployez, au lieu de créer et de télécharger une archive volumineuse contenant toutes vos dépendances. Consultez l' exemple d'application pour obtenir un exemple utilisant Gradle.

AWS X-Ray métriques pour X-Ray SDK pour Java

Cette rubrique décrit l'espace de AWS X-Ray noms, les métriques et les dimensions. Vous pouvez utiliser X-Ray SDK pour Java pour publier des CloudWatch métriques Amazon non échantillonnées à partir des segments X-Ray que vous avez collectés. Ces métriques sont dérivées de l'heure de début et de fin du segment, ainsi que des indicateurs d'erreur, de défaillance et d'état de limitation. Utilisez ces métriques de suivi pour exposer les nouvelles tentatives et les problèmes de dépendance dans les sous-segments.

CloudWatch est un référentiel de métriques. Une métrique est le concept fondamental CloudWatch et représente un ensemble de points de données triés dans le temps. Vous publiez (ou Services AWS) publiez des points de données métriques dans CloudWatch lesquels vous extrayez des statistiques sous la forme d'un ensemble ordonné de séries chronologiques.

Les métriques sont uniquement définies par un nom, un espace de noms et une ou plusieurs dimensions. Chaque point de données comporte un horodatage et, le cas échéant, une unité de mesure. Lorsque vous demandez des statistiques, le flux de données renvoyé est identifié par l'espace de noms, le nom de la métrique et la dimension.

Pour plus d'informations CloudWatch, consultez le guide de CloudWatch l'utilisateur Amazon.

CloudWatch Métriques X-Ray

L'espace de noms ServiceMetrics/SDK inclut les métriques suivantes.

Métrique Statistiques disponibles Description Unités

Latency

Moyenne, Minimum, Maximum, Nombre

Différence entre l'heure de début et de fin. Moyenne, minimale et maximale décrivent tous une latence de fonctionnement. Count décrit le nombre d'appels.

Millisecondes

ErrorRate

Average, Sum

Taux de demandes qui ont échoué avec un code d'état 4xx Client Error, entraînant une erreur.

Pourcentage

FaultRate

Average, Sum

Taux de traces qui ont échoué avec un code d'état 5xx Server Error, entraînant une erreur.

Pourcentage

ThrottleRate

Average, Sum

Le taux de traces limitées qui renvoient un code d'état 429. Il s'agit d'un sous-ensemble de la métrique ErrorRate.

Pourcentage

OkRate

Average, Sum

Taux de demandes suivies entraînant un code d'état OK.

Pourcentage

CloudWatch Dimensions du X-Ray

Utilisez les dimensions du tableau suivant pour affiner les mesures renvoyées pour vos Java applications instrumentées X-Ray.

Dimension Description

ServiceType

Type du service, par exemple, AWS::EC2::Instance ou NONE, s'il n'est pas connu.

ServiceName

Nom canonique du service.

Activez les CloudWatch métriques X-Ray

Utilisez la procédure suivante pour activer les métriques de suivi dans votre Java application instrumentée.

Pour configurer les métriques de suivi

  1. Ajoutez le aws-xray-recorder-sdk-metrics package en tant que Apache Maven dépendance. Pour plus d'informations, consultez la section Sous-modules X-Ray SDK for Java.

  2. Activez un nouveau dans le MetricsSegmentListener() comme partie intégrante de la construction de l'enregistreur global.

    Exemple src/com/myapp/web/Startup.java
    import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
                                        .standard()
                                        .withPlugin(new EC2Plugin())
                                        .withPlugin(new ElasticBeanstalkPlugin())
                                        .withSegmentListener(new MetricsSegmentListener());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

  3. Déployez l' CloudWatch agent pour collecter des métriques à l'aide d'Amazon Elastic Compute Cloud (AmazonEC2), d'Amazon Elastic Container Service (AmazonECS) ou d'Amazon Elastic Kubernetes Service (Amazon) : EKS

  4. Configurez le SDK pour communiquer avec l' CloudWatch agent. Par défaut, il SDK communique avec l' CloudWatch agent sur l'adresse127.0.0.1. Vous pouvez configurer d'autres adresses en définissant la variable d'environnement ou la propriété Java sur address:port.

    Exemple Variable d'environnement
    AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
    Exemple Propriété Java
    com.amazonaws.xray.metrics.daemonAddress=address:port
Pour valider la configuration

  1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse https://console.aws.amazon.com/cloudwatch/.

  2. Ouvrez l'onglet Métriques pour observer le flot de vos métriques.

  3. (Facultatif) Dans la CloudWatch console, sous l'onglet Journaux, ouvrez le groupe de ServiceMetricsSDK journaux. Recherchez un flux de journal correspondant aux métriques de l'hôte et confirmez les messages de journal.