AWS X-Ray agent d'auto-instrumentation pour Java

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 HTTP requêtes Apache en aval, AWS SDK les SQL requêtes et les requêtes effectuées à l'aide d'un JDBC pilote. 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 X-Ray SDK 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 devriez peut-être envisager une instrumentation manuelle à la place. SDK 

L'agent X-Ray est créé à l'aide de la boîte à outils Distributed Systems Compréhension, ou D. iSCo D iSCo 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 D iSCo pour utiliser l'agent X-Ray, vous pouvez en savoir plus sur le projet en visitant sa page d'accueil sur GitHub. 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.

Exemple d'application

L'application eb-java-scorekeepd'é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.

Premiers pas

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 plus d’informations, consultez AWS X-Ray daemon.

2. Téléchargez la dernière distribution de l'agent. 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

3. Modifiez les JVM arguments de votre application pour inclure les éléments suivants, qui activent l'agent. Assurez-vous que l'-javaagentargument est placé avant l'-jarargument, le cas échéant. Le processus de modification des JVM arguments 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:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

4. Pour spécifier la manière dont le nom de votre application apparaît sur la console X-Ray, définissez la variable d'AWS_XRAY_TRACING_NAMEenvironnement ou la propriété com.amazonaws.xray.strategy.tracingName système. Si aucun nom n'est fourni, un nom par défaut est utilisé.

5. 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, consultezRésolution des problèmes.

Configuration

L'agent X-Ray est configuré par un JSON fichier 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, consultezVariables d’environnement. 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	Chaîne	Toute chaîne	Le nom de votre service instrumenté tel qu'il apparaîtra dans la console X-Ray.	AWS_XRAY_TRACING_NAME	com.amazonaws.xray.strategy. tracingName	XRayInstrumentedService
contextMissingStrategy	Chaîne	LOG_ERROR, IGNORE_ERROR	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_XRAY_CONTEXT_MISSING	com.amazonaws.xray.strategy. contextMissingStrategy	LOG_ERROR
daemonAddress	Chaîne	Adresse IP et port formatés, ou liste TCP d'UDPadresses	Adresse utilisée par l'agent pour communiquer avec le daemon X-Ray.	AWS_XRAY_DAEMON_ADDRESS	com.amazonaws.xray.emitter. daemonAddress	127,0.0. 1:2000
tracingEnabled	Booléen	Vrai, faux	Permet l'instrumentation par l'agent X-Ray.	AWS_XRAY_TRACING_ENABLED	com.amazonaws.xray. tracingEnabled	TRUE
samplingStrategy	Chaîne	CENTRAL, LOCAL, NONE, ALL	Stratégie d'échantillonnage utilisée par l'agent. ALLcapture toutes les demandes, n'en NONE capture aucune. Voir les règles d'échantillonnage.	N/A	N/A	CENTRAL
traceIdInjectionPréfixe	Chaîne	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	Chaîne	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
awsServiceHandlerManifeste	Chaîne	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 auprès des AWS SDK clients.	N/A	N/A	DefaultOperationParameterWhitelist.json
awsSdkVersion	Entier	1, 2	Version du AWS SDKpour Java que vous utilisez. Ignoré s'awsServiceHandlerManifestil 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
streamingThreshold	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 sont également ajoutées. Sinon, ne fait rien.	N/A	N/A	TRUE
pluginsEnabled	Booléen	Vrai, faux	Active les plug-ins qui enregistrent les métadonnées relatives AWS aux environnements dans lesquels vous travaillez. Voir plugins.	N/A	N/A	TRUE
collectSqlQueries	Booléen	Vrai, faux	Enregistre les chaînes de SQL requête dans SQL des sous-segments dans la mesure du possible.	N/A	N/A	FALSE
contextPropagation	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 journalisation

Le niveau de journalisation de l'agent X-Ray peut être configuré de la même manière que celui de X-Ray SDK pour Java. Consultez Journalisation pour plus d'informations sur la configuration de la journalisation avec X-Ray SDK pour Java.

Instrumentation manuelle

Si vous souhaitez effectuer une instrumentation manuelle en plus de l'instrumentation automatique de l'agent, ajoutez le X-Ray SDK en tant que dépendance à votre projet. Notez que les filtres SDK de servlet personnalisés mentionnés dans Tracing Incoming Requests ne sont pas compatibles avec l'agent X-Ray.

Note

Vous devez utiliser la dernière version du X-Ray SDK 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.

<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

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 en plus des annotations, des métadonnées et des utilisateurs IDs lorsque vous utilisez l'agent, comme vous le feriez avec l'agent normal. SDK 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 SDK utilisez Jakarta Commons Logging (JCL). Pour voir le résultat de journalisation, assurez-vous qu'un pont se connectant 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 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 INFO 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 demandes en aval, telles que les AWS SDK demandes ou les SQL requêtes, 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 SDK plutôt envisager une instrumentation manuelle avec le X-Ray. Vous pouvez également activer les journaux de SDK débogage de 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.

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 en utilisant des threads d'arrière-plan qui « se déclenchent et oublient », par exemple en effectuant un appel ponctuel à une fonction Lambda avec AWS SDK le ou en interrogeant régulièrement un point de terminaison, cela peut semer la confusion chez l'agent lorsqu'il propage le contexte HTTP entre les threads. Pour vérifier que c'est bien votre problème, activez les journaux de SDK débogage de X-Ray et vérifiez la présence de messages tels que : Pas d'émission de segment nommé < NAME > car il contient des sous-segments en cours de développement. 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.