Tracer des applications Java

Exigences de compatibilité

La dernière version du traceur Java prend en charge toutes les JVM à partir de la version 8. Pour en savoir plus sur les JVM antérieures à la version 8, consultez la section Runtimes JVM pris en charge.

Pour obtenir la liste complète des frameworks et versions Java pris en charge (y compris les anciennes versions et les versions de maintenance), consultez la section relative aux exigences de compatibilité.

Installation et démarrage

Suivre la documentation dans l’application (conseillé)

Suivez les instructions de démarrage rapide fournies dans l’application Datadog pour profiter d’une expérience optimale, et notamment :

• Obtenir des instructions détaillées en fonction de la configuration de votre déploiement (hosts, Docker, Kubernetes ou Amazon ECS) ;
• Définir les tags service, env et version de façon dynamique ;
• Activer le profileur en continu, l’ingestion de 100 % des traces et l’injection des ID de trace dans les logs durant la configuration.

Configurer l’Agent Datadog pour l’APM

Installez et configurez l’Agent Datadog de façon à ce qu’il reçoive des traces à partir de votre application instrumentée. Par défaut, l’Agent Datadog est activé dans votre fichier datadog.yaml sous apm_config avec enabled: true, et écoute les données de tracing sur http://localhost:8126. Pour les environnements conteneurisés, suivez les liens ci-dessous afin d’activer la collecte de traces au sein de l’Agent Datadog.

1. Définissez apm_non_local_traffic: true dans la section apm_config de votre fichier de configuration principal datadog.yaml.

2. Consultez les instructions de configuration spécifiques pour vous assurer que l’Agent est configuré de façon à recevoir des traces dans un environnement conteneurisé :

3. Une fois l’application instrumentée, le client de tracing tente d’envoyer les traces au socket de domaine Unix /var/run/datadog/apm.socket par défaut. Si le socket n’existe pas, les traces sont envoyées à http://localhost:8126.

   Si vous souhaitez spécifier un autre socket, host ou port, utilisez la variable d’environnement DD_TRACE_AGENT_URL. Voici quelques exemples :

   DD_TRACE_AGENT_URL=http://custom-hostname:1234
   DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket
   

   java -javaagent:<DD-JAVA-AGENT-PATH>.jar -jar <YOUR_APPLICATION_PATH>.jar
   

   Vous pouvez également utiliser des propriétés système :

   java -javaagent:<DD-JAVA-AGENT-PATH>.jar \
       -Ddd.trace.agent.url=$DD_TRACE_AGENT_URL \
       -jar <YOUR_APPLICATION_PATH>.jar
   

   Là encore, le client de tracing tente d’envoyer les statistiques au socket de domaine Unix /var/run/datadog/dsd.socket. Si le socket n’existe pas, les statistiques sont envoyées à http://localhost:8125.

4. Définissez DD_SITE dans l’Agent Datadog sur pour vous assurer que l’Agent envoie les données au bon site Datadog.

Pour configurer l’APM Datadog dans AWS Lambda, consultez la documentation dédiée au tracing de fonctions sans serveur.

Le tracing est disponible pour un certain nombre d’environnements, tels que Heroku, Cloud Foundry, AWS Elastic Beanstalk et Azure App Services.

Pour les autres environnements, consultez la documentation relative aux intégrations pour l’environnement qui vous intéresse. Contactez l’assistance si vous rencontrez des problèmes de configuration.

Instrumenter votre application

Une fois l’Agent installé, procédez comme suit pour commencer à tracer vos applications :

1. Téléchargez le fichier dd-java-agent.jar, qui contient les derniers fichiers de classe de l’Agent, dans un dossier auquel votre utilisateur Datadog peut accéder :

   wget -O dd-java-agent.jar https://dtdg.co/latest-java-tracer
   

   Remarque : pour télécharger le dernier build d’une version majeure spécifique, utilisez plutôt le lien https://dtdg.co/java-tracer-vX en remplaçant X par la version majeure souhaitée. Par exemple, utilisez https://dtdg.co/java-tracer-v1 pour obtenir le dernier build de la version 1. Les numéros des versions mineures ne doivent pas être inclus. Vous pouvez également récupérer n’importe quelle version spécifique depuis le référentiel Maven de Datadog.

2. Pour exécuter votre application à partir d’un IDE, d’un script d’application Maven ou Gradle, ou de la commande java -jar, avec le profileur en continu, le suivi des déploiements et l’injection de logs (si vous envoyez des logs à Datadog), ajoutez l’argument JVM -javaagent et les options de configuration suivantes, le cas échéant :

   java -javaagent:/path/to/dd-java-agent.jar -Ddd.profiling.enabled=true -XX:FlightRecorderOptions=stackdepth=256 -Ddd.logs.injection=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar
   

   Remarque : l’activation du profiling est susceptible d’augmenter vos coûts, en fonction de l’offre APM que vous avez choisie. Consultez la page des tarifs pour en savoir plus.

D’autres options de configuration sont décrites ci-dessous.

Ajouter le traceur Java à la JVM

Consultez la documentation de votre serveur d’application pour découvrir comment passer -javaagent et d’autres arguments JVM. Voici des instructions pour certains frameworks couramment utilisés :

JAVA_OPTS=-javaagent:/chemin/vers/dd-java-agent.jar

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/chemin/vers/dd-java-agent.jar"

set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"c:\chemin\vers\dd-java-agent.jar"

JAVA_OPTS="$JAVA_OPTS -javaagent:/chemin/vers/dd-java-agent.jar"

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/chemin/vers/dd-java-agent.jar"

<option value="-javaagent:/chemin/vers/dd-java-agent.jar"/>

JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/chemin/vers/dd-java-agent.jar"

-javaagent:/chemin/vers/dd-java-agent.jar

-javaagent:/chemin/vers/dd-java-agent.jar

Remarque

• Si vous ajoutez l’argument -javaagent à votre commande java -jar, il doit être ajouté avant l’argument -jar, c’est-à-dire en tant qu’option JVM et non en tant qu’argument d’application. Par exemple :

  java -javaagent:/path/to/dd-java-agent.jar -jar my_app.jar
  

  Pour en savoir plus, consultez la documentation Oracle (en anglais).

• N’ajoutez jamais dd-java-agent à votre classpath. Cela peut entraîner un comportement inattendu.

Instrumentation automatique

L’instrumentation automatique pour Java utilise les fonctionnalités d’instrumentation java-agent fournies par la JVM. Lorsqu’un java-agent est enregistré, il est capable de modifier les fichiers de classe durant le chargement.

Remarque : les classes chargées avec le ClassLoader à distance ne sont pas automatiquement instrumentées.

L’instrumentation peut provenir de l’instrumentation automatique, de l’API OpenTracing ou d’un mélange des deux. L’instrumentation capture généralement les informations suivantes :

• La durée est capturée à l’aide de l’horloge nanoTime de la JVM, sauf si un timestamp est fourni à partir de l’API OpenTracing
• Les paires de tags key/value
• Les erreurs et les stack traces non gérées par l’application
• Le nombre total de traces (requêtes) transmises via le système

Configuration

Au besoin, configurez la bibliothèque de tracing pour envoyer des données de télémétrie relatives aux performances de l’application, notamment en configurant le tagging de service unifié. Consultez la section Configuration de la bibliothèque pour en savoir plus.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Code source de l'APM Datadog JavaGITHUB Explorer vos services, ressources et tracesDOCUMENTATION