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. À compter 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 par le traceur et le profileur Java. Pour obtenir la liste complète des bibliothèques prises en charge, consultez la page Exigences de compatibilité.

La configuration du tracing implique de configurer le Profileur en continu. Il vous suffit ensuite d’activer le Profileur pour commencer à recevoir les données de profiling depuis votre application.

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.

Installation de Java

Sinon, pour commencer à tracer vos applications :

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

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

    Pour accéder à une version spécifique du traceur, consultez le référentiel Maven de Datadog.

  2. Pour exécuter votre application à partir d’un EDI, d’un script d’application Maven ou Gradle, ou de la commande java -jar, avec le profileur en continu, le suivi des déploiements, l’injection de logs (si vous envoyez des logs à Datadog) et le contrôle des volumes de traces, 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.trace.sample.rate=1 -Ddd.service=my-app -Ddd.env=staging -jar path/to/your/app.jar -Ddd.version=1.0
    

    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_SERVICE_RULESdd.trace.sampling.service.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.

  1. Assurez-vous que l’Agent Datadog est configuré pour l’APM et que votre application peut y accéder en suivant les instructions propres à votre environnement ci-dessous.

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

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.

Remarque : si vous utilisez les propriétés système du traceur Java, assurez-vous de les spécifier avant -jar, afin qu’elles soient lues en tant qu’options JVM.

dd.service
Variable d’environnement : DD_SERVICE
Valeur par défaut : unnamed-java-app
Le nom d’un ensemble de processus qui effectuent la même tâche. Utilisé pour regrouper les statistiques de votre application. Disponible à partir de la version 0.50.0.
dd.tags
Variables d’environnement : DD_TAGS
Valeur par défaut : null
Exemple : layer:api,team:intake
La liste des tags par défaut à ajouter à chaque span, profil et métrique JMX. Si la variable DD_ENV ou DD_VERSION est utilisée, tout tag « env » ou « version » défini dans DD_TAGS est remplacé. Disponible à partir de la version 0.50.0.
dd.env
Variable d’environnement : DD_ENV
Valeur par défaut : none
L’environnement de votre application (par exemple, production ou staging). Disponible à partir de la version 0.48.
dd.version
Variable d’environnement : DD_VERSION
Valeur par défaut : null
La version de votre application (par exemple, 2.5, 202003181415 ou 1.3-alpha). Disponible à partir de la version 0.48.
dd.logs.injection
Variable d’environnement : DD_LOGS_INJECTION
Valeur par défaut : true
Active 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.config
Variable d’environnement : DD_TRACE_CONFIG
Valeur par défaut : null
Le chemin 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.service=<NOM_SERVICE>.
dd.service.mapping
Variable d’environnement : DD_SERVICE_MAPPING
Valeur par défaut : null
Exemple : mysql:my-mysql-service-name-db, postgres:my-postgres-service-name-db
Renomme de façon dynamique les services via la configuration. Sert notamment à s’assurer que les bases de données possèdent des noms distincts d’un service à l’autre.
dd.writer.type
Variable d’environnement : DD_WRITER_TYPE
Valeur par défaut : DDAgentWriter
La 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.host
Variable d’environnement : DD_AGENT_HOST
Valeur par défaut : localhost
Le hostname vers lequel envoyer les traces. Si vous utilisez un environnement conteneurisé, configurez cette option sur l’IP du host. Consultez la section Tracer des applications Docker pour en savoir plus.
dd.trace.agent.port
Variable d’environnement : DD_TRACE_AGENT_PORT
Valeur par défaut : 8126
Le numéro du port sur lequel l’Agent effectue son écoute pour le host configuré.
dd.trace.agent.unix.domain.socket
Variable d’environnement : DD_TRACE_AGENT_UNIX_DOMAIN_SOCKET
Valeur par défaut : null
Permet de faire passer des données de tracing par un proxy en vue de leur envoi vers un Agent Datadog distant.
dd.trace.agent.url
Variable d’environnement : DD_TRACE_AGENT_URL
Valeur par défaut : null
L’URL vers laquelle envoyer les traces. Elle peut commencer par http:// pour une connexion via HTTP ou par unix:// pour connexion via un socket de domaine Unix. Une fois cette option définie, elle a la priorité sur DD_AGENT_HOST et DD_TRACE_AGENT_PORT. Disponible à partir de la version 0.65.
dd.trace.agent.timeout
Variable d’environnement : DD_TRACE_AGENT_TIMEOUT
Valeur par défaut : 10
Le délai d’expiration en secondes pour les interactions réseau avec l’Agent Datadog.
dd.trace.header.tags
Variable d’environnement : DD_TRACE_HEADER_TAGS
Valeur par défaut : null
Exemple : CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
Accepte une liste des correspondances entre les clés d’en-tête (insensibles à la casse) et les noms de tag et applique automatiquement les valeurs d’en-tête correspondantes en tant que tags sur les traces. Accepte également les entrées sans nom de tag qui sont automatiquement mis en correspondance avec des tags au format http.request.headers.<nom_en-tête> et http.response.headers.<nom_en-tête>, respectivement.

Jusqu’à la version 0.96.0, ce paramètre s’appliquait uniquement aux tags des en-têtes de requête. Pour revenir à l’ancien comportement, ajoutez le paramètre -Ddd.trace.header.tags.legacy.parsing.enabled=true ou la variable d’environnement DD_TRACE_HEADER_TAGS_LEGACY_PARSING_ENABLED=true.
dd.trace.request_header.tags
Variable d’environnement : DD_TRACE_REQUEST_HEADER_TAGS
Valeur par défaut : null
Exemple : CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
Accepte une liste des correspondances entre les clés d’en-tête (insensibles à la casse) et les noms de tag et applique automatiquement les valeurs d’en-tête de requête correspondantes en tant que tags sur les traces. Accepte également les entrées sans nom de tag qui sont automatiquement mis en correspondance avec des tags au format http.request.headers.<nom_en-tête>.
Disponible à partir de la version 0.96.0.
dd.trace.response_header.tags
Environment Variable: DD_TRACE_RESPONSE_HEADER_TAGS
Default: null
Example: CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
Accepte une liste des correspondances entre les clés d’en-tête (insensibles à la casse) et les noms de tag et applique automatiquement les valeurs d’en-tête de réponse correspondantes en tant que tags sur les traces. Accepte également les entrées sans nom de tag qui sont automatiquement mis en correspondance avec des tags au format http.response.headers.<nom_en-tête>.
Disponible à partir de la version 0.96.0.
dd.trace.annotations
Variable d’environnement : DD_TRACE_ANNOTATIONS
Valeur par défaut : (répertoriée sur cette page)
Exemple : com.some.Trace;io.other.Trace
Une liste des annotations de méthode à traiter en tant que @Trace.
dd.trace.methods
Variable d’environnement : DD_TRACE_METHODS
Valeur par défaut : null
Exemple : package.ClassName[method1,method2,...];AnonymousClass$1[call];package.ClassName[*]
La liste des classes/interfaces et méthodes à tracer. Semblable à l’ajout de @Trace, mais sans changer le code. Remarque : l’utilisation d’un wildcard ([*]) ne prend pas en compte les appels de méthode constructors, getters, setters, synthetic, toString, equals, hashcode ou finalizer.
dd.trace.classes.exclude
Variable d’environnement : DD_TRACE_CLASSES_EXCLUDE
Valeur par défaut : null
Exemple : package.ClassName,package.ClassName$Nested,package.Foo*,package.other.*
Une liste de noms de classe complets (pouvant se terminer par un wildcard pour spécifier un préfixe) qui seront ignorés (non modifiés) par le traceur. Ces noms doivent correspondre à la représentation interne JVM (ex. : package.ClassName$Nested et non package.ClassName.Nested).
dd.trace.partial.flush.min.spans
Variable d’environnement : DD_TRACE_PARTIAL_FLUSH_MIN_SPANS
Valeur par défaut : 1000
Dé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.split-by-tags
Variable d’environnement : DD_TRACE_SPLIT_BY_TAGS
Valeur par défaut : null
Exemple : aws.service
Utilisé pour renommer le service associé aux spans à identifier avec le tag de span correspondant.
dd.trace.db.client.split-by-instance
Variable d’environnement : DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE
Valeur par défaut : false
Lorsque 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.enabled
Variable d’environnement : DD_TRACE_HEALTH_METRICS_ENABLED
Valeur par défaut : false
Lorsque cette option est définie sur true, des métriques de santé sur le traceur sont envoyées.
dd.trace.health.metrics.statsd.host
Variable d’environnement : DD_TRACE_HEALTH_METRICS_STATSD_HOST
Valeur par défaut : identique à dd.jmxfetch.statsd.host
Le host Statsd vers lequel envoyer les métriques de santé.
dd.trace.health.metrics.statsd.port
Variable d’environnement : DD_TRACE_HEALTH_METRICS_STATSD_PORT
Valeur par défaut : identique à dd.jmxfetch.statsd.port
Le port Statsd vers lequel envoyer les métriques de santé.
dd.http.client.tag.query-string
Variable d’environnement : DD_HTTP_CLIENT_TAG_QUERY_STRING
Valeur par défaut : false
Lorsque 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.statuses
Variable d’environnement : DD_HTTP_CLIENT_ERROR_STATUSES
Valeur par défaut : 400-499
Permet de définir une plage d’erreurs à accepter. Par défaut, les erreurs 4xx sont signalées comme des erreurs pour les clients http. Cette option remplace ce comportement. Exemple : dd.http.client.error.statuses=400-403,405,410-499.
dd.http.server.error.statuses
Variable d’environnement : DD_HTTP_SERVER_ERROR_STATUSES
Valeur par défaut : 500-599
Permet de définir une plage d’erreurs à accepter. Par défaut, les codes de statut 5xx sont signalés comme des erreurs pour les serveurs http. Cette option remplace ce comportement. Exemple : dd.http.server.error.statuses=500,502-599.
dd.http.server.tag.query-string
Variable d’environnement : DD_HTTP_SERVER_TAG_QUERY_STRING
Valeur par défaut : false
Lorsque 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.trace.enabled
Variable d’environnement : DD_TRACE_ENABLED
Valeur par défaut : true
Lorsque cette option est définie sur false, l’Agent de tracing est désactivé.
dd.jmxfetch.enabled
Variable d’environnement : DD_JMXFETCH_ENABLED
Valeur par défaut : true
Active la collecte de métriques JMX par l’Agent de tracing Java.
dd.jmxfetch.config.dir
Variable d’environnement : DD_JMXFETCH_CONFIG_DIR
Valeur par défaut : null
Exemple : /path/to/directory/etc/conf.d
Le 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.config
Variable d’environnement : DD_JMXFETCH_CONFIG
Valeur par défaut : null
Exemple : path/to/file/conf.yaml,other/path/to/file/conf.yaml
Le 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-period
Variable d’environnement : DD_JMXFETCH_CHECK_PERIOD
Valeur par défaut : 1500
La fréquence d’envoi des métriques JMX (en ms).
dd.jmxfetch.refresh-beans-period
Variable d’environnement : DD_JMXFETCH_REFRESH_BEANS_PERIOD
Valeur par défaut : 600
La fréquence d’actualisation de la liste des beans JMX disponibles (en secondes).
dd.jmxfetch.statsd.host
Variable d’environnement : DD_JMXFETCH_STATSD_HOST
Valeur par défaut : identique à agent.host
Le host Statsd vers lequel envoyer les métriques JMX. Si vous utilisez des sockets de domaine Unix, utilisez un argument tel que ‘unix://CHEMIN_VERS_SOCKET_UDS’. Exemple : unix:///var/datadog-agent/dsd.socket.
dd.jmxfetch.statsd.port
Variable d’environnement : DD_JMXFETCH_STATSD_PORT
Valeur par défaut : 8125
Le port StatsD vers lequel envoyer les métriques JMX. Si vous utilisez des sockets de domaine Unix, saisissez 0.
dd.integration.opentracing.enabled
Variable d’environnement : DD_INTEGRATION_OPENTRACING_ENABLED
Valeur par défaut : true
Par défaut, le client de tracing détecte si un GlobalTracer est en cours de chargement et enregistre un traceur dans celui-ci de manière dynamique. En définissant cette option sur false, toute dépendance entre le traceur et OpenTracing est supprimée.
dd.hystrix.tags.enabled
Variable d’environnement : DD_HYSTRIX_TAGS_ENABLED
Valeur par défaut : false
Par défaut, les tags associés au groupe, à la commande et au statut du circuit Hystrix sont désactivés. Cette option permet de les activer.
dd.trace.servlet.async-timeout.error
Variable d’environnement : DD_TRACE_SERVLET_ASYNC_TIMEOUT_ERROR
Valeur par défaut : true
Par défaut, les requêtes asynchrones à exécution longue sont considérées comme des erreurs. Lorsque cette valeur est définie sur false, toutes les requêtes ayant expiré sont considérées comme réussies.
dd.trace.startup.logs
Variable d’environnement : DD_TRACE_STARTUP_LOGS
Valeur par défaut : true
Lorsque cette option est définie sur false, les logs de lancement informatifs sont désactivés. Disponible à partir de la version 0.64.
dd.trace.servlet.principal.enabled
Variable d’environnement : DD_TRACE_SERVLET_PRINCIPAL_ENABLED
Valeur par défaut : false
Lorsque cette option est définie sur true, l’objet principal utilisateur est recueilli. Disponible à partir de la version 0.61.

Remarques :

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
mapping de service

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
tags globaux de trace

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
tags de span de trace

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
tags JMX de trace

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
méthodes à tracer

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 :

instance 1

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 :

instance 2

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
chaîne de requête

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 :

exemple JMXFetch

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 traces

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.

Performance

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

Pour aller plus loin