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. # AWS X-Ray SDK pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Le SDK X-Ray pour 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 requêtes HTTP entrantes traitées par l'application et les appels que l'application envoie aux services en aval à l'aide du AWS SDK, des clients HTTP ou d'un connecteur de base de données SQL. Vous pouvez également créer des segments manuellement et ajouter des informations de débogage dans les annotations et les métadonnées. Le SDK X-Ray pour 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](https://github.com/aws/aws-xray-sdk-java)- xray-sdk-java Commencez par [ajouter `AWSXRayServletFilter` en tant que filtre servlet](xray-sdk-java-filters.md) pour suivre les demandes entrantes. Un filtre de servlet crée un [segment](xray-concepts.md#xray-concepts-segments). Lorsque le segment est ouvert, vous pouvez utiliser les méthodes du client du SDK pour ajouter des informations au segment et créer des sous-segments afin de suivre les appels en aval. Le kit de développement logiciel (SDK) enregistre aussi automatiquement les exceptions que votre application renvoie quand 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](xray-sdk-java-aop-spring.md). 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 le SDK X-Ray pour Java pour instrumenter AWS SDK pour Java vos clients [en incluant le sous-module SDK Instrumentor](#xray-sdk-java-dependencies) dans votre configuration de compilation. Chaque fois que vous appelez une ressource Service AWS ou une ressource en aval avec un client instrumenté, le SDK enregistre les informations relatives à l'appel 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 des clients individuels [en ajoutant un `TracingHandler`](xray-sdk-java-awssdkclients.md) à un client de service AWS SDK. D'autres sous-modules du SDK X-Ray pour Java fournissent une instrumentation pour les appels en aval aux bases de données APIs Web HTTP et SQL. Vous pouvez [utiliser le SDK X-Ray pour les versions Java `HTTPClient` de `HTTPClientBuilder`](xray-sdk-java-httpclients.md) et dans le sous-module HTTP Apache pour instrumenter les clients HTTP Apache. Pour instrumenter les requêtes SQL, [ajoutez l'intercepteur du kit de développement logiciel (SDK) à votre source de données](xray-sdk-java-sqlclients.md). Après avoir commencé à utiliser le SDK, personnalisez son comportement en [configurant l'enregistreur et le filtre de servlet](xray-sdk-java-configuration.md). Vous pouvez ajouter des plug-ins pour enregistrer les données sur les ressources de calcul exécutant votre application, personnaliser le comportement d'échantillonnage en définissant des règles d'échantillonnage et définir le niveau de journal afin d'afficher plus ou moins d'informations du kit de développement logiciel dans vos journaux d'application. Enregistrez les informations supplémentaires sur les demandes et le travail que votre application effectue dans les [annotations et les métadonnées](xray-sdk-java-segment.md). Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les [expressions de filtre](xray-console-filters.md), de telle sorte que vous pouvez explorer les suivis qui contiennent des données spécifiques. Les entrées des métadonnées sont moins restrictives et peuvent enregistrer des objets et tableaux entiers (tout ce qui peut être sérialisé en JSON). **Annotations et métadonnées** Les annotations et les métadonnées sont du texte arbitraire que vous ajoutez aux segments avec le SDK X-Ray. 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 ou de l'API X-Ray. 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](xray-sdk-java-subsegments.md). 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 SDK X-Ray pour Java depuis Maven. Le SDK X-Ray pour Java est divisé en sous-modules par cas d'utilisation, avec une nomenclature pour la gestion des versions : + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/)(obligatoire) — Fonctionnalité de base pour créer des segments et transmettre des segments. Inclut `AWSXRayServletFilter` pour instrumenter des demandes entrantes. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/)— Instrumente les appels Services AWS passés avec AWS SDK pour Java les clients en ajoutant un client de suivi en tant que gestionnaire de demandes. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/)— Instrumente les appels Services AWS effectués avec les clients AWS SDK pour Java 2.2 et versions ultérieures en ajoutant un client de suivi comme intercepteur de demandes. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/)— Avec`aws-xray-recorder-sdk-aws-sdk`, instrumente automatiquement tous les AWS SDK pour Java clients. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/)— Avec`aws-xray-recorder-sdk-aws-sdk-v2`, instrumente automatiquement tous les clients AWS SDK pour Java 2.2 et versions ultérieures. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/)— Instruments les appels HTTP sortants effectués avec les clients HTTP Apache. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/)— Fournit des intercepteurs pour les applications Spring AOP Framework. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/)— Instruments les appels sortants vers une base de données PostgreSQL effectués avec JDBC. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/)— Instruments les appels sortants vers une base de données MySQL effectués avec JDBC. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/)— Fournit une nomenclature que vous pouvez utiliser pour spécifier la version à utiliser pour tous les sous-modules. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/)— Publiez des CloudWatch statistiques Amazon non échantillonnées à partir des segments X-Ray que vous avez collectés. Si vous utilisez Maven ou Gradle pour créer votre application, [ajoutez le SDK X-Ray pour Java à](#xray-sdk-java-dependencies) votre configuration de compilation. Pour la documentation de référence sur les classes et les méthodes du SDK, consultez le manuel de référence des API du [AWS X-Ray SDK for Java](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc). ## Prérequis Le SDK X-Ray pour Java nécessite Java 8 ou version ultérieure, l'API Servlet 3, AWS le SDK et Jackson. Le kit de développement logiciel dépend des bibliothèques suivantes lors de la compilation et de l'exécution : + AWS SDK pour Java version 1.11.398 ou ultérieure + Servlet API 3.1.0 Ces dépendances sont déclarées dans le fichier `pom.xml` du kit de développement logiciel et sont incluses automatiquement si vous créez à l'aide de Maven ou Gradle. Si vous utilisez une bibliothèque incluse dans le SDK X-Ray pour Java, vous devez utiliser la version incluse. Par exemple, si vous dépendez déjà de Jackson lors de l'exécution et incluez des fichiers JAR dans votre déploiement pour cette dépendance, vous devez supprimer ces fichiers JAR, car le fichier JAR du kit SDK inclut ses propres versions des bibliothèques Jackson. ## Gestion des dépendances Le SDK X-Ray 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 le kit de développement logiciel en tant que dépendance dans votre fichier `pom.xml`. **Example pom.xml - dépendances** ``` com.amazonaws aws-xray-recorder-sdk-bom 2.11.0 pom import com.amazonaws aws-xray-recorder-sdk-core com.amazonaws aws-xray-recorder-sdk-apache-http com.amazonaws aws-xray-recorder-sdk-aws-sdk com.amazonaws aws-xray-recorder-sdk-aws-sdk-instrumentor com.amazonaws aws-xray-recorder-sdk-sql-postgres com.amazonaws aws-xray-recorder-sdk-sql-mysql ``` Pour Gradle, ajoutez le kit de développement logiciel en tant que dépendance de compilation dans votre fichier `build.gradle`. **Example 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](xray-scorekeep.md) pour obtenir un exemple utilisant Gradle. # AWS X-Ray agent d'auto-instrumentation pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). L'agent AWS X-Ray d'auto-instrumentation pour Java est une solution de traçage qui permet d'instrumenter vos applications Web Java avec un minimum d'efforts de développement. L'agent permet le suivi des applications basées sur des servlets et de toutes les demandes en aval de l'agent effectuées avec des frameworks et des bibliothèques pris en charge. Cela inclut les requêtes HTTP Apache en aval, les requêtes AWS SDK et les requêtes SQL effectuées à l'aide d'un pilote JDBC. L'agent propage le contexte X-Ray, y compris tous les segments et sous-segments actifs, entre les threads. Toutes les configurations et la polyvalence du SDK X-Ray sont toujours disponibles avec l'agent Java. Des valeurs par défaut appropriées ont été choisies pour garantir que l'agent fonctionne avec un minimum d'effort. La solution X-Ray Agent convient parfaitement aux serveurs d'applications Web Java basés sur des servlets et basés sur des requêtes/réponses. Si votre application utilise un framework asynchrone ou n'est pas correctement modélisée en tant que service de demande-réponse, vous pouvez plutôt envisager une instrumentation manuelle avec le SDK.  L'agent X-Ray est conçu à l'aide de la boîte à outils Distributed Systems Compréhension, ou DiSCo. Di SCo est un framework open source permettant de créer des agents Java utilisables dans des systèmes distribués. Bien qu'il ne soit pas nécessaire de comprendre Di SCo pour utiliser l'agent X-Ray, vous pouvez en savoir plus sur le projet en visitant sa [page d'accueil sur GitHub](https://github.com/awslabs/disco). L'agent X-Ray est également entièrement open source. Pour consulter le code source, apporter des contributions ou signaler des problèmes concernant l'agent, consultez son [référentiel sur GitHub](https://github.com/aws/aws-xray-java-agent). ## Exemple d’application L'application [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)d'échantillonnage est adaptée pour être instrumentée avec l'agent X-Ray. Cette branche ne contient aucune configuration de filtre de servlet ou d'enregistreur, car ces fonctions sont effectuées par l'agent. Pour exécuter l'application localement ou à l'aide de AWS ressources, suivez les étapes décrites dans le fichier readme de l'exemple d'application. Les instructions d'utilisation de l'exemple d'application pour générer des traces X-Ray se trouvent dans le [didacticiel de l'exemple d'application](xray-scorekeep.md). ## Prise en main Pour commencer à utiliser l'agent Java d'auto-instrumentation X-Ray dans votre propre application, procédez comme suit. 1. Exécutez le daemon X-Ray dans votre environnement. Pour de plus amples informations, veuillez consulter [AWS X-Ray daemon](xray-daemon.md). 1. Téléchargez la [dernière distribution de l'agent](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip). Décompressez l'archive et notez son emplacement dans votre système de fichiers. Son contenu doit ressembler à ce qui suit. ``` disco ├── disco-java-agent.jar └── disco-plugins     ├── aws-xray-agent-plugin.jar     ├── disco-java-agent-aws-plugin.jar     ├── disco-java-agent-sql-plugin.jar     └── disco-java-agent-web-plugin.jar ``` 1. Modifiez les arguments JVM de votre application pour inclure les éléments suivants, qui activent l'agent. Assurez-vous que l'`-javaagent`argument est placé *avant* l'`-jar`argument, le cas échéant. Le processus de modification des arguments JVM varie en fonction des outils et des frameworks que vous utilisez pour lancer votre serveur Java. Consultez la documentation de votre infrastructure de serveur pour obtenir des conseils spécifiques. ``` -javaagent://disco-java-agent.jar=pluginPath=//disco-plugins ``` 1. Pour spécifier la façon dont le nom de votre application apparaît sur la console X-Ray, définissez la variable d'`AWS_XRAY_TRACING_NAME`environnement ou la propriété `com.amazonaws.xray.strategy.tracingName` système. Si aucun nom n'est fourni, un nom par défaut est utilisé. 1. Redémarrez votre serveur ou votre conteneur. Les demandes entrantes et leurs appels en aval sont désormais tracés. Si vous ne voyez pas les résultats escomptés, consultez[Résolution des problèmes](#XRayAutoInstrumentationAgent-Troubleshooting). ## Configuration L'agent X-Ray est configuré par un fichier JSON externe fourni par l'utilisateur. Par défaut, ce fichier se trouve à la racine du chemin de classe de l'utilisateur (par exemple, dans son `resources` répertoire) nommé. `xray-agent.json` Vous pouvez configurer un emplacement personnalisé pour le fichier de configuration en définissant la propriété `com.amazonaws.xray.configFile` système sur le chemin absolu du système de fichiers de votre fichier de configuration. Un exemple de fichier de configuration est présenté ci-dessous. ``` {         "serviceName": "XRayInstrumentedService",     "contextMissingStrategy": "LOG_ERROR",     "daemonAddress": "127.0.0.1:2000",     "tracingEnabled": true,     "samplingStrategy": "CENTRAL",         "traceIdInjectionPrefix": "prefix",         "samplingRulesManifest": "/path/to/manifest",         "awsServiceHandlerManifest": "/path/to/manifest",         "awsSdkVersion": 2,         "maxStackTraceLength": 50,         "streamingThreshold": 100,         "traceIdInjection": true,         "pluginsEnabled": true,         "collectSqlQueries": false } ``` ### Spécification de configuration Le tableau suivant décrit les valeurs valides pour chaque propriété. Les noms de propriétés distinguent les majuscules des minuscules, mais pas leurs clés. Pour les propriétés qui peuvent être remplacées par des variables d'environnement et des propriétés système, l'ordre de priorité est toujours variable d'environnement, puis propriété système, puis fichier de configuration. Pour plus d'informations sur les propriétés que vous pouvez remplacer, consultez[Variables d’environnement](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars). Tous les champs sont facultatifs. | Nom de la propriété | Type | Valeurs valides | Description | Variable d'environnement | Propriété du système | Par défaut | | --- | --- | --- | --- | --- | --- | --- | | serviceName | String | Toute chaîne | Le nom de votre service instrumenté tel qu'il apparaîtra dans la console X-Ray. | AWS\$1XRAY\$1NOM\$1TRAÇAGE | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService | | contextMissingStrategy | String | LOG\$1ERROR, IGNORE\$1ERROR | L'action entreprise par l'agent lorsqu'il tente d'utiliser le contexte du segment X-Ray mais qu'aucune n'est présente. | AWS\$1XRAY\$1CONTEXTE\$1MANQUANT | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\$1ERROR | | Adresse du démon | String | Adresse IP et port formatés, ou liste d'adresses TCP et UDP | Adresse utilisée par l'agent pour communiquer avec le daemon X-Ray. | AWS\$1XRAYADRESSE DU DÉMON | Adresse com.amazonaws.xray.emitter.daemon | 127,0.0. 1:2000 | | Activé pour le traçage | Booléen | Vrai, Faux | Permet l'instrumentation par l'agent X-Ray. | AWS\$1XRAY\$1ACTIVÉ POUR LE TRAÇAGE | com.amazonaws.xray.tracingEnabled | TRUE | | Stratégie d'échantillonnage | String | CENTRAL, LOCAL, AUCUN, TOUS | Stratégie d'échantillonnage utilisée par l'agent. ALL capture toutes les demandes, NONE ne capture aucune demande. Voir les [règles d'échantillonnage](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling). | N/A | N/A | CENTRAL | | traceIdInjectionPréfixe | String | Toute chaîne | Inclut le préfixe fourni avant l'injection du trace IDs dans les logs. | N/A | N/A | Aucun (chaîne vide) | | samplingRulesManifest | String | Un chemin de fichier absolu | Chemin d'accès à un fichier de règles d'échantillonnage personnalisé à utiliser comme source des règles d'échantillonnage pour la stratégie d'échantillonnage locale ou des règles de secours pour la stratégie centrale. | N/A | N/A | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) | | awsServiceHandlerManifeste | String | Un chemin de fichier absolu | Le chemin d'accès à une liste d'autorisation de paramètres personnalisée, qui capture des informations supplémentaires provenant des clients du AWS SDK. | N/A | N/A | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) | | awsSdkVersion | Entier | 1, 2 | Version du [AWS SDK pour](https://docs.aws.amazon.com/sdk-for-java/index.html) Java que vous utilisez. Ignoré s'`awsServiceHandlerManifest`il n'est pas également défini. | N/A | N/A | 2 | | maxStackTraceLongueur | Entier | Entiers non négatifs | Nombre maximal de lignes d'une pile à enregistrer dans une trace. | N/A | N/A | 50 | | Seuil de diffusion | Entier | Entiers non négatifs | Une fois qu'au moins autant de sous-segments sont fermés, ils sont transmis au daemon pour out-of-band éviter que les segments ne soient trop volumineux. | N/A | N/A | 100 | | traceIdInjection | Booléen | Vrai, Faux | Permet l'injection d'un identifiant de trace X-Ray dans les journaux si les dépendances et la configuration décrites dans la [configuration de journalisation](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) sont également ajoutées. Sinon, ne fait rien. | N/A | N/A | TRUE | | Plugins activés | Booléen | Vrai, Faux | Active les plug-ins qui enregistrent les métadonnées relatives AWS aux environnements dans lesquels vous travaillez. Voir [plugins](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins). | N/A | N/A | TRUE | | collectSqlQueries | Booléen | Vrai, Faux | Enregistre au mieux les chaînes de requête SQL dans des sous-segments SQL. | N/A | N/A | FALSE | | Propagation du contexte | Booléen | Vrai, Faux | Propage automatiquement le contexte X-Ray entre les threads si c'est vrai. Sinon, utilise Thread Local pour stocker le contexte et une propagation manuelle entre les threads est requise. | N/A | N/A | TRUE | ### Configuration de la journalisation Le niveau de journalisation de l'agent X-Ray peut être configuré de la même manière que le SDK X-Ray pour Java. Consultez [Logging](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) pour plus d'informations sur la configuration de la journalisation avec le SDK X-Ray pour Java. ### Instrumentation manuelle Si vous souhaitez effectuer une instrumentation manuelle en plus de l'instrumentation automatique de l'agent, ajoutez le SDK X-Ray en tant que dépendance à votre projet. Notez que les filtres de servlet personnalisés du SDK mentionnés dans [Tracing Incoming Requests](xray-sdk-java-filters.md) ne sont pas compatibles avec l'agent X-Ray. **Note** Vous devez utiliser la dernière version du SDK X-Ray pour effectuer une instrumentation manuelle tout en utilisant l'agent. Si vous travaillez dans un projet Maven, ajoutez les dépendances suivantes à votre `pom.xml` fichier. ```       com.amazonaws     aws-xray-recorder-sdk-core     2.11.0      ``` Si vous travaillez dans un projet Gradle, ajoutez les dépendances suivantes à votre `build.gradle` fichier. ``` implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0' ``` Vous pouvez ajouter [des sous-segments personnalisés](xray-sdk-java-subsegments.md) en plus [des annotations, des métadonnées et des utilisateurs IDs](xray-sdk-java-segment.md) lorsque vous utilisez l'agent, comme vous le feriez avec le SDK normal. L'agent propage automatiquement le contexte entre les threads. Aucune solution de contournement pour propager le contexte ne devrait donc être nécessaire lorsque vous travaillez avec des applications multithread. ## Résolution des problèmes Comme l'agent propose une instrumentation entièrement automatique, il peut être difficile d'identifier la cause première d'un problème lorsque vous rencontrez des problèmes. Si l'agent X-Ray ne fonctionne pas comme prévu, passez en revue les problèmes et solutions suivants. L'agent X-Ray et le SDK utilisent Jakarta Commons Logging (JCL). Pour voir le résultat de journalisation, assurez-vous qu'un pont reliant JCL à votre backend de journalisation se trouve sur le chemin de classe, comme dans l'exemple suivant : ou. `log4j-jcl` `jcl-over-slf4j` ### Problème : j'ai activé l'agent Java sur mon application mais je ne vois rien sur la console X-Ray **Le daemon X-Ray s'exécute-t-il sur la même machine ?** Si ce n'est pas le cas, consultez la [documentation du daemon X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) pour le configurer. **Dans les journaux de vos applications, voyez-vous un message tel que « Initializing the X-Ray Agent Recorder » ?** Si vous avez correctement ajouté l'agent à votre application, ce message est enregistré au niveau INFO au démarrage de votre application, avant qu'elle ne commence à recevoir des demandes. Si ce message n'est pas présent, cela signifie que l'agent Java n'est pas en cours d'exécution avec votre processus Java. Assurez-vous d'avoir suivi correctement toutes les étapes de configuration, sans fautes de frappe. **Dans les journaux de votre application, voyez-vous plusieurs messages d'erreur tels que « Suppression d'une exception manquante AWS X-Ray dans le contexte » ?** Ces erreurs se produisent parce que l'agent essaie d'instrumenter les requêtes en aval, telles que les requêtes du AWS SDK ou les requêtes SQL, mais il n'a pas réussi à créer automatiquement un segment. Si vous constatez un grand nombre de ces erreurs, l'agent n'est peut-être pas le meilleur outil pour votre cas d'utilisation et vous devriez plutôt envisager une instrumentation manuelle avec le kit de développement X-Ray. Vous pouvez également activer les [journaux de débogage](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) du SDK X-Ray pour voir la trace de l'endroit où se produisent les exceptions manquantes au contexte. Vous pouvez envelopper ces parties de votre code avec des segments personnalisés, ce qui devrait résoudre ces erreurs. Pour un exemple d'encapsulation de requêtes en aval avec des segments personnalisés, consultez l'exemple de code de la section [Instrumentation du code de démarrage](scorekeep-startup.md). ### Problème : certains des segments que je prévois n'apparaissent pas sur la console X-Ray **Votre application utilise-t-elle le multithreading ?** Si certains segments que vous pensez être créés n'apparaissent pas dans votre console, cela peut être dû aux fils d'arrière-plan de votre application. Si votre application exécute des tâches à l'aide de threads d'arrière-plan qui sont « déclenchés et oubliés », par exemple en effectuant un appel ponctuel à une fonction Lambda avec AWS le SDK ou en interrogeant régulièrement un point de terminaison HTTP, cela peut semer la confusion chez l'agent lorsqu'il propage le contexte entre les threads. Pour vérifier que c'est bien votre problème, activez les journaux de débogage du SDK X-Ray et vérifiez la présence de messages tels que : *Pas d'émission de segment nommé car il contient des sous-segments en* cours. Pour contourner ce problème, vous pouvez essayer de joindre les fils d'arrière-plan avant le retour de votre serveur afin de vous assurer que tout le travail effectué dans ceux-ci est enregistré. Vous pouvez également définir la `contextPropagation` configuration de l'agent `false` pour désactiver la propagation du contexte dans les fils d'arrière-plan. Dans ce cas, vous devrez instrumenter manuellement ces fils avec des segments personnalisés ou ignorer les exceptions manquantes liées au contexte qu'ils produisent. **Avez-vous défini des règles d'échantillonnage ?** Si des segments apparemment aléatoires ou inattendus apparaissent sur la console X-Ray, ou si les segments que vous pensez ne pas apparaître sur la console ne le sont pas, il se peut que vous rencontriez un problème d'échantillonnage. L'agent X-Ray applique un échantillonnage centralisé à tous les segments qu'il crée, en utilisant les règles de la console X-Ray. La règle par défaut est qu'un segment par seconde, plus 5 % des segments suivants sont échantillonnés. Cela signifie que les segments créés rapidement avec l'agent risquent de ne pas être échantillonnés. Pour résoudre ce problème, vous devez créer des règles d'échantillonnage personnalisées sur la console X-Ray afin d'échantillonner de manière appropriée les segments souhaités. Pour plus d'informations, voir [échantillonnage](xray-console-sampling.md). # Configuration du SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Le SDK X-Ray pour Java inclut une classe `AWSXRay` nommée qui fournit l'enregistreur global. Ceci est un `TracingHandler` que vous pouvez utiliser pour outiller votre code. Vous pouvez configurer l'enregistreur mondial pour personnaliser le `AWSXRayServletFilter` qui crée des segments pour les appels HTTP entrants. **Topics** + [Plug-ins de service](#xray-sdk-java-configuration-plugins) + [Règles d'échantillonnage](#xray-sdk-java-configuration-sampling) + [Logging](#xray-sdk-java-configuration-logging) + [Écouteurs de segment](#xray-sdk-java-configuration-listeners) + [Variables d’environnement](#xray-sdk-java-configuration-envvars) + [Propriétés système](#xray-sdk-java-configuration-sysprops) ## Plug-ins de service Permet `plugins` d'enregistrer des informations sur le service hébergeant votre application. **Plug-ins** + Amazon EC2 : `EC2Plugin` ajoute l'ID de l'instance, la zone de disponibilité et le groupe de CloudWatch journaux. + Elastic `ElasticBeanstalkPlugin` Beanstalk : ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement. + Amazon ECS — `ECSPlugin` ajoute l'ID du conteneur. + Amazon EKS : `EKSPlugin` ajoute l'ID du conteneur, le nom du cluster, l'ID du pod et le groupe de CloudWatch journaux. ![\[Segmentez les données des ressources avec les plugins Amazon EC2 et Elastic Beanstalk.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png) Pour utiliser un plug-in, appelez `withPlugin` sur votre `AWSXRayRecorderBuilder`. **Example src/main/java/scorekeep/WebConfig.java - enregistreur** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` Le SDK utilise également les paramètres du plugin pour définir le `origin` champ du segment. Cela indique le type de AWS ressource qui exécute votre application. Lorsque vous utilisez plusieurs plug-ins, le SDK utilise l'ordre de résolution suivant pour déterminer l'origine : ElasticBeanstalk > EKS > ECS > EC2. ## Règles d'échantillonnage Le SDK utilise les règles d'échantillonnage que vous définissez dans la console X-Ray pour déterminer les demandes à enregistrer. La règle par défaut suit la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires provenant de tous les services envoient des traces à X-Ray. [Créez des règles supplémentaires dans la console X-Ray](xray-console-sampling.md) pour personnaliser la quantité de données enregistrées pour chacune de vos applications. Le SDK applique les règles personnalisées dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, le SDK applique uniquement la première règle. **Note** Si le SDK ne parvient pas à accéder à X-Ray pour obtenir des règles d'échantillonnage, il revient à une règle locale par défaut concernant la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler sampling APIs ou ne peut pas se connecter au daemon X-Ray, qui agit comme un proxy TCP pour les appels d'API effectués par le SDK. Vous pouvez également configurer le SDK pour charger des règles d'échantillonnage à partir d'un document JSON. Le SDK peut utiliser les règles locales comme solution de rechange dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement les règles locales. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` Cet exemple définit une règle personnalisée et une règle par défaut. La règle personnalisée applique un taux d'échantillonnage de 5 % sans nombre minimum de demandes à suivre pour les chemins sous-jacents. `/api/move/` La règle par défaut suit la première demande chaque seconde et 10 % des demandes supplémentaires. L'inconvénient de définir des règles localement est que la cible fixe est appliquée par chaque instance de l'enregistreur indépendamment, au lieu d'être gérée par le service X-Ray. Au fur et à mesure que vous déployez de nouveaux hôtes, le taux fixe est multiplié, ce qui complique le contrôle de la quantité de données enregistrées. Activé AWS Lambda, vous ne pouvez pas modifier le taux d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des demandes échantillonnées par ce service seront enregistrés par Lambda. Si le suivi actif est activé et qu'aucun en-tête de suivi n'est présent, Lambda prend la décision d'échantillonnage. Pour fournir des règles de sauvegarde dans Spring, configurez l'enregistreur mondial avec une stratégie `CentralizedSamplingStrategy` dans une classe de configuration. **Example src/main/java/myapp/WebConfig.java - configuration de l'enregistreur** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } ``` Pour Tomcat, ajoutez un écouteur qui étend `ServletContextListener` et enregistrez l'écouteur dans le descripteur de déploiement. **Example src/com/myapp/web/Startup.java** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); import java.net.URL; import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; public class Startup implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } @Override public void contextDestroyed(ServletContextEvent event) { } } ``` **Example WEB-INF/web.xml** ``` ... com.myapp.web.Startup ``` Pour utiliser les règles local uniquement, remplacez `CentralizedSamplingStrategy` par `LocalizedSamplingStrategy`. ``` builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); ``` ## Logging Par défaut, le SDK envoie des messages de `ERROR` niveau B dans les journaux de vos applications. Vous pouvez activer la journalisation au niveau du débogage sur le SDK pour générer des journaux plus détaillés dans le fichier journal de votre application. Les niveaux de journalisation valides sont `DEBUG` `INFO``WARN`,,`ERROR`, et`FATAL`. `FATAL`le niveau du journal fait taire tous les messages de journal car le SDK ne se connecte pas au niveau fatal. **Example application.properties** Définissez le niveau de journalisation avec la propriété `logging.level.com.amazonaws.xray`. ``` logging.level.com.amazonaws.xray = DEBUG ``` Utilisez les journaux de débogage pour identifier les problèmes, tels que des sous-segments ouverts, lorsque vous [générez manuellement des sous-segments](xray-sdk-java-subsegments.md). ### Injection d'ID de suivi dans les journaux Pour exposer l'ID de trace complet actuel à vos instructions de journal, vous pouvez l'injecter dans le contexte de diagnostic mappé (MDC). À l'aide de l'interface `SegmentListener`, les méthodes sont appelées à partir de l'enregistreur X-Ray lors des événements du cycle de vie des segments. Lorsqu'un segment ou un sous-segment commence, l'ID de trace qualifié est injecté dans le MDC avec la clé `AWS-XRAY-TRACE-ID`. Lorsque ce segment se termine, la clé est supprimée du MDC. Ceci expose l'ID de trace à la bibliothèque de journalisation en cours d'utilisation. Lorsqu'un sous-segment se termine, son ID parent est injecté dans le MDC. **Example ID de trace complet** L'ID complet est affiché au format `TraceID@EntityID` ``` 1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3 ``` Cette fonctionnalité fonctionne avec les applications Java instrumentées avec le SDK AWS X-Ray pour Java et prend en charge les configurations de journalisation suivantes : + SLF4API frontale J avec backend Logback + SLF4API frontale J avec backend Log4J2 + API frontale Log4J2 avec backend Log4J2 Consultez les onglets suivants pour connaître les besoins de chaque frontal et de chaque backend. ------ #### [ SLF4J Frontend ] 1. Ajoutez la dépendance Maven suivante à votre projet. ``` com.amazonaws aws-xray-recorder-sdk-slf4j 2.11.0 ``` 1. Incluez la méthode `withSegmentListener` lors de la construction du `AWSXRayRecorder`. Cela ajoute une `SegmentListener` classe qui injecte automatiquement une nouvelle trace IDs dans le SLF4 J MDC. `SegmentListener` utilise une chaîne facultative comme paramètre pour configurer le préfixe de l'instruction de journalisation. Le préfixe peut être configuré comme suit : + **Aucun** — Utilise le `AWS-XRAY-TRACE-ID` préfixe par défaut. + **Vide** — Utilise une chaîne vide (par exemple`""`). + **Personnalisé** — Utilise un préfixe personnalisé tel que défini dans la chaîne. **Example `AWSXRayRecorderBuilder` déclaration** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Log4J2 front end ] 1. Ajoutez la dépendance Maven suivante à votre projet. ``` com.amazonaws aws-xray-recorder-sdk-log4j 2.11.0 ``` 1. Incluez la méthode `withSegmentListener` lors de la construction du `AWSXRayRecorder`. Cela ajoutera une `SegmentListener` classe qui injecte automatiquement une nouvelle trace entièrement qualifiée IDs dans le SLF4 J MDC. `SegmentListener` utilise une chaîne facultative comme paramètre pour configurer le préfixe de l'instruction de journalisation. Le préfixe peut être configuré comme suit : + **Aucun** — Utilise le `AWS-XRAY-TRACE-ID` préfixe par défaut. + **Vide** — Utilise une chaîne vide (par exemple`""`) et supprime le préfixe. + **Personnalisé** — Utilise le préfixe personnalisé défini dans la chaîne. **Example `AWSXRayRecorderBuilder` déclaration** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Logback backend ] Pour insérer l'ID de trace dans vos événements de journal, vous devez modifier le `PatternLayout` de l'enregistreur, qui formate chaque instruction de journalisation. 1. Recherchez l'emplacement où `patternLayout` est configuré. Vous pouvez le faire par programme ou via un fichier de configuration XML. Pour en savoir plus, consultez [Configuration Logback](http://logback.qos.ch/manual/configuration.html). 1. Insérez `%X{AWS-XRAY-TRACE-ID}` n'importe où dans le `patternLayout` pour insérer l'ID de trace dans les instructions de journalisation futures. `%X{}` indique que vous récupérez une valeur avec la clé fournie à partir du MDC. Pour en savoir plus sur PatternLayouts Logback, voir [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout). ------ #### [ Log4J2 backend ] 1. Recherchez l'emplacement où `patternLayout` est configuré. Vous pouvez le faire par programme ou via un fichier de configuration écrit au format XML, JSON, YAML ou propriétés. Pour en savoir plus sur la configuration de Log4J2 via un fichier de configuration, consultez [Configuration](https://logging.apache.org/log4j/2.x/manual/configuration.html). Pour en savoir plus sur la configuration de Log4J2 par programmation, consultez [Configuration programmatique](https://logging.apache.org/log4j/2.x/manual/customconfig.html). 1. Insérez `%X{AWS-XRAY-TRACE-ID}` n'importe où dans le `PatternLayout` pour insérer l'ID de trace dans les instructions de journalisation futures. `%X{}` indique que vous récupérez une valeur avec la clé fournie à partir du MDC. [Pour en savoir plus sur PatternLayouts Log4J2, consultez Pattern Layout.](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout) ------ **Exemple d'injection d'ID de trace** Ce qui suit montre une chaîne `PatternLayout` modifiée pour inclure l'ID de trace. L'ID de trace est imprimé après le nom du thread (`%t`) et avant le niveau du journal (`%-5p`). **Example `PatternLayout` avec injection d'ID** ``` %d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n ``` AWS X-Ray imprime automatiquement la clé et l'identifiant de trace dans l'instruction du journal pour faciliter l'analyse. Ce qui suit montre une instruction de journal à l'aide de la modification de `PatternLayout`. **Example Instruction de journalisation avec injection d'ID** ``` 2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here ``` Le message de journalisation lui-même est hébergé dans le modèle `%m` et est défini lors de l'appel de l'enregistreur. ## Écouteurs de segment Les écouteurs de segments sont une interface permettant d'intercepter les événements du cycle de vie tels que le début et la fin des segments produits par le. `AWSXRayRecorder` L'implémentation d'une fonction d'événement d'écouteur de segment peut consister à ajouter la même annotation à tous les sous-segments lorsqu'ils sont créés avec [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-), à journaliser un message une fois que chaque segment est envoyé au démon à l'aide de [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-), ou à enregistrer les requêtes envoyées par les intercepteurs SQL à l'aide de [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) pour vérifier si le sous-segment représente une requête SQL, en ajoutant des métadonnées supplémentaires dans ce cas. Pour consulter la liste complète des `SegmentListener` fonctions, consultez la documentation de l'API [AWS X-Ray Recorder SDK for Java](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html). L'exemple suivant montre comment ajouter une annotation cohérente à tous les sous-segments lors de la création avec [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) et comment imprimer un message de journal à la fin de chaque segment avec [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-). **Example MySegmentListener.java** ``` import com.amazonaws.xray.entities.Segment; import com.amazonaws.xray.entities.Subsegment; import com.amazonaws.xray.listeners.SegmentListener; public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); } } ``` Cet écouteur de segment personnalisé est ensuite référencé lors de la génération de `AWSXRayRecorder`. **Example AWSXRayRecorderBuilder déclaration** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener()); ``` ## Variables d’environnement Vous pouvez utiliser des variables d'environnement pour configurer le SDK X-Ray pour Java. Le kit SDK prend en charge les variables suivantes. + `AWS_XRAY_CONTEXT_MISSING`— Réglé sur `RUNTIME_ERROR` pour générer des exceptions lorsque votre code instrumenté tente d'enregistrer des données alors qu'aucun segment n'est ouvert. **Valeurs valides** + `RUNTIME_ERROR`— Lance une exception d'exécution. + `LOG_ERROR`— Enregistrez une erreur et continuez (par défaut). + `IGNORE_ERROR`— Ignorez l'erreur et continuez. Des erreurs liées à des segments ou sous-segments manquants peuvent se produire lorsque vous essayez d'utiliser un client instrumenté dans un code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans un code qui génère un nouveau thread. + `AWS_XRAY_DAEMON_ADDRESS`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray. Par défaut, le SDK utilise à la fois `127.0.0.1:2000` les données de trace (UDP) et l'échantillonnage (TCP). Utilisez cette variable si vous avez configuré le démon pour qu'il [écoute sur un port différent](xray-daemon-configuration.md) ou s'il s'exécute sur un autre hôte. **Format** + **Même port** — `address:port` + **Différents ports** — `tcp:address:port udp:address:port` + `AWS_LOG_GROUP`— Définissez le nom d'un groupe de journaux sur le groupe de journaux associé à votre application. Si votre groupe de journaux utilise le même AWS compte et la même région que votre application, X-Ray recherchera automatiquement les données de segment de votre application à l'aide de ce groupe de journaux spécifié. Pour plus d'informations sur les groupes de journaux, consultez la section [Utilisation des groupes de journaux et des flux](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html). + `AWS_XRAY_TRACING_NAME`— Définissez un nom de service que le SDK utilise pour les segments. Remplace le nom de service que vous définissez sur la [stratégie d'attribution de noms de segment](xray-sdk-java-filters.md#xray-sdk-java-filters-naming) du filtre servlet. Les variables d'environnement remplacent les [propriétés de système](#xray-sdk-java-configuration-sysprops) et les valeurs équivalentes définies dans le code. ## Propriétés système Vous pouvez utiliser les propriétés de système en tant qu'alternative JVM aux [variables d'environnement](#xray-sdk-java-configuration-envvars). Le kit SDK prend en charge les propriétés suivantes : + `com.amazonaws.xray.strategy.tracingName`— Équivalent à`AWS_XRAY_TRACING_NAME`. + `com.amazonaws.xray.emitters.daemonAddress`— Équivalent à`AWS_XRAY_DAEMON_ADDRESS`. + `com.amazonaws.xray.strategy.contextMissingStrategy`— Équivalent à`AWS_XRAY_CONTEXT_MISSING`. Si une propriété système et la variable d'environnement équivalente sont toutes les deux définies, c'est la valeur de la variable d'environnement qui est utilisée. Les deux méthodes remplacent les valeurs définies dans le code. # Suivi des demandes entrantes avec le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Vous pouvez utiliser le SDK X-Ray pour suivre les requêtes HTTP entrantes traitées par votre application sur une instance EC2 dans Amazon EC2 ou Amazon AWS Elastic Beanstalk ECS. Utilisez un `Filter` pour instrumenter les demandes HTTP entrantes. Lorsque vous ajoutez le filtre de servlet X-Ray à votre application, le SDK X-Ray pour Java crée un segment pour chaque requête échantillonnée. Ce segment comprend la durée, la méthode et l'état de la demande HTTP. L'instrumentation supplémentaire crée des sous-segments sur ce segment. **Note** Pour les AWS Lambda fonctions, Lambda crée un segment pour chaque requête échantillonnée. Pour plus d’informations, consultez [AWS Lambda et AWS X-Ray](xray-services-lambda.md). Chaque segment porte un nom qui identifie votre application dans la carte des services. Le segment peut être nommé de manière statique ou vous pouvez configurer le SDK pour qu'il soit nommé dynamiquement en fonction de l'en-tête de l'hôte dans la demande entrante. La dénomination dynamique vous permet de regrouper les traces en fonction du nom de domaine indiqué dans la demande et d'appliquer un nom par défaut si le nom ne correspond pas au modèle attendu (par exemple, si l'en-tête de l'hôte est falsifié). **Demandes transmises** Si un équilibreur de charge ou un autre intermédiaire transmet une demande à votre application, X-Ray prend l'adresse IP du client depuis l'`X-Forwarded-For`en-tête de la demande plutôt que depuis l'adresse IP source du paquet IP. L'adresse IP du client enregistrée pour une demande transférée peut être falsifiée, elle ne doit donc pas être fiable. Lorsqu'une demande est transmise, le SDK définit un champ supplémentaire dans le segment pour l'indiquer. Si le segment contient le champ `x_forwarded_for` défini sur`true`, l'adresse IP du client a été extraite de l'`X-Forwarded-For`en-tête de la requête HTTP. Le gestionnaire de messages crée un segment pour chaque demande entrante avec un bloc `http` contenant les informations suivantes : + **Méthode HTTP** : GET, POST, PUT, DELETE, etc. + **Adresse du client** : adresse IP du client qui a envoyé la demande. + **Code de réponse** : code de réponse HTTP pour la demande terminée. + **Moment** : heure de début (date de réception de la demande) et heure de fin (date d'envoi de la réponse). + **Agent utilisateur** — Le formulaire `user-agent` de la demande. + **Longueur du contenu** : `content-length` extrait de la réponse. **Topics** + [Ajout d'un filtre de suivi à votre application (Tomcat)](#xray-sdk-java-filters-tomcat) + [Ajout d'un filtre de suivi à votre application (Spring)](#xray-sdk-java-filters-spring) + [Configuration d'une stratégie d'attribution de noms de segment](#xray-sdk-java-filters-naming) ## Ajout d'un filtre de suivi à votre application (Tomcat) Pour Tomcat, ajoutez un `` aux fichier `web.xml` de votre projet. Utilisez le paramètre `fixedName` pour spécifier un [nom de service](#xray-sdk-java-filters-naming) à appliquer aux segments créés pour les demandes entrantes. **Example WEB-INF/web.xml - Tomcat** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter fixedName MyApp AWSXRayServletFilter * ``` ## Ajout d'un filtre de suivi à votre application (Spring) Pour Spring, ajoutez un `Filter` à votre classe `WebConfig`. Transmettez le nom du segment au constructeur [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) en tant que chaîne. **Example src/main/java/myapp/WebConfig.java - printemps** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## Configuration d'une stratégie d'attribution de noms de segment AWS X-Ray utilise un *nom de service* pour identifier votre application et la distinguer des autres applications, bases de données, ressources externes APIs et AWS ressources utilisées par votre application. Lorsque le SDK X-Ray génère des segments pour les demandes entrantes, il enregistre le nom du service de votre application dans le [champ du nom](xray-api-segmentdocuments.md#api-segmentdocuments-fields) du segment. Le SDK X-Ray peut nommer les segments d'après le nom d'hôte dans l'en-tête de la requête HTTP. Cependant, cet en-tête peut être falsifié, ce qui peut entraîner la création de nœuds inattendus dans votre carte de service. Pour éviter que le SDK ne nomme les segments de manière incorrecte en raison de demandes contenant des en-têtes d'hôte falsifiés, vous devez spécifier un nom par défaut pour les demandes entrantes. Si votre application traite des demandes pour plusieurs domaines, vous pouvez configurer le SDK pour qu'il utilise une stratégie de dénomination dynamique afin de refléter cela dans les noms des segments. Une stratégie de dénomination dynamique permet au SDK d'utiliser le nom d'hôte pour les demandes qui correspondent à un modèle attendu et d'appliquer le nom par défaut aux demandes qui ne le sont pas. Par exemple, il se peut qu'une seule application envoie des demandes à trois sous-domaines : `www.example.com``api.example.com`, et`static.example.com`. Vous pouvez utiliser une stratégie de dénomination dynamique avec le modèle `*.example.com` pour identifier les segments de chaque sous-domaine avec un nom différent, ce qui permet d'obtenir trois nœuds de service sur la carte des services. Si votre application reçoit des demandes dont le nom d'hôte ne correspond pas au modèle, vous verrez un quatrième nœud sur la carte des services avec un nom de remplacement que vous spécifiez. Pour utiliser le même nom pour tous les segments de la demande, spécifiez le nom de votre application lorsque vous initialisez le filtre servlet, comme indiqué dans la [section précédente](#xray-sdk-java-filters-tomcat). Cela a le même effet que de créer un correctif [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)en l'appelant `SegmentNamingStrategy.fixed()` et en le transmettant au [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)constructeur. **Note** Vous pouvez remplacer le nom de service par défaut que vous définissez avec la `AWS_XRAY_TRACING_NAME`variable d'environnement[Variables d’environnement](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars). Une stratégie d'attribution de noms dynamique définit un modèle auquel doivent correspondre les noms d'hôte et un nom par défaut à utiliser si le nom d'hôte de la demande HTTP ne correspond pas au modèle. Pour nommer les segments de façon dynamique dans Tomcat, utilisez `dynamicNamingRecognizedHosts` et `dynamicNamingFallbackName` pour définir, respectivement, le modèle et le nom par défaut. **Example WEB-INF/web.xml - Filtre servlet avec attribution de noms dynamique** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter dynamicNamingRecognizedHosts *.example.com dynamicNamingFallbackName MyApp AWSXRayServletFilter * ``` Pour Spring, créez une dynamique [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)en appelant `SegmentNamingStrategy.dynamic()` et transmettez-la au `AWSXRayServletFilter` constructeur. **Example src/main/java/myapp/WebConfig.java - filtre de servlet avec dénomination dynamique** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com")); } } ``` # Suivi des appels du AWS SDK avec le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Lorsque votre application fait des appels Services AWS pour stocker des données, écrire dans une file d'attente ou envoyer des notifications, le SDK X-Ray pour Java suit les appels en aval [dans](xray-sdk-java-subsegments.md) des sous-segments. Les ressources tracées Services AWS et auxquelles vous accédez au sein de ces services (par exemple, un compartiment Amazon S3 ou une file d'attente Amazon SQS) apparaissent sous forme de nœuds en aval sur la carte de trace de la console X-Ray. Le SDK X-Ray pour Java instrumente automatiquement tous les clients du SDK AWS lorsque vous incluez `aws-sdk` les sous-modules et `aws-sdk-instrumentor` [an](xray-sdk-java.md#xray-sdk-java-submodules) dans votre build. Si vous n'incluez pas les sous-modules Instrumentor, vous pouvez choisir d'instrumenter certains clients tout en excluant d'autres. Pour instrumenter des clients individuels, supprimez le `aws-sdk-instrumentor` sous-module de votre build et ajoutez-en un `XRayClient` en tant que `TracingHandler` sur votre client AWS SDK à l'aide du générateur de clients du service. Par exemple, pour instrumenter un client `AmazonDynamoDB`, transmettez un gestionnaire de suivi à `AmazonDynamoDBClientBuilder`. **Example MyModel.java - Client DynamoDB** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); ... public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); ... ``` Pour tous les services, vous pouvez voir le nom de l'API appelée dans la console X-Ray. Pour un sous-ensemble de services, le SDK X-Ray ajoute des informations au segment afin d'améliorer la granularité de la carte des services. Par exemple, lorsque vous passez un appel avec un client DynamoDB instrumenté, le SDK ajoute le nom de la table au segment pour les appels qui ciblent une table. Dans la console, chaque table apparaît sous la forme d'un nœud distinct dans la carte des services, avec un nœud DynamoDB générique pour les appels qui ne ciblent pas une table. **Example Sous-segment pour un appel à DynamoDB pour enregistrer un élément** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` Lorsque vous accédez aux ressources nommées, les appels vers les services suivants créent des nœuds supplémentaires dans la cartographie des services. Les appels qui ne ciblent pas de ressources spécifiques créent un nœud générique pour le service. + **Amazon DynamoDB — Nom** de la table + **Amazon Simple Storage Service** : nom du compartiment et de la clé + **Amazon Simple Queue Service** — Nom de la file d'attente Pour instrumenter les appels en aval vers Services AWS AWS SDK pour Java 2.2 et versions ultérieures, vous pouvez omettre le `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` module de votre configuration de compilation. Incluez plutôt le module `aws-xray-recorder-sdk-aws-sdk-v2 module`, puis instrumentez les clients individuels en les configurant avec un `TracingInterceptor`. **Example AWS SDK pour Java 2.2 et versions ultérieures - intercepteur de traçage** ``` import com.amazonaws.xray.interceptors.TracingInterceptor; import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration import software.amazon.awssdk.services.dynamodb.DynamoDbClient; //... public class MyModel { private DynamoDbClient client = DynamoDbClient.builder() .region(Region.US_WEST_2) .overrideConfiguration(ClientOverrideConfiguration.builder() .addExecutionInterceptor(new TracingInterceptor()) .build() ) .build(); //... ``` # Suivi des appels vers les services Web HTTP en aval avec le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Lorsque votre application effectue des appels vers des microservices ou du protocole HTTP public APIs, vous pouvez utiliser la version de X-Ray SDK pour Java pour `HttpClient` instrumenter ces appels et ajouter l'API au graphe de service en tant que service en aval. Le SDK X-Ray pour Java `DefaultHttpClient` inclut des `HttpClientBuilder` classes qui peuvent être utilisées à la place des équivalents HttpComponents Apache pour instrumenter les appels HTTP sortants. + `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient` + `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder` Ces bibliothèques se trouvent dans le sous-module [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md). Vous pouvez remplacer vos relevés d'importation existants par l'équivalent de X-Ray pour instrumenter tous les clients, ou utiliser le nom complet lorsque vous initialisez un client pour instrumenter des clients spécifiques. **Example HttpClientBuilder** ``` import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.util.EntityUtils; import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); ... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` Lorsque vous instrumentez un appel à une API Web en aval, le SDK X-Ray pour Java enregistre un sous-segment contenant des informations sur la requête et la réponse HTTP. X-Ray utilise le sous-segment pour générer un segment inféré pour l'API distante. **Example Sous-segment pour un appel HTTP en aval** ``` { "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } } } ``` **Example Segment déduit pour un appel HTTP en aval** ``` { "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-62be1272-1b71c4274f39f122afa64eab", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true } ``` # Suivi des requêtes SQL avec le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). ## Intercepteurs SQL Instrumentez les requêtes de base de données SQL en ajoutant l'intercepteur JDBC du SDK X-Ray pour Java à la configuration de votre source de données. + **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor` + **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor` Ces intercepteurs se trouvent respectivement dans les sous-modules [`aws-xray-recorder-sql-postgres` et `aws-xray-recorder-sql-mysql`](xray-sdk-java.md). Ils implémentent `org.apache.tomcat.jdbc.pool.JdbcInterceptor` et sont compatibles avec les groupes de connexion Tomcat. **Note** Les intercepteurs SQL n'enregistrent pas la requête SQL elle-même dans les sous-segments à des fins de sécurité. Pour Spring, ajoutez l'intercepteur dans un fichier de propriétés et créez la source de données avec le `DataSourceBuilder` de Spring Boot. **Example `src/main/java/resources/application.properties` - Intercepteur JDBC PostgreSQL** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **Example `src/main/java/myapp/WebConfig.java` - Source de données** ``` import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.jpa.repository.config.EnableJpaRepositories; import javax.servlet.Filter; import javax.sql.DataSource; import java.net.URL; @Configuration @EnableAutoConfiguration @EnableJpaRepositories("myapp") public class RdsWebConfig { @Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); } ... } ``` Pour Tomcat, faites appel à `setJdbcInterceptors` la source de données JDBC en faisant référence à la classe X-Ray SDK for Java. **Example `src/main/myapp/model.java` - Source de données** ``` import org.apache.tomcat.jdbc.pool.DataSource; ... DataSource source = new DataSource(); source.setUrl(url); source.setUsername(user); source.setPassword(password); source.setDriverClassName("com.mysql.jdbc.Driver"); source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;"); ``` La bibliothèque de sources de données Tomcat JDBC est incluse dans le SDK X-Ray pour Java, mais vous pouvez la déclarer comme dépendance fournie pour documenter que vous l'utilisez. **Example `pom.xml` - Source de données JDBC** ``` org.apache.tomcat tomcat-jdbc 8.0.36 provided ``` ## Décorateur de traçage SQL natif + Ajoutez [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql)à vos dépendances. + Décorez la source de données, la connexion ou l'instruction de votre base de données. ``` dataSource = TracingDataSource.decorate(dataSource) connection = TracingConnection.decorate(connection) statement = TracingStatement.decorateStatement(statement) preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql) callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql) ``` # Génération de sous-segments personnalisés avec le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Les sous-segments étendent le [segment](xray-concepts.md#xray-concepts-segments) d'une trace avec des détails sur le travail effectué afin de répondre à une demande. Chaque fois que vous passez un appel avec un client instrumenté, le SDK X-Ray enregistre les informations générées dans un sous-segment. Vous pouvez créer des sous-segments supplémentaires pour regrouper d'autres sous-segments, pour mesurer les performances d'une section de code ou pour enregistrer des annotations et des métadonnées. Pour gérer des sous-segments, utilisez les méthodes `beginSubsegment` et `endSubsegment`. **Example GameModel.java - sous-segment personnalisé** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` Dans cet exemple, le code du sous-segment charge la session du jeu depuis DynamoDB à l'aide d'une méthode basée sur le modèle de session et utilise le mappeur DynamoDB pour enregistrer le AWS SDK pour Java jeu. L'encapsulation de ce code dans un sous-segment fait des appels DynamoDB des enfants du sous-segment dans `Save Game` la vue de suivi de la console. ![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png) Si le code de votre sous-segment lève des exceptions cochées, enveloppez-le dans un bloc `try` et appelez `AWSXRay.endSubsegment()` dans un bloc `finally` pour veiller à ce que le sous-segment soit toujours fermé. Si un sous-segment n'est pas fermé, le segment parent ne peut pas être terminé et ne sera pas envoyé à X-Ray. Pour le code qui ne génère pas d'exceptions vérifiées, vous pouvez le transmettre `AWSXRay.CreateSubsegment` en tant que fonction Lambda. **Example Sous-segment de la fonction Lambda** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code }); ``` Lorsque vous créez un sous-segment au sein d'un segment ou d'un autre sous-segment, le SDK X-Ray pour Java génère un identifiant et enregistre l'heure de début et de fin. **Example Sous-segment avec des métadonnées** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` Pour la programmation asynchrone et multithread, vous devez transmettre manuellement le sous-segment à la `endSubsegment()` méthode pour vous assurer qu'il est correctement fermé, car le contexte de X-Ray peut être modifié lors de l'exécution asynchrone. Si un sous-segment asynchrone est fermé après la fermeture de son segment parent, cette méthode diffuse automatiquement le segment entier vers le daemon X-Ray. **Example Sous-segment asynchrone** ``` @GetMapping("/api") public ResponseEntity api() { CompletableFuture.runAsync(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("Async Work"); try { Thread.sleep(3000); } catch (InterruptedException e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(subsegment); } }); return ResponseEntity.ok().build(); } ``` # Ajoutez des annotations et des métadonnées aux segments avec le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Vous pouvez enregistrer des informations supplémentaires sur les demandes, l'environnement ou votre application à l'aide d'annotations et de métadonnées. Vous pouvez ajouter des annotations et des métadonnées aux segments créés par le SDK X-Ray ou aux sous-segments personnalisés que vous créez. Les **annotations sont des** paires clé-valeur avec des chaînes, des nombres ou des valeurs booléennes. Les annotations sont indexées pour être utilisées avec les expressions de [filtre](xray-console-filters.md). Utilisez les annotations pour enregistrer les données que vous souhaitez utiliser pour regrouper les suivis dans la console ou lors de l'appel de l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Les **métadonnées sont des** paires clé-valeur qui peuvent contenir des valeurs de n'importe quel type, y compris des objets et des listes, mais qui ne sont pas indexées pour être utilisées avec des expressions de filtre. Utilisez les métadonnées pour enregistrer des données supplémentaires que vous souhaitez stocker dans le traçage, mais que vous n'avez pas besoin d'utiliser pour la recherche. En plus des annotations et des métadonnées, vous pouvez également [enregistrer les chaînes d'ID utilisateur](#xray-sdk-java-segment-userid) sur des segments. IDs Les utilisateurs sont enregistrés dans un champ distinct sur les segments et sont indexés pour être utilisés dans le cadre de la recherche. **Topics** + [Enregistrer des annotations avec le SDK X-Ray pour Java](#xray-sdk-java-segment-annotations) + [Enregistrement de métadonnées avec le SDK X-Ray pour Java](#xray-sdk-java-segment-metadata) + [Utilisateur enregistrant IDs avec le SDK X-Ray pour Java](#xray-sdk-java-segment-userid) ## Enregistrer des annotations avec le SDK X-Ray pour Java Utilisez les annotations pour enregistrer les informations sur les segments ou sous-segments qui doivent être indexés pour la recherche. **Exigences liées aux annotations** + **Clés** — La clé d'une annotation X-Ray peut comporter jusqu'à 500 caractères alphanumériques. Vous ne pouvez pas utiliser d'espaces ou de symboles autres qu'un point ou un point (.) + **Valeurs** — La valeur d'une annotation X-Ray peut comporter jusqu'à 1 000 caractères Unicode. + Nombre d'**annotations** : vous pouvez utiliser jusqu'à 50 annotations par trace. **Pour enregistrer les annotations** 1. Obtenez une référence au segment ou sous-segment en cours à partir d'`AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` or ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. Appelez `putAnnotation` avec une clé de type chaîne et une valeur de type booléen, numérique ou chaîne. ``` document.putAnnotation("mykey", "my value"); ``` L'exemple suivant montre comment appeler `putAnnotation` avec une clé String qui inclut un point et une valeur booléenne, numérique ou chaîne. ``` document.putAnnotation("testkey.test", "my value"); ``` Le kit de développement logiciel enregistre les annotations sous forme de paires clé-valeur dans un objet `annotations` du document de segment. Si vous appelez deux fois `putAnnotation` avec la même clé, les valeurs précédemment enregistrées sur le même segment ou sous-segment sont remplacées. Pour rechercher les suivis ayant des annotations avec des valeurs spécifiques, utilisez le mot clé `annotation[key]` dans une [expression de filtre](xray-console-filters.md). **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java)— Annotations et métadonnées** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## Enregistrement de métadonnées avec le SDK X-Ray pour Java Utilisez les métadonnées pour enregistrer des informations sur les segments ou sous-segments qui n'ont pas besoin d'être indexés pour la recherche. Les valeurs des métadonnées peuvent être de type chaîne, valeur numérique, valeur booléenne ou tout objet à même d'être sérialisé en un tableau ou objet JSON. **Pour enregistrer les métadonnées** 1. Obtenez une référence au segment ou sous-segment en cours à partir d'`AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` or ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. Appelez `putMetadata` avec un espace de noms de type chaîne, une clé de type chaîne, et une valeur de type booléen, numérique, chaîne ou objet. ``` document.putMetadata("my namespace", "my key", "my value"); ``` or Appelez `putMetadata` avec seulement une clé et une valeur. ``` document.putMetadata("my key", "my value"); ``` Si vous ne spécifiez pas d'espace de noms, le kit de développement logiciel utilise `default`. Si vous appelez deux fois `putMetadata` avec la même clé, les valeurs précédemment enregistrées sur le même segment ou sous-segment sont remplacées. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java)— Annotations et métadonnées** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## Utilisateur enregistrant IDs avec le SDK X-Ray pour Java Enregistrez les segments utilisateur IDs sur demande pour identifier l'utilisateur qui a envoyé la demande. **Pour enregistrer un utilisateur IDs** 1. Obtenez une référence au segment en cours à partir d'`AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 1. Appelez `setUser` avec l'ID de type chaîne de l'utilisateur ayant envoyé la demande. ``` document.setUser("U12345"); ``` Vous pouvez appeler `setUser` dans vos contrôleurs pour enregistrer l'ID utilisateur dès que votre application commence le traitement d'une demande. Si vous n'utilisez le segment que pour définir l'ID utilisateur, vous pouvez chaîner les appels sur une seule ligne. **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) — ID utilisateur** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` Pour rechercher les suivis d'un ID utilisateur, utilisez le mot clé `user` dans une [expression de filtre](xray-console-filters.md). ## AWS X-Ray métriques pour le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Cette rubrique décrit l'espace de AWS X-Ray noms, les métriques et les dimensions. Vous pouvez utiliser le SDK X-Ray pour Java pour publier des métriques CloudWatch 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 [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/). ### CloudWatch Métriques X-Ray L’espace de noms `ServiceMetrics/SDK` inclut les métriques suivantes. | Métrique | Statistiques disponibles | Description | Uunité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 du [SDK X-Ray pour Java](#xray-sdk-java-submodules). 1. Activez un nouveau dans le `MetricsSegmentListener()` comme partie intégrante de la construction de l'enregistreur global. **Example 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()); } } ``` 1. Déployez l' CloudWatch agent pour collecter des métriques à l'aide d'Amazon Elastic Compute Cloud (Amazon EC2), d'Amazon Elastic Container Service (Amazon ECS) ou d'Amazon Elastic Kubernetes Service (Amazon EKS) : + Pour configurer Amazon EC2, consultez la section [Installation de l' CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html). + Pour configurer Amazon ECS, consultez [Surveiller les conteneurs Amazon ECS à l'aide de Container Insights](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html). + Pour configurer Amazon EKS, consultez [Installer l' CloudWatch agent à l'aide du module complémentaire Amazon CloudWatch Observability EKS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html). 1. Configurez le SDK pour communiquer avec l' CloudWatch agent. Par défaut, le SDK communique avec l' CloudWatch agent sur l'adresse`127.0.0.1`. Vous pouvez configurer d'autres adresses en définissant la variable d'environnement ou la propriété Java sur `address:port`. **Example Variable d'environnement** ``` AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port ``` **Example 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/](https://console.aws.amazon.com/cloudwatch/). 1. Ouvrez l'onglet **Métriques** pour observer le flot de vos métriques. 1. (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. # Transmission de contexte de segment entre threads dans une application multithreads **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Lorsque vous créez un thread dans l'application, `AWSXRayRecorder` ne conserve pas de référence au segment ou sous-segment actuel [Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html). Si vous utilisez un client instrumenté dans le nouveau thread, le SDK essaie d'écrire sur un segment qui n'existe pas, ce qui provoque un. [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html) Pour éviter de générer des exceptions pendant le développement, vous pouvez configurer l'enregistreur avec un [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html)qui lui indique de consigner une erreur à la place. Vous pouvez configurer la stratégie en code avec [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy))une variable d'environnement ou une propriété système ou configurer des options équivalentes avec une [variable d'environnement](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) ou une [propriété système](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops). Pour résoudre l'erreur, vous pouvez utiliser un nouveau segment en appelant [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) lorsque vous démarrez le thread et [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--) lorsque vous le fermez. Cela fonctionne si vous instrumentez du code qui ne s'exécute pas en réponse à une demande HTTP, à l'image du code qui s'exécute au démarrage de l'application. Si vous utilisez plusieurs threads pour gérer les demandes entrantes, vous pouvez transmettre le segment ou le sous-segment en cours au nouveau thread et le fournir à l'enregistreur mondial. Cela permet de s'assurer que les informations enregistrées dans le nouveau thread sont associées au même segment que les autres informations enregistrées concernant cette demande. Une fois que le segment est disponible dans le nouveau thread, vous pouvez exécuter n'importe quel exécutable ayant accès au contexte de ce segment à l'aide de la `segment.run(() -> { ... })` méthode. Consultez [Utilisation de clients instrumentés dans les threads de travail](scorekeep-workerthreads.md) pour obtenir un exemple. ## Utilisation de X-Ray avec une programmation asynchrone Le SDK X-Ray pour Java peut être utilisé dans des programmes Java asynchrones avec. [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) SegmentContextExecutor implémente l'interface Executor, ce qui signifie qu'elle peut être transmise à toutes les opérations asynchrones d'un. [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) Cela garantit que toutes les opérations asynchrones seront exécutées avec le segment approprié dans son contexte. **Example Exemple App.java : Passage SegmentContextExecutor à CompletableFuture** ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.create(); AWSXRay.beginSegment(); // ... client.getItem(request).thenComposeAsync(response -> { // If we did not provide the segment context executor, this request would not be traced correctly. return client.getItem(request2); }, SegmentContextExecutors.newSegmentContextExecutor()); ``` # AOP avec Spring et le SDK X-Ray pour Java **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Cette rubrique décrit comment utiliser le SDK X-Ray et le Spring Framework pour instrumenter votre application sans en modifier la logique de base. Cela signifie qu'il existe désormais un moyen non invasif d'instrumenter vos applications exécutées à AWS distance. **Pour activer AOP dans Spring** 1. [Configurez Spring](#xray-sdk-java-aop-spring-configuration) 1. [Ajoutez un filtre de suivi à votre application](#xray-sdk-java-aop-filters-spring) 1. [Annotez votre code ou implémentez une interface](#xray-sdk-java-aop-annotate-or-implement) 1. [Activez X-Ray dans votre application](#xray-sdk-java-aop-activate-xray) ## Configuration de Spring Vous pouvez utiliser Maven ou Gradle pour configurer Spring afin de vous servir d'AOP pour instrumenter votre application. Si vous utilisez Maven pour créer votre application, ajoutez la dépendance suivante dans votre fichier `pom.xml`. ``` com.amazonaws aws-xray-recorder-sdk-spring 2.11.0 ``` Pour Gradle, ajoutez la dépendance suivante dans votre fichier `build.gradle`. ``` compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0' ``` ## Configuration de Spring Boot Outre la dépendance Spring décrite dans la section précédente, si vous utilisez Spring Boot, ajoutez la dépendance suivante si elle ne figure pas déjà dans votre chemin de classe. Maven : ``` org.springframework.boot spring-boot-starter-aop 2.5.2 ``` Gradle : ``` compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2' ``` ## Ajouter un filtre de suivi à votre application Ajoutez un `Filter` à votre `WebConfig` classe. Transmettez le nom du segment au constructeur [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) en tant que chaîne. Pour plus d'informations sur le suivi des filtres et l'instrumentation des demandes entrantes, consultez[Suivi des demandes entrantes avec le SDK X-Ray pour Java](xray-sdk-java-filters.md). **Example src/main/java/myapp/WebConfig.java - printemps** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## Support à Jakarta Spring 6 utilise [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) au lieu de Javax pour son édition Enterprise. Pour prendre en charge ce nouvel espace de noms, X-Ray a créé un ensemble parallèle de classes qui vivent dans leur propre espace de noms Jakarta. Pour les classes de filtres, remplacez `javax` par`jakarta`. Lorsque vous configurez une stratégie de dénomination de segment, ajoutez-la `jakarta` avant le nom de classe de stratégie de dénomination, comme dans l'exemple suivant : ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import jakarta.servlet.Filter; import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter; import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy; @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep")); } } ``` ## Annotation de votre code ou implémentation d'une interface Vos classes doivent soit être annotées avec l'`@XRayEnabled`annotation, soit implémenter l'`XRayTraced`interface. Cela demande au système AOP d'encapsuler les fonctions de la classe affectée pour l'instrumentation X-Ray. ## Activation de X-Ray dans votre application Pour activer le traçage X-Ray dans votre application, votre code doit étendre la classe abstraite `BaseAbstractXRayInterceptor` en remplaçant les méthodes suivantes. + `generateMetadata`—Cette fonction permet de personnaliser les métadonnées associées à la trace de la fonction en cours. Par défaut, le nom de classe de la fonction d'exécution est enregistré dans les métadonnées. Vous pouvez ajouter des données supplémentaires si vous avez besoin d'informations supplémentaires. + `xrayEnabledClasses`—Cette fonction est vide et doit le rester. Elle sert d'hôte pour un pointcut demandant à l'intercepteur quelles méthodes encapsuler. Définissez le pointcut en spécifiant les classes qui sont annotées avec `@XRayEnabled` pour effectuer le suivi. L'instruction de pointcut suivante demande à l'intercepteur d'encapsuler tous les beans de contrôleur annotés avec l'annotation `@XRayEnabled`. ``` @Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”) ``` Si votre projet utilise Spring Data JPA, envisagez d'étendre depuis `AbstractXRayInterceptor` au lieu de`BaseAbstractXRayInterceptor`. ## Exemple Le code suivant étend la classe abstraite`BaseAbstractXRayInterceptor`. ``` @Aspect @Component public class XRayInspector extends BaseAbstractXRayInterceptor { @Override protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} } ``` Le code suivant est une classe qui sera instrumentée par X-Ray. ``` @Service @XRayEnabled public class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository; @Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List getMyEntities(){ try(Stream entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } } } ``` Si vous avez correctement configuré votre application, vous devez voir la pile d'appels complète de l'application, depuis le contrôleur jusqu'aux appels de service, comme illustré dans la capture d'écran suivante de la console. ![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/aop-spring-console.png)