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

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 :

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 :

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

<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

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.

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.

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.