JMX

JMX

Agent Check Check de l'Agent

Présentation

L’intégration Java vous permet de recueillir des métriques, des traces et des logs à partir de votre application Java.

Configuration

Collecte de métriques

Si votre application expose des métriques JMX, l’Agent Datadog appelle un petit plug-in Java du nom de JMXFetch (compatible uniquement avec Java >= 1.7) afin de se connecter à MBean Server et de recueillir les métriques de votre application. Il envoie également des checks de service afin de déterminer le statut des instances que vous surveillez. Ce plug-in envoie les métriques à l’Agent Datadog via le serveur DogStatsD, qui s’exécute au sein de l’Agent. Les intégrations suivantes utilisent également les métriques JMX :

  • ActiveMQ
  • Cassandra
  • Solr
  • Tomcat
  • Kafka

Remarque : par défaut, les checks JMX sont limités à 350 métriques par instance. Si vous souhaitez utiliser davantage de métriques, contactez l'assistance Datadog.

Installation

Vérifiez que vous pouvez ouvrir une connexion JMX distante. L’Agent Datadog nécessite une connexion distante pour se connecter à la JVM, même s’ils sont tous les deux sur le même host. Pour des raisons de sécurité, il est recommandé de ne pas utiliser l’adresse d’écoute 0.0.0.0. Utilisez plutôt com.sun.management.jmxremote.host=127.0.0.1 pour un déploiement avec la JVM et l’Agent.

Configuration

Si vous exécutez l’Agent en tant que binaire sur un host, configurez votre check JMX comme n’importe quelle intégration de l’Agent. Si vous exécutez l’Agent en tant que DaemonSet dans Kubernetes, configurez votre check JMX avec Autodiscovery.

  • Configurez l’Agent pour le connecter à JMX. Modifiez le fichier jmx.d/conf.yaml dans le dossier conf.d/ à la racine du répertoire de configuration de votre Agent. Consultez les options de configuration ci-dessous ou les modèles de init_config et d'instance pour découvrir toutes les options de configuration disponibles.

      init_config:
        is_jmx: true
        collect_default_metrics: true
        # custom_jar_paths:
        #  - <CUSTOM_JAR_FILE_PATH>.jar
    
      instances:
        - host: localhost
          port: port
          user: username
          password: password
          name: jmx_instance_name
    
  • Redémarrez l’Agent.

Remarque : pour exécuter plusieurs checks JMX, créez des fichiers de configuration avec le format jmx_<INDEX>.d/conf.yaml. Exemples : jmx_1.d/conf.yaml, jmx_2.d/conf.yaml, etc. Chaque dossier doit être stocké dans le répertoire conf.d. Définissez l’option is_jmx sur true dans le fichier de configuration.

JMX n’est pas installé sur l’image standard gcr.io/datadoghq/agent:latest servant à exécuter le conteneur de l’Agent Datadog. Utilisez plutôt l’image gcr.io/datadoghq/agent:latest-jmxAgent : celle-ci est basée sur gcr.io/datadoghq/agent:latest mais comprend une JVM, dont l’Agent a besoin pour exécuter jmxfetch.

Pour lancer un check JMX sur l’un de vos conteneurs :

  1. Créez un fichier de configuration de check JMX en faisant référence à host ou en utilisant un fichier de configuration de check JMX pour l’une des intégrations JMX officiellement prises en charge par Datadog :

  2. Montez ce fichier dans le dossier conf.d/ de votre Agent Datadog : -v <CHEMIN_DOSSIER_HOST>:/conf.d. Consultez la section Configuration des modèles de checks pour en savoir plus.

Remarque : l’utilisation de %%port%% peut entraîner des erreurs. Si vous rencontrez un problème, vous pouvez remplacer %%port%% par un port JMX codé en dur.

Options de configuration
Option Obligatoire Description
custom_jar_paths Non Permet de spécifier des fichiers jar personnalisés afin de les ajouter au classpath du JVM de l’Agent.
jmx_url Non Si l’Agent a besoin de se connecter à une URL JMX différente de celle par défaut, indiquez l’URL ici au lieu d’un host et d’un port. Si vous utilisez ce paramètre, vous devez spécifier un name pour l’instance.
is_jmx Non Autorise la création de différents fichiers de configuration pour chaque application, au lieu de créer un seul fichier JMX exhaustif. Indiquez cette option dans chaque fichier de configuration, tel qu’expliqué dans la remarque de la section Configuration.
collect_default_jvm_metrics Non Ordonne à l’intégration de collecter les métriques JVM par défaut (jvm.*). La valeur par défaut est true.
collect_default_metrics Non Chaque intégration contient un fichier metrics.yaml qui comprend la liste des beans par défaut à recueillir. Si vous définissez ce paramètre sur true, ces métriques sont automatiquement recueillies sans être explicitement ajoutées au fichier yaml. Cette option est généralement utilisée pour gérer la configuration d’Autodiscovery, afin de réduire la taille de l’objet de configuration. Cela ne s’applique pas à la collecte de métriques JMX via l’Agent de tracing Java.
java_bin_path Non Indiquez le chemin vers votre binaire ou exécutable Java si l’Agent ne parvient pas à le localiser. Exemple : C:/chemin/vers/java.exe ou /etc/alternatives/java.
java_options Non Options JVM Java
name Non Utilisé conjointement avec jmx_url.
new_gc_metrics Non Définissez ce paramètre sur true pour améliorer les noms des métriques de garbage collection. La valeur par défaut est false.
process_name_regex Non Au lieu de spécifier un host et un port ou jmx_url, l’Agent peut se connecter à l’aide de l’API Attach. Pour ce faire, vous devez avoir installé le JDK et avoir défini le chemin vers tools.jar.
refresh_beans Non Fréquence d’actualisation de la liste des Mbeans correspondants. Valeur par défaut : 600 s. Toute valeur inférieure peut entraîner une augmentation de la charge processeur.
refresh_beans_initial Non Période d’actualisation de la liste des Mbeans correspondants qui intervient immédiatement après l’initialisation. La valeur par défaut est refresh_beans.
rmi_connection_timeout Non Le délai d’expiration, en millisecondes, d’une connexion à la JVM à l’aide du host et du port ou d’une jmx_url.
rmi_client_timeout Non Spécifie la durée, en millisecondes, sans réponse de la JVM connectée après laquelle l’Agent abandonne une connexion existante et réessaie de se connecter.
service Non Permet d’associer un tag service:<SERVICE> à chaque métrique, événement et check de service émis par cette intégration.
service_check_prefix Non Préfixe de check de service custom, par ex. my_prefix pour obtenir un check de service nommé my_prefix.can_connect. Si cette valeur n’a pas été définie, le nom de l’intégration est utilisé par défaut.
tools_jar_path Non À définir lorsque process_name_regex est défini.
trust_store_path et trust_store_password Non À définir si le protocole SSL est activé.

Le paramètre conf correspond à une liste de dictionnaires. Seules deux clés sont autorisées dans ce dictionnaire :

Clé Obligatoire Description
include Oui Dictionnaire de filtres. Tout attribut qui correspond à ces filtres est recueilli, sauf s’il correspond également aux filtres « exclude » (voir ci-dessous).
exclude Non Dictionnaire de filtres. Les attributs qui correspondent à ces filtres ne sont pas recueillis.

Les tags sont automatiquement ajoutés aux métriques en fonction du nom du MBean. Vous pouvez spécifier explicitement des tags supplémentaires. Par exemple, si le MBean suivant est exposé par votre application surveillée :

mydomain:attr0=val0,attr1=val1

Cela créé une métrique mondomaine (ou un nom similaire, en fonction de l’attribut au sein du bean) avec les tags : attr0:val0, attr1:val1, domain:mondomaine, simple:val0, raw_value:ma_valeur_choisie, multiple:val0-val1.

Si vous spécifiez un alias dans une clé include au format camel case, il est converti au format snake case. Par exemple, MonNomMétrique devient mon_nom_métrique dans Datadog.

Description des filtres

Chaque dictionnaire include ou exclude prend en charge les clés suivantes :

Clé Description
domain Nom de domaine ou liste de noms de domaine (par ex. java.lang).
domain_regex Expression régulière ou liste d’expressions régulières correspondant au nom de domain (par ex. java\lang.*)
bean ou bean_name Nom de bean ou liste de noms de bean complets (par ex. java.lang:type=Compilation).
bean_regex Expression régulière ou liste d’expressions régulières correspondant aux noms de bean complets (par ex. java\.lang.*[,:]type=Compilation.*). Vous pouvez utiliser des groupes d’enregistrement dans votre expression régulière afin de spécifier des valeurs de tag. Voir l’exemple de configuration ci-dessus.
class Classe ou liste de noms de classe (par ex. org.datadog.jmxfetch.SimpleTestJavaApp).
class_regex Expression régulière ou liste d’expressions régulières correspondant aux noms de classe (par ex. org\.datadog\.jmxfetch\.SimpleTestJavaApp).
exclude_tags Liste de clés de tag à supprimer des métriques finales. Celle-ci peut être utilisée pour améliorer la cardinalité des tags de métrique. (Par ex. ["attr1", "id", "partition-id"])
attribute Liste ou dictionnaire de noms d’attributs (voir ci-dessous pour plus de détails).

Remarques :

  • Les expressions régulières définies dans domain_regex et bean_regex doivent respecter le format des expressions régulières de Java. Ces filtres ont été ajoutés dans la version 5.5.0.
  • À l’exception des expressions régulières, toutes les valeurs sont sensibles à la casse.

En plus de ces paramètres, les filtres prennent en charge les clés personnalisées. Ainsi, vous pouvez appliquer des filtres basés sur des paramètres bean. Par exemple, si vous souhaitez recueillir des métriques concernant le cache Cassandra, vous pouvez appliquer le filtre type: - Caches :

conf:
    - include:
          domain: org.apache.cassandra.db
          type:
              - Caches

Le filtre Attribute

Le filtre attribute accepte deux types de valeurs :

  • Dictionnaire dont les clés correspondent aux noms des attributs cibles :

    conf:
        - include:
              attribute:
                  maxThreads:
                      alias: tomcat.threads.max
                      metric_type: gauge
                  currentThreadCount:
                      alias: tomcat.threads.count
                      metric_type: gauge
                  bytesReceived:
                      alias: tomcat.bytes_rcvd
                      metric_type: counter
    
    • Vous pouvez définir un alias pour l’attribut qui devient le nom de la métrique dans Datadog.
    • Vous pouvez également définir le type de métrique : gauge, histogram, counter/rate, ou monotonic_count. Si vous choisissez counter, un rate (taux) par seconde est calculé pour la métrique et envoyé en tant que gauge.
  • Une liste de noms d’attribut cible :

    conf:
        - include:
              domain: org.apache.cassandra.db
              attribute:
                  - BloomFilterDiskSpaceUsed
                  - BloomFilterFalsePositives
                  - BloomFilterFalseRatio
                  - Capacity
                  - CompressionRatio
                  - CompletedTasks
                  - ExceptionCount
                  - Hits
                  - RecentHitRate
    
    • Le type de métrique est défini sur gauge par défaut.
    • Le nom de la métrique est jmx.<NOM_DOMAINE>.<NOM_ATTRIBUT>.

Voici un autre exemple de filtre :

instances:
    - host: 127.0.0.1
      name: jmx_instance
      port: 9999

init_config:
    conf:
        - include:
              bean: org.apache.cassandra.metrics:type=ClientRequest,scope=Write,name=Latency
              attribute:
                  - OneMinuteRate
                  - 75thPercentile
                  - 95thPercentile
                  - 99thPercentile

Validation

Lancez la sous-commande status de l’Agent et cherchez votre check JMX dans la section JMXFetch.

Les checks JMX possèdent également une configuration par défaut qui recueille des métriques depuis votre application. Reportez-vous au Metrics Explorer pour : jvm.heap_memory, jvm.non_heap_memory ou jvm.gc.cms.count.

Collecte de logs

Disponible à partir des versions > 6.0 de l’Agent

Consultez la documentation relative à la configuration de la collecte de logs Java pour transmettre vos logs à Datadog.

Collecte de traces

Après avoir activé la collecte de traces avec votre Agent, consultez la documentation relative à l'instrumentation de votre application Java pour envoyer ses traces à Datadog.

Données collectées

Métriques

jvm.heap_memory
(gauge)
The total Java heap memory used.
Shown as byte
jvm.heap_memory_committed
(gauge)
The total Java heap memory committed to be used.
Shown as byte
jvm.heap_memory_init
(gauge)
The initial Java heap memory allocated.
Shown as byte
jvm.heap_memory_max
(gauge)
The maximum Java heap memory available.
Shown as byte
jvm.non_heap_memory
(gauge)
The total Java non-heap memory used.
Shown as byte
jvm.non_heap_memory_committed
(gauge)
The total Java non-heap memory committed to be used.
Shown as byte
jvm.non_heap_memory_init
(gauge)
The initial Java non-heap memory allocated.
Shown as byte
jvm.non_heap_memory_max
(gauge)
The maximum Java non-heap memory available.
Shown as byte
jvm.thread_count
(count)
The number of live threads.
Shown as thread
jvm.gc.cms.count
(count)
The total number of garbage collections that have occurred.
jvm.gc.major_collection_count
(count)
The number of major garbage collections that have occurred. Set `new_gc_metrics: true` to receive this metric.
jvm.gc.minor_collection_count
(count)
The number of minor garbage collections that have occurred. Set `new_gc_metrics: true` to receive this metric.
jvm.gc.parnew.time
(gauge)
The approximate accumulated garbage collection time elapsed.
Shown as millisecond
jvm.gc.major_collection_time
(gauge)
The approximate major garbage collection time elapsed. Set `new_gc_metrics: true` to receive this metric.
Shown as millisecond
jvm.gc.minor_collection_time
(gauge)
The approximate minor garbage collection time elapsed. Set `new_gc_metrics: true` to receive this metric.
Shown as millisecond

Remarque : définissez new_gc_metrics: true dans votre fichier jmx.d/conf.yaml pour remplacer les métriques suivantes :

jvm.gc.cms.count   => jvm.gc.minor_collection_count
                      jvm.gc.major_collection_count
jvm.gc.parnew.time => jvm.gc.minor_collection_time
                      jvm.gc.major_collection_time

Dépannage

Consultez la liste des commandes de dépannage JMX et la FAQ dédiée.

Pour aller plus loin