Tracer des applications Java

Exigences de compatibilité

La bibliothèque de tracing Java prend en charge toutes les JVM sur toutes les plateformes à partir de la version 7. Pour tirer parti du tracing avec le Profileur en continu, OpenJDK 11+, Oracle Java 11+, OpenJDK 8 pour la plupart des fournisseurs (version 8u262+) et Zulu Java 8+ (version mineure 1.8.0_212+) sont pris en charge. À partir de la version 8u272+, tous les fournisseurs seront pris en charge pour le profileur.

Tous les langages basés sur la JVM, tels que Scala (versions 2.10.x à 2.13.x), Groovy, Kotlin, ou encore Clojure sont pris en charge. Pour obtenir la liste complète des bibliothèques prises en charge, consultez la page Exigences de compatibilité.

Installation et démarrage

Suivre la documentation intégrée à 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.

Étapes d’installation Java

Sinon, pour commencer le tracing d’applications écrites dans n’importe quel langage :

1. Téléchargez dd-java-agent.jar, qui contient les fichiers de classe de l’Agent :

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

2. Ajoutez l’argument JVM suivant lors du démarrage de votre application dans votre script d’application IDE, Maven ou Gradle, ou la commande java -jar :

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

3. Ajoutez des options de configuration pour le tracing et assurez-vous de définir les variables d’environnement ou de passer les propriétés système en tant qu’arguments JVM, en particulier pour les métriques de service, d’environnement, d’injection de logs, de profiling et éventuellement les métriques runtime (toutes les métriques que vous avez l’intention d’utiliser). Consultez les exemples ci-dessous. Notez que si vous utilisez les instructions Quickstart intégrées à l’application, ces options seront générées pour vous.

Configurer l’Agent Datadog pour 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_enabled: true, et écoute le trafic des traces sur 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.

• Dropdown

1. Définissez apm_non_local_traffic: true dans 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 que vous avez instrumenté votre application, le client de tracing envoie, par défaut, les traces à localhost:8126. S’il ne s’agit pas du host et du port adéquats, modifiez-les en définissant les variables d’environnement ci-dessous :

DD_AGENT_HOST et DD_TRACE_AGENT_PORT.

java -javaagent:<CHEMIN-AGENT-JAVA-DD>.jar -jar <CHEMIN_VOTRE_APPLICATION>.jar

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

java -javaagent:<CHEMIN-AGENT-JAVA-DD>.jar \
     -Ddd.agent.host=$DD_AGENT_HOST \
     -Ddd.agent.port=$DD_TRACE_AGENT_PORT \
     -jar <CHEMIN_VOTRE_APPLICATION>.jar

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 l'extension Azure App Services.

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

Ajouter le traceur Java à la JVM

Consultez la documentation de votre IDE pour savoir 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_OPTS=%CATALINA_OPTS_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"

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.

• 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 possède la capacité de modifier les fichiers de classe durant le chargement.

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 nanoseconde 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

Toutes les options de configuration ci-dessous ont une propriété système et une variable d’environnement équivalentes. Si le même type de clé est défini pour les deux, la configuration de la propriété système est prioritaire. Les propriétés système peuvent être définies en tant que flags JVM.

Remarques :

• Si le même type de clé est défini pour les deux, la configuration de la propriété système est prioritaire.

• Les propriétés système peuvent être utilisées comme paramètres JVM.

• Par défaut, les métriques JMX de votre application sont envoyées à l’Agent Datadog via DogStatsD sur le port 8125. Vérifiez que DogStatsD est activé pour l’Agent.

  • Si vous exécutez l’Agent en tant que conteneur, vérifiez que DD_DOGSTATSD_NON_LOCAL_TRAFFIC est définie sur true et que le port 8125 est ouvert sur le conteneur de l’Agent.
  • Dans Kubernetes, liez le port DogStatsD à un port de host ; dans ECS, définissez les flags adéquats dans la définition de votre tâche.

Intégrations

Pour découvrir comment désactiver des intégrations, consultez la section relative à la compatibilité des intégrations.

Exemples

dd.service.mapping

Exemple avec une propriété système :

java -javaagent:/chemin/vers/dd-java-agent.jar -Ddd.service=web-app -Ddd.service.mapping=postgresql:web-app-pg -jar chemin/vers/application.jar

dd.tags

Configuration d’un environnement global pour les spans et les métriques JMX :

java -javaagent:/chemin/vers/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -jar chemin/vers/application.jar

dd.trace.span.tags

Exemple d’ajout de project:test à chaque span :

java -javaagent:/chemin/vers/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.trace.span.tags=project:test -jar chemin/vers/application.jar

dd.trace.jmx.tags

Définition de custom.type:2 sur une métrique JMX :

java -javaagent:/chemin/vers/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.trace.span.tags=project:test -Ddd.trace.jmx.tags=custom.type:2 -jar chemin/vers/application.jar

dd.trace.methods

Exemple avec une propriété système :

java -javaagent:/chemin/vers/agent-java-dd.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.trace.methods="hello.GreetingController[doSomeStuff,doSomeOtherStuff];hello.Randomizer[randomize]" -jar chemin/vers/application.jar

dd.trace.db.client.split-by-instance

Exemple avec une propriété système :

java -javaagent:/chemin/vers/dd-java-agent.jar -Ddd.env=dev -Ddd.service=web-app -Ddd.trace.db.client.split-by-instance=TRUE -jar chemin/vers/application.jar

L’instance de base de données 1, webappdb, possède désormais son propre nom de service, le même que celui indiqué dans les métadonnées de span db.instance :

L’instance de base de données 2, secondwebappdb, possède désormais son propre nom de service, le même que celui indiqué dans les métadonnées de span db.instance :

De même, sur la service map, une app Web appelle désormais deux bases de données Postgres distinctes.

dd.http.server.tag.query-string

Exemple avec une propriété système :

java -javaagent:/chemin/vers/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.http.server.tag.query-string=TRUE -jar chemin/vers/application.jar

dd.trace.enabled

Exemple avec une propriété système et le mode debugging d’app

java -javaagent:/chemin/vers/agent-java-dd.jar -Ddd.trace.enabled=false -Ddatadog.slf4j.simpleLogger.defaultLogLevel=debug -jar chemin/vers/application.jar

Les logs de debugging d’app indiquent, avec le message Tracing is disabled, not installing instrumentations, que le tracing est désactivé et qu’aucune instrumentation n’est en cours d’installation.

dd.jmxfetch.config.dir et dd.jmxfetch.config

Exemple de configuration :

• Combinaison DD_JMXFETCH_CONFIG_DIR=<CHEMIN_RÉPERTOIRE> + DD_JMXFETCH_CONFIG=conf.yaml
• Ou directement avec DD_JMXFETCH_CONFIG=<CHEMIN_RÉPERTOIRE>/conf.yaml

Avec le contenu suivant pour conf.yaml :

init_config:
instances:
    - jvm_direct: true
      port: '<PORT>'
      conf:
          - include:
                bean:
                    - java.lang:type=MemoryPool,name=Metaspace
                attribute:
                    Usage.used:
                        metric_type: gauge
                        alias: sb.usage.used

On obtient le résultat suivant :

Consultez la documentation relative à l’intégration Java pour en savoir plus sur la collecte de métriques Java avec JMXFetch.

Extraction et injection d’en-têtes B3

Le traceur de l’APM Datadog prend en charge l’extraction et l’injection d’en-têtes B3 pour le tracing distribué.

L’injection et l’extraction distribuées d’en-têtes sont contrôlées en configurant des styles d’injection/extraction. Deux styles sont actuellement pris en charge :

• Datadog : Datadog
• B3 : B3

Les styles d’injection peuvent être configurés via :

• Propriété système : -Ddd.propagation.style.inject=Datadog,B3
• Variable d’environnement : DD_PROPAGATION_STYLE_INJECT=Datadog,B3

La propriété ou la variable d’environnement prend pour valeur une liste de styles d’en-tête séparés par des virgules (ou des espaces) qui sont activés pour l’injection. Par défaut, seul le style d’injection Datadog est activé.

Les styles d’extraction peuvent être configurés via :

• Propriété système : -Ddd.propagation.style.extract=Datadog,B3
• Variable d’environnement : DD_PROPAGATION_STYLE_EXTRACT=Datadog,B3

La propriété ou la variable d’environnement prend pour valeur une liste de styles d’en-tête séparés par des virgules (ou des espaces) qui sont activés pour l’extraction. Par défaut, seul le style d’extraction Datadog est activé.

Si plusieurs styles d’extraction sont activés, une tentative d’extraction est effectuée dans l’ordre selon lequel ces styles ont été configurés, et la première valeur extraite avec succès est utilisée.

Transmission de traces

Voici à quoi ressemble le processus de transmission de trace à Datadog :

• La trace est recueillie.
• La trace est transférée dans une file d’attente asynchrone de traces.
  • La file d’attente présente une limite fixe de 7 000 traces.
  • Une fois la limite atteinte, les traces sont supprimées.
  • Le nombre total de traces est capturé pour assurer l’intégrité des données.
• Dans un thread de transmission distinct, la file d’attente de traces est vidée et les traces sont codées via msgpack, puis envoyées à l’Agent Datadog via http.
• La file d’attente est vidée toutes les secondes.

Pour voir le code utilisé, la documentation ou des exemples d’utilisation des bibliothèques et frameworks pris en charge par Datadog, consultez la liste complète des composants à instrumentation automatique pour les applications Java dans la section Intégrations.

Annotation de trace

Ajoutez la dépendance dd-trace-api à votre projet. Pour Maven, ajoutez ce qui suit à pom.xml :

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>dd-trace-api</artifactId>
    <version>{version}</version>
</dependency>

Pour Gradle, ajoutez :

implementation group: 'com.datadoghq', name: 'dd-trace-api', version: {version}

Ajoutez maintenant @Trace aux méthodes pour permettre leur tracing lors d’une exécution avec dd-java-agent.jar. Si l’Agent n’est pas associé, cette annotation n’a aucun effet sur votre application.

Les annotations @Trace prennent le nom d’opération par défaut trace.annotation, tandis que la méthode tracée prend la ressource par défaut.

Performances

L’APM Java a un impact minimal sur la charge d’une application :

• Toutes les collectes assurées par l’APM Java sont soumises à des limites de mémoire
• La transmission de traces ne bloque pas le thread de l’application
• L’APM Java charge des classes supplémentaires pour la collecte de traces et l’instrumentation de la bibliothèque
• L’APM Java entraîne généralement une augmentation de la charge processeur inférieure à 3 %
• L’APM Java entraîne généralement une augmentation de la charge mémoire de JVM inférieure à 3 %

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

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