Nouvelles annonces sur les technologies sans serveur et réseau ainsi que sur le RUM (Real-User Monitoring) dévoilées à la conférence Dash ! Nouvelles annonces dévoilées à la conférence Dash !

Tracer des applications Java

Installation et démarrage

Si vous avez déjà un compte Datadog, vous trouverez des instructions détaillées dans nos guides intégrés à l'application pour les configurations basées sur un host et les configurations basées sur un conteneur.

Pour commencer le tracing d’applications écrites dans n’importe quel langage, vous devez d’abord installer et configurer l’Agent Datadog. Pour obtenir davantage d’informations, consultez la documentation relative au tracing d’applications Docker ou au tracing d’applications Kubernetes.

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

wget -O dd-java-agent.jar 'https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.datadoghq&a=dd-java-agent&v=LATEST'

Enfin, vous devez ajouter 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:/chemin/vers/l/agent/java-dd.jar

Remarque :

  • Le -javaagent doit être exécuté avant le fichier -jar en l’ajoutant en tant qu’option JVM et non en tant qu’argument d’application. Pour en savoir plus, consultez la documentation Oracle.

  • Les artefacts de dd-trace-java (dd-java-agent.jar, dd-trace-api.jar, dd-trace-ot.jar) prennent en charge tous les langages basés sur JVM, tels que Scala, Groovy, Kotlin, Clojure, etc. Si vous avez besoin d’utiliser un framework spécifique, pensez à effectuer une contribution open source.

Instrumentation automatique

L’instrumentation automatique pour Java utilise les fonctionnalités d’instrumentation java-agent fournies par JVM. Lorsqu’un java-agent est enregistré, celui-ci a la capacité de modifier les fichiers de classe durant le chargement. Le java-agent utilise le framework Byte Buddy pour trouver les classes définies pour l’instrumentation et modifier ces octets de classe en conséquence.

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 JVM, sauf si un horodatage est fourni à partir de l’API OpenTracing
  • Les paires de tags clé/valeur
  • Les erreurs et les traces de pile non gérées par l’application
  • Le nombre total de traces (requêtes) transmises via le système

Compatibilité

Datadog prend officiellement en charge l’environnement Java JRE 1.7 et versions ultérieures d’Oracle JDK et OpenJDK. Datadog ne prend pas officiellement en charge toute version de Java en accès anticipé.

Intégrations

La plupart des intégrations sont activées par défaut. Le paramètre suivant peut être utilisé pour les désactiver par défaut.

  • Propriété système : -Ddd.integrations.enabled=false
  • Variable d’environnement : DD_INTEGRATIONS_ENABLED=false

Les intégrations peuvent être activées ou désactivées individuellement (ce qui remplace le paramètre par défaut ci-dessus).

  • Propriété système : -Ddd.integration.<integration-name>.enabled=true
  • Variable d’environnement : DD_INTEGRATION_<NOM_INTÉGRATION>_ENABLED=true

(Le nom de chaque intégration est affiché ci-dessous.)

Les intégrations bêta sont désactivées par défaut, mais peuvent être activées individuellement.

Compatibilité des frameworks Web

dd-java-agent prend en charge le tracing automatique des frameworks Web suivants :

ServeurVersionsType de prise en chargeNoms des instrumentations (utilisés pour la configuration)
Serveur Akka-Http10.0+Prise en charge complèteakka-http, akka-http-server
Grizzly2.0+Bêtagrizzly
Servlet Java compatible2.3+, 3.0+Prise en charge complèteservlet, servlet-2, servlet-3
Annotations Jax-RSJSR311-APIPrise en charge complètejax-rs, jaxrs, jax-rs-annotations
Jetty (hors servlet)8+Bêtajetty, jetty-8
Netty HTTP Server4.0+Prise en charge complètenetty, netty-4.0, netty-4.1
Play2.4-2.7Prise en charge complèteplay
Ratpack1.4+Prise en charge complèteratpack
Spark Java2.3+Bêtasparkjava (nécessite jetty)
Spring Web (MVC)4.0+Prise en charge complètespring-web
Spring WebFlux5.0+Prise en charge complètespring-webflux

Le tracing de frameworks Web permet : le calcul du délai entre la requête HTTP et la réponse, l’application de tags à la requête HTTP (code de statut, méthode, etc.), la capture des erreurs et des traces de pile, la mise en corrélation des requêtes Web avec les opérations en backend ainsi que la mise en place d’un tracing distribué.

Remarque : de nombreux serveurs d’applications sont compatibles avec les servlets et sont automatiquement couverts par cette instrumentation. C’est le cas de Tomcat, Jetty, Websphere, Weblogic, etc. En outre, certains frameworks comme Spring Boot sont automatiquement pris en charge car ils utilisent généralement un serveur d’applications intégré compatible avec les servlets (Tomcat/Jetty/Netty).

Les instrumentations en version bêta sont désactivées par défaut. Pour les activer, ajoutez l’une des configurations suivantes : * Propriété système : -Ddd.integration.<nom-intégration>.enabled=true * Variable d’environnement : DD_INTEGRATION_<NOM_INTÉGRATION>_ENABLED=true

Vos frameworks Web préférés ne sont pas disponibles ? Datadog élargit continuellement la liste des frameworks pris en charge. Contactez l’assistance Datadog si vous avez besoin d’aide.

Compatibilité des frameworks réseau

dd-java-agent prend en charge le tracing automatique des frameworks réseau suivants :

FrameworkVersionsType de prise en chargeNoms des instrumentations (utilisés pour la configuration)
Apache HTTP Client4.0+Prise en charge complètehttpclient
Apache HTTP Async Client4.0+Prise en charge complètehttpasyncclient, apache-httpasyncclient
Kit de développement Java AWS1.11+, 2.2+Prise en charge complèteaws-sdk
Google HTTP Client1.19.0+Prise en charge complètegoogle-http-client
gRPC1.5+Prise en charge complètegrpc, grpc-client, grpc-server
HttpURLConnectionToutesPrise en charge complètehttpurlconnection, urlconnection
Clients Kafka0.11+Prise en charge complètekafka
Kafka Streams0.11+Prise en charge complètekafka, kafka-streams
Clients Jax RS2.0+Prise en charge complètejax-rs, jaxrs, jax-rs-client
Jersey Client1.9+Prise en charge complètejax-rs, jaxrs, jax-rs-client
JMS1 et 2Prise en charge complètejms
Netty HTTP Client4.0+Prise en charge complètenetty, netty-4.0, netty-4.1
OkHTTP3.0+Prise en charge complèteokhttp, okhttp-3
Play WSClient1.0+Prise en charge complèteplay-ws
Rabbit AMQP2.7+Prise en charge complèteamqp, rabbitmq
Spring WebClient5.0+Prise en charge complètespring-webflux, spring-webflux-client

Le tracing de frameworks réseau permet : le calcul du délai entre la requête et la réponse, l’application de tags à la requête (par exemple le code de réponse), la capture des erreurs et des traces de pile, ainsi que la mise en place d’un tracing distribué.

Votre framework réseau préféré n’est pas disponible ? Datadog élargit continuellement la liste des frameworks pris en charge. Contactez l’assistance Datadog si vous avez besoin d’aide.

Compatibilité des datastores

dd-java-agent prend en charge le tracing automatique des frameworks/pilotes de base de données suivants :

Base de donnéesVersionsType de prise en chargeNoms des instrumentations (utilisés pour la configuration)
Couchbase2.0+Prise en charge complètecouchbase
Cassandra3.XPrise en charge complètecassandra
Elasticsearch Transport2.0+Prise en charge complèteelasticsearch, elasticsearch-transport, elasticsearch-transport-{2,5,6} (choisissez-en un)
Elasticsearch Rest5.0+Prise en charge complèteelasticsearch, elasticsearch-rest, elasticsearch-rest-5, elasticsearch-rest-6
JDBCS. O.Prise en charge complètejdbc
Jedis1.4+Prise en charge complèteredis
Lettuce5.0+Prise en charge complètelettuce
MongoDB3.0+Prise en charge complètemongo
SpyMemcached2.12+Prise en charge complètespymemcached

dd-java-agent est également compatible avec les pilotes JDBC courants, notamment :

  • Apache Derby
  • Firebird SQL
  • Moteur de base de données H2
  • HSQLDB
  • IBM DB2
  • MariaDB
  • MSSQL (Microsoft SQL Server)
  • MySQL
  • Oracle
  • Postgres SQL

Le tracing de datastores permet : le calcul du délai entre la requête et la réponse, la récupération des informations sur la requête (par exemple, la chaîne de requête expurgée) ainsi que la capture des erreurs et des traces de pile.

Vos datastores préférés ne sont pas disponibles ? Datadog élargit continuellement la liste des datastores pris en charge. Contactez l’assistance Datadog si vous avez besoin d’aide.

Compatibilité avec les autres frameworks

dd-java-agent prend en charge le tracing automatique des frameworks suivants :

FrameworkVersionsType de prise en chargeNoms des instrumentations (utilisés pour la configuration)
Dropwizard Views0.7+Prise en charge complètedropwizard, dropwizard-view
Hibernate3.5+Prise en charge complètehibernate
Hystrix1.4+Prise en charge complètehystrix
JSP Rendering2.3+Prise en charge complètejsp, jsp-render
Slf4J MDC1+Prise en charge complètemdc (voir également la configuration dd.logs.injection)
Spring Data1.8+Prise en charge complètespring-data
Twilio SDK0+Prise en charge complètetwilio-sdk

Votre framework préféré n’est pas disponible ? Datadog élargit continuellement la liste des frameworks pris en charge. Contactez l’assistance Datadog si vous avez besoin d’aide.

Pour profiter d’une meilleure visibilité sur vos applications utilisant des frameworks non pris en charge, vous pouvez :

  • Ajouter une instrumentation personnalisée (avec OpenTracing ou l’annotation @Trace)
  • Envoyer une pull request avec l’instrumentation en vue de son ajout dans une version future
  • Contacter l’assistance Datadog et envoyer une demande d’ajout de fonctionnalité

Configuration

Le traceur est configuré à l’aide des propriétés système et des variables d’environnement comme suit : (Voir la configuration spécifique de l’intégration dans la section Intégrations ci-dessus.)

Propriété systèmeVariable d’environnementDefaultDescription
dd.trace.enabledDD_TRACE_ENABLEDtrueLorsque cette option est définie sur false, l’Agent est désactivé.
dd.trace.configDD_TRACE_CONFIGnullChemin facultatif vers un fichier où les propriétés de configuration sont définies (une par ligne). Le chemin du fichier peut par exemple être spécifié via -Ddd.trace.config=<CHEMIN_FICHIER>.properties, en définissant le nom du service dans le fichier avec dd.trace.enabled=<NOM_SERVICE>
dd.service.nameDD_SERVICE_NAMEunnamed-java-appLe nom d’un ensemble de processus qui effectuent la même tâche. Utilisé pour regrouper les statistiques de votre application.
dd.service.mappingDD_SERVICE_MAPPINGnull(Exemple : mysql:nom-du-service-db.) Renomme de façon dynamique les services via la configuration. Utile pour faire en sorte que les bases de données affichent des noms distincts d’un service à l’autre.
dd.writer.typeDD_WRITER_TYPEDDAgentWriterLa valeur par défaut active l’envoi des traces à l’Agent. Si vous utilisez LoggingWriter dans votre configuration, les traces sont écrites dans la console.
dd.agent.hostDD_AGENT_HOSTlocalhostHostname vers lequel envoyer les traces. Si vous utilisez un environnement conteneurisé, configurez cette propriété sur l’IP du host. Consultez la documentation relative au tracing d’applications Docker pour en savoir plus.
dd.trace.agent.portDD_TRACE_AGENT_PORT8126Numéro du port sur lequel l’Agent effectue son écoute pour le host configuré.
dd.trace.agent.unix.domain.socketDD_TRACE_AGENT_UNIX_DOMAIN_SOCKETnullPermet de faire passer des données de tracing par un proxy en vue de leur envoi vers un Agent Datadog distant.
dd.trace.global.tagsDD_TRACE_GLOBAL_TAGSnull(Exemple : key1:value1,key2:value2.) Une liste de tags par défaut à ajouter à chaque span et à chaque métrique JMX. Cette valeur est fusionnée dans trace.span.tags et trace.jmx.tags afin de configurer les deux depuis un seul emplacement.
dd.trace.span.tagsDD_TRACE_SPAN_TAGSnull(Exemple : key1:value1,key2:value2.) Une liste de tags par défaut à ajouter à chaque span. Les tags portant le même nom qui sont ajoutés directement à une span remplacent ceux par défaut fournis ici.
dd.trace.jmx.tagsDD_TRACE_JMX_TAGSnull(Exemple : key1:value1,key2:value2) La liste des tags par défaut à ajouter à chaque métrique JMX. Les tags portant le même nom qui sont ajoutés à la configuration de métriques JMX remplacent ceux par défaut fournis ici.
dd.trace.header.tagsDD_TRACE_HEADER_TAGSnull(Exemple : en-tête-insensible-CASSE:nom-du-tag,User-ID:userId.) Une liste des correspondances entre les clés d’en-tête et les noms de tag. Applique automatiquement des valeurs d’en-tête en tant que tags sur les traces.
dd.trace.annotationsDD_TRACE_ANNOTATIONS(liste disponible ici)(Exemple : com.some.Trace;io.other.Trace.) Une liste des annotations de méthode à traiter en tant que @Trace.
dd.trace.methodsDD_TRACE_METHODSnull(Exemple : package.ClassName[method1,method2…];AnonymousClass$1[call].) Liste des classes/interfaces et méthodes à tracer. Semblable à l’ajout de @Trace, mais sans changer le code.
dd.trace.partial.flush.min.spansDD_TRACE_PARTIAL_FLUSH_MIN_SPANS1000Définit le nombre de spans partielles à partir duquel celles-ci doivent être vidées. Permet de réduire la charge de la mémoire en cas de traitement d’un trafic important ou de traces à exécution longue.
dd.trace.report-hostnameDD_TRACE_REPORT_HOSTNAMEfalseLorsque cette option est activée, le hostname détecté est ajouté aux métadonnées de trace.
dd.trace.split-by-tagsDD_TRACE_SPLIT_BY_TAGSnull(Exemple : aws.service) Utilisé pour renommer les spans identifiées avec le tag de service correspondant
dd.trace.db.client.split-by-instanceDD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCEfalseLorsque cette option est définie sur true, les spans de base de données reçoivent le nom de l’instance en tant que nom du service.
dd.trace.health.metrics.enabledDD_TRACE_HEALTH_METRICS_ENABLEDfalseDéfinir sur true pour envoyer des métriques de santé du tracer
dd.trace.health.metrics.statsd.hostDD_TRACE_HEALTH_METRICS_STATSD_HOSTidentique à dd.jmxfetch.statsd.hostHost Statsd vers lequel envoyer les métriques de santé
dd.trace.health.metrics.statsd.portDD_TRACE_HEALTH_METRICS_STATSD_PORTidentique à dd.jmxfetch.statsd.portPort Statsd vers lequel envoyer les métriques de santé
dd.http.client.tag.query-stringDD_HTTP_CLIENT_TAG_QUERY_STRINGfalseLorsque cette option est définie sur true, les paramètres de chaîne de requête et le fragment sont ajoutés aux spans du client Web.
dd.http.client.error.statusesDD_HTTP_CLIENT_ERROR_STATUSESfalsePermet de définir une plage d’erreurs à accepter. Par défaut, les erreurs 4xx ne sont pas signalées comme des erreurs. Ce paramètre remplace ce comportement. Par exemple, dd.http.client.error.statuses=400-499
dd.http.server.tag.query-stringDD_HTTP_SERVER_TAG_QUERY_STRINGfalseLorsque cette option est définie sur true, les paramètres de chaîne de requête et le fragment sont ajoutés aux spans du serveur Web.
dd.jmxfetch.enabledDD_JMXFETCH_ENABLEDtrueActive la collecte de métriques JMX par l’agent de tracing Java.
dd.jmxfetch.config.dirDD_JMXFETCH_CONFIG_DIRnull(Exemple : /opt/datadog-agent/etc/conf.d) Répertoire de configuration supplémentaire pour la collecte de métriques JMX. L’Agent Java recherche jvm_direct:true dans la section instance du fichier yaml pour changer la configuration.
dd.jmxfetch.configDD_JMXFETCH_CONFIGnull(Exemple : activemq.d/conf.yaml, jmx.d/conf.yaml) Fichier de configuration de métriques supplémentaires pour la collecte de métriques JMX. L’Agent Java recherche jvm_direct:true dans la section instance du fichier yaml pour changer la configuration.
dd.jmxfetch.check-periodDD_JMXFETCH_CHECK_PERIOD1500Fréquence d’envoi des métriques JMX (en ms).
dd.jmxfetch.refresh-beans-periodDD_JMXFETCH_REFRESH_BEANS_PERIOD600Fréquence d’actualisation de la liste des beans JMX disponibles (en secondes).
dd.jmxfetch.statsd.hostDD_JMXFETCH_STATSD_HOSTidentique à agent.hostHost Statsd vers lequel envoyer les métriques JMX.
dd.jmxfetch.statsd.portDD_JMXFETCH_STATSD_PORT8125Port Statsd vers lequel envoyer les métriques JMX.
dd.logs.injectionDD_LOGS_INJECTIONfalseActive 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

Remarques :

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 d’en-têtes distribuées est contrôlée par la configuration 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_INJECTION=Datadog,B3

La valeur de la propriété ou de la variable d’environnement est 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 valeur de la propriété ou de la variable d’environnement est 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

Lors de la transmission d’une trace à Datadog, voici ce qui se produit :

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

compile 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 %

Modifier le hostname de l’Agent

Configurez vos traceurs d’applications de façon à envoyer des traces à un hostname d’Agent personnalisé :

Le module de tracing Java recherche automatiquement les variables ENV DD_AGENT_HOST et DD_TRACE_AGENT_PORT et s’initialise avec celles-ci.

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 aller plus loin