Le profileur est fourni dans les bibliothèques de tracing Datadog. Si vous utilisez déjà l’APM pour recueillir des traces pour votre application, vous pouvez ignorer l’installation de la bibliothèque et passer directement à l’activation du profileur.

Prérequis

Depuis la version 1.0.0 de dd-trace-java, vous avez le choix parmi deux moteurs pour générer des données sur les profils CPU pour les applications Java : le Java Flight Recorder (JFR) et le profileur Datadog. Depuis la version 1.7.0, le profileur Datadog est utilisé par défaut. Chaque moteur de profileur possède ses propres effets secondaires, exigences, configurations disponibles et limites. Cette page décrit les caractéristiques de chaque moteur. Vous pouvez activer l’un des moteurs ou les deux. Si vous activez les deux moteurs, vous enregistrerez simultanément les deux types de profils.

Tous les langages JVM, comme Java, Scala, Groovy, Kotlin et Clojure, sont pris en charge.

Le profileur en continu n’est pas pris en charge sur les plateformes sans serveur, comme AWS Lambda.

Installation

Pour commencer le profiling d’applications, procédez comme suit :

1. Si vous utilisez déjà Datadog, mettez à jour votre Agent vers la version 7.20.2+ ou 6.20.2+. Si l’APM n’est pas activée et que votre application n’est pas configurée pour envoyer des données à Datadog, dans votre Agent, définissez la variable d’environnement DD_APM_ENABLED sur true et le port d’écoute sur 8126/TCP.

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

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

   Remarque : le profileur est disponible dans la bibliothèque dd-java-agent.jar dans la version 0.55 et les versions ultérieures.

3. Définissez le flag -Ddd.profiling.enabled ou la variable d’environnement DD_PROFILING_ENABLED sur true pour activer le profileur. Spécifiez les paramètres dd.service, dd.env et dd.version pour pouvoir filtrer et regrouper vos profils en fonction de ces dimensions :

   Appelez votre service :

   java \
       -javaagent:dd-java-agent.jar \
       -Ddd.service=<VOTRE_SERVICE> \
       -Ddd.env=<VOTRE_ENVIRONNEMENT> \
       -Ddd.version=<VOTRE_VERSION> \
       -Ddd.profiling.enabled=true \
       -XX:FlightRecorderOptions=stackdepth=256 \
       -jar <VOTRE_SERVICE>.jar <VOS_FLAGS_DE_SERVICE>
   

   export DD_SERVICE=<VOTRE SERVICE>
   export DD_ENV=<VOTRE_ENVIRONNEMENT>
   export DD_VERSION=<VOTRE_VERSION>
   export DD_PROFILING_ENABLED=true
   java \
       -javaagent:dd-java-agent.jar \
       -XX:FlightRecorderOptions=stackdepth=256 \
       -jar <VOTRE_SERVICE>.jar <VOS_FLAGS_DE_SERVICE>
   

   Remarque : l’argument -javaagent doit figurer avant -jar et être ajouté en tant qu’option JVM et non en tant qu’argument d’application. Pour en savoir plus, consultez la documentation Oracle (en anglais) :

   # Correct :
   java -javaagent:dd-java-agent.jar ... -jar my-service.jar -more-flags
   # Incorrect :
   java -jar my-service.jar -javaagent:dd-java-agent.jar ...
   

4. Au bout d’une ou de deux minutes, vous pouvez visualiser vos profils en accédant à l’APM Datadog puis à la page Profiling.

Activer les options du moteur pour le profileur du CPU

Depuis la version 1.5.0 de dd-trace-java, vous pouvez choisir parmi deux profileurs pour le CPU : Datadog ou Java Flight Recorder (JFR). Depuis la version 1.7.0, le profileur Datadog est utilisé par défaut. Il est néanmoins également possible activer JFR pour le profiling du CPU. Vous pouvez activer l’un des moteurs ou les deux. Si vous activez les deux moteurs, vous enregistrerez simultanément les deux types de profils.

Le profileur Datadog enregistre la span active pour chaque échantillon, ce qui améliore la précision des fonctionnalités de profiling des hotspots de code et des endpoints. Une fois activé, ce moteur améliore significativement l’intégration du tracing APM.

Le profileur Datadog comprend plusieurs moteurs de profiling, notamment pour le CPU, le wall clock, les allocations et les fuites de données.

export DD_PROFILING_DDPROF_ENABLED=true # valeur par défaut pour les versions 1.7.0+
export DD_PROFILING_DDPROF_CPU_ENABLED=true

-Ddd.profiling.ddprof.enabled=true # valeur par défaut pour les versions 1.7.0+
-Ddd.profiling.ddprof.cpu.enabled=true

sudo sh -c 'echo 2 >/proc/sys/kernel/perf_event_paranoid'

export DD_PROFILING_DDPROF_CPU_ENABLED=false

-Ddd.profiling.ddprof.cpu.enabled=false

Moteur wall clock du profileur Datadog

Le moteur de profiling du wall clock permet d’effectuer le profiling des latences. Il s’intègre également parfaitement avec le tracing APM. Le moteur échantillonne tous les threads, sur le CPU ou en dehors, sur lesquels des activités de tracing sont en cours. Il permet également d’identifier la cause des latences au niveau des traces ou spans. Depuis la version 1.7.0, le moteur est activé par défaut.

ou :

-Ddd.profiling.ddprof.enabled=true # valeur par défaut pour les versions 1.7.0+
-Ddd.profiling.ddprof.wall.enabled=true

Pour les versions 1.7.0+, utilisez ce qui suit pour désactiver le profileur de wall clock :

export DD_PROFILING_DDPROF_WALL_ENABLED=false

ou :

-Ddd.profiling.ddprof.wall.enabled=false

Pour les utilisateurs de JMC, l’événement datadog.MethodSample est généré pour les échantillons de wall clock.

Le moteur de wall clock ne dépend pas du paramètre /proc/sys/kernel/perf_event_paranoid.

Moteur d’allocations du profileur Datadog

Le moteur de profiling d’allocations Datadog contextualise les profils d’allocation. Il prend en charge les profils d’allocation filtrés par endpoint. Pour les versions de dd-java-agent antérieures à la v1.17.0, le moteur est désactivé par défaut. Vous pouvez toutefois utiliser ce qui suit pour l’activer :

export DD_PROFILING_DDPROF_ENABLED=true # valeur par défaut pour les versions 1.7.0+
export DD_PROFILING_DDPROF_ALLOC_ENABLED=true # valeur par défaut pour les versions 1.17.0+

ou :

-Ddd.profiling.ddprof.enabled=true # valeur par défaut pour les versions 1.7.0+
-Ddd.profiling.ddprof.alloc.enabled=true # valeur par défaut pour les versions 1.17.0+

Pour les utilisateurs de JMC, les événements d’allocation Datadog sont datadog.ObjectAllocationInNewTLAB et datadog.ObjectAllocationOutsideTLAB.

Le moteur du profileur d’allocations ne répond pas du paramètre /proc/sys/kernel/perf_event_paranoid.

Moteur du profileur de mémoire dans le tas active

Depuis la version 1.17.0

Le moteur de profileur de mémoire dans le tas active permet d’étudier l’utilisation globale de la mémoire de votre service et d’identifier d’éventuelles fuites de mémoire. Le moteur échantillonne des allocations et vérifie si ces échantillons existent toujours après le dernier cycle de nettoyage de mémoire. Le nombre d’échantillons survivants permet d’estimer le nombre d’objets actifs dans le tas. Le nombre d’échantillons suivis est limité, afin d’éviter une augmentation illimitée de l’utilisation de la mémoire du profileur.

Ce moteur est désactivé par défaut, mais vous pouvez utiliser ce qui suit pour l’activer :

export DD_PROFILING_DDPROF_LIVEHEAP_ENABLED=true

ou :

-Ddd.profiling.ddprof.liveheap.enabled=true

Pour les utilisateurs de JMC, l’événement de mémoire dans le tas active Datadog est datadog.HeapLiveObject.

Le moteur d’allocations ne dépend pas du paramètre /proc/sys/kernel/perf_event_paranoid.

Collecte des stack traces natives

Si les moteurs de CPU ou wall clock du profileur Datadog sont activés, vous pouvez recueillir des stack traces natives. Celles-ci comprennent les composants internes des JVM, les bibliothèques natives utilisées par votre application ou par la JVM, ainsi que les appels système.

Les stack traces natives ne sont pas recueillies par défaut, car elles ne permettent généralement pas d'obtenir d'informations exploitables. De plus, les stacks natives parcourues peuvent potentiellement nuire à la stabilité de l'application. Testez ce paramètre dans un environnement hors production avant de l'implémenter en production.

Pour activer la collecte de stack traces natives, malgré le fait que cela puisse avoir une incidence sur la stabilité de votre application, définissez ce qui suit :

export DD_PROFILING_DDPROF_ENABLED=true # valeur par défaut pour les versions 1.7.0+
export DD_PROFILING_DDPROF_CSTACK=dwarf

ou :

-Ddd.profiling.ddprof.enabled=true # valeur par défaut pour les versions 1.7.0+
-Ddd.profiling.ddprof.cstack=dwarf

Configuration

Vous pouvez configurer le profileur à l’aide des variables d’environnement suivantes :

Variable d’environnement	Type	Description
DD_PROFILING_ENABLED	Booléen	Alternative à l’argument -Ddd.profiling.enabled. Définissez cette variable d’environnement sur true pour activer le profileur.
DD_PROFILING_ALLOCATION_ENABLED	Booléen	Remplace l’argument -Ddd.profiling.allocation.enabled. Définissez cette variable sur true pour activer le profileur d’allocation. Le profileur doit au préalable avoir été activé.
DD_ENV	Chaîne	Le nom de l’environnement, par exemple production.
DD_SERVICE	Chaîne	Le nom du service, par exemple web-backend.
DD_VERSION	Chaîne	La version de votre service.
DD_TAGS	Chaîne	Les tags à appliquer à un profil importé. Doit correspondre à une liste de paires <key>:<value> séparées par des virgules, par exemple : layer:api, team:intake.

Vous avez des doutes sur les prochaines étapes à suivre ?

Le guide Premiers pas avec le profileur en continu présente un exemple de service problématique et vous explique comment utiliser le profileur en continu pour mieux comprendre le problème et le corriger.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Débuter avec le profileurDOCUMENTATION En savoir plus sur les visualisations disponibles pour les profilsDOCUMENTATION Résoudre les problèmes rencontrés en utilisant le profileurDOCUMENTATION