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é :

Docker
Kubernetes
Amazon ECS
ECS Fargate

  1. 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.

  1. 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

Si vous recueillez des traces à partir d'une application Kubernetes ou à partir d'une application sur un host ou conteneur Linux, plutôt que de suivre les instructions ci-dessous, vous pouvez injecter la bibliothèque de tracing dans votre application. Consultez la page Injecter des bibliothèques pour obtenir des instructions.

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.

Variable d’environnementPropriété systèmeDescription
DD_ENVdd.envL’environnement de votre application (production, staging, etc.).
DD_SERVICEdd.serviceLe nom d’un ensemble de processus qui effectuent la même tâche. Utilisé pour regrouper les statistiques de votre application.
DD_VERSIONdd.versionLa version de votre application (par exemple : 2.5, 202003181415, 1.3-alpha, etc.).
DD_PROFILING_ENABLEDdd.profiling.enabledActive le Profleur en continu
DD_LOGS_INJECTIONdd.logs.injectionActive l’injection automatique des clés MDC pour les ID de span et de trace Datadog. Consultez la section Utilisation avancée pour en savoir plus.
DD_TRACE_SAMPLE_RATEdd.trace.sample.rateDéfinit un taux d’échantillonnage à la racine de la trace pour tous les services.
DD_TRACE_SAMPLING_RULESdd.trace.sampling.rulesDéfinit un taux d’échantillonnage à la racine de la trace pour les services qui correspondent à la règle spécifiée.

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 :

Si votre application s’appelle my_app.jar, créez un fichier my_app.conf, contenant :

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

Pour en savoir plus, consultez la documentation de Spring Boot.

Ouvrez votre fichier de script de démarrage Tomcat, par exemple setenv.sh sous Linux, et ajoutez :

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

Sous Windows, il s’agit du fichier setenv.bat :

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

Si vous ne disposez pas de fichier setenv, créez-le dans le répertoire ./bin du dossier de projet Tomcat.

  • En mode autonome :

    Ajoutez la ligne suivante à la fin de standalone.conf :

JAVA_OPTS="$JAVA_OPTS -javaagent:/chemin/vers/dd-java-agent.jar"
  • En mode autonome et sur Windows, ajoutez la ligne suivante à la fin de standalone.conf.bat :
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/chemin/vers/dd-java-agent.jar"
  • En mode domaine :

    Ajoutez la ligne suivante dans le fichier domain.xml, sous le tag server-groups.server-group.jvm.jvm-options :

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

Pour en savoir plus, consultez la documentation de JBoss.

Si vous utilisez jetty.sh pour démarrer Jetty en tant que service, ajoutez ce qui suit :

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

Si vous utilisez start.ini pour démarrer Jetty, ajoutez la ligne suivante (sous --exec, ou ajoutez la ligne --exec si elle n’est pas présente) :

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

Dans la console d’administration :

  1. Sélectionnez Servers. Sous Server Type, sélectionnez WebSphere application servers et choisissez votre serveur.
  2. Sélectionnez Java and Process Management > Process Definition.
  3. Dans la section Additional Properties, cliquez sur Java Virtual Machine.
  4. Dans le champ de texte Generic JVM arguments, saisissez :
-javaagent:/chemin/vers/dd-java-agent.jar

Pour plus d’informations et d’options, consultez la documentation relative à WebSphere.

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