JMX
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

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 afin qu’il se connecte à l’aide de JMX, et modifiez-le selon vos besoins. Voici un fichier d’exemple jmx.d/conf.yaml :

init_config:
  #custom_jar_paths:
  #  - <CHEMIN_FICHIER_JAR_PERSONNALISÉ>.jar
  #is_jmx: true

instances:
  - host: "<ENDPOINT_INSTANCE_JMX>"
    port: "<PORT_JMX>"
    user: "<NOM_UTILISATEUR>"
    password: "<MOTDEPASSE>"

    jmx_url: "service:jmx:rmi:///jndi/rmi://myhost.host:9999/<CHEMIN_PERSONNALISÉ>" # facultatif

    name: "<NOM_INSTANCE_JMX>"
    java_bin_path: "<CHEMIN_JAVA>"
    java_options: "-Xmx200m -Xms50m"
    trust_store_path: "<CHEMIN_TRUST_STORE>.jks"
    trust_store_password: "<MOTDEPASSE>"

    rmi_connection_timeout: 20
    rmi_client_timeout: 15000

    process_name_regex: ".*<NOM_PROCESSUS>.*"
    tools_jar_path: /usr/lib/jvm/java-7-openjdk-amd64/lib/tools.jar
    refresh_beans: 600
    tags:
      env: dev
      "<KEY_TAG>":"<VALUE_TAG>"

    conf:
      - include:
          domain: "<NOM_DOMAINE_1>"
          tags:
              simple: $attr0
              raw_value: "<VALEUR_CHOISIE>"
              multiple: $attr0-$attr1
          bean:
            - "<NOM_BEAN_1>"
            - "<NOM_BEAN_2>"
          attribute:
            attribute1:
              metric_type: counter
              alias: "jmx.<NOM_ATTRIBUT_MÉTRIQUE_1>"
            attribute2:
              metric_type: gauge
              alias: "jmx.<NOM_ATTRIBUT_MÉTRIQUE_2>"
            attribute3:
              metric_type: monotonic_count
              alias: "jmx.<NOM_ATTRIBUT_MÉTRIQUE_3>"

      - include:
          domain: "<NOM_DOMAINE_2>"
        exclude:
          bean:
            - "<NOM_BEAN_EXCLU>"
      - include:
          domain_regex: "<REGEX_DOMAINE>"
        exclude:
          bean_regex:
            - "<NOM_REGEX_BEAN_EXCLU>"
      - include:
          bean_regex: regex_topic=(.*?)
          attribute:
            attribute1:
              metric_type: gauge
              alias: "jmx.<NOM_ATTRIBUT_AVEC_TAG_REGEX>"

          ## Les lignes suivantes envoient le bean <NOM_ATTRIBUT_AVEC_TAG_REGEX> avec les tags :
          ## `hostregex:<paramètreBean>`
          ## `typeregex:<paramètreBean>`
          ## `contextregex<paramètreBean>`
          ## `optional:tag`
          tags:
              TypeRegex: $1
              HostRegex: $2
              contextRegex: $3
              optional: tag

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

JMX n’est pas installé sur l’image standard datadog/agent:latest servant à exécuter le conteneur de l’Agent Datadog. Utilisez plutôt l’image datadog/agent:latest-jmx : celle-ci est basée sur datadog/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
OptionObligatoireDescription
custom_jar_pathsNonPermet de spécifier des fichiers jar personnalisés afin de les ajouter au classpath du JVM de l’Agent.
jmx_urlNonSi 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_jmxNonAutorise 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_metricsNonChaque 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.
nameNonUtilisé conjointement avec jmx_url.
java_bin_pathNonDoit être défini si l’Agent ne parvient pas à trouver votre exécutable Java.
java_optionsNonOptions JVM Java
trust_store_path et trust_store_passwordNonÀ définir si le protocole SSL est activé.
process_name_regexNonAu 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.
tools_jar_pathNonÀ définir lorsque process_name_regex est défini.
refresh_beansNonFré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.
rmi_connection_timeoutNonLe délai d’expiration, en secondes, d’une connexion à la JVM à l’aide du host et du port ou d’une jmx_url.
rmi_client_timeoutNonSpé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.

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

CléObligatoireDescription
includeOuiDictionnaire de filtres. Tout attribut qui correspond à ces filtres est recueilli, sauf s’il correspond également aux filtres « exclude » (voir ci-dessous).
excludeNonDictionnaire 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 s’affiche sous la forme mon_nom_métrique dans Datadog.

Description des filtres

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

CléDescription
domainListe des noms de domaine (p. ex., java.lang).
domain_regexListe des expressions régulières pour le nom de domaine (p. ex., java\.lang.*).
bean ou bean_nameListe des noms de bean complets (p. ex., java.lang:type=Compilation).
bean_regexListe des expressions régulières pour les noms de bean complets (p. ex., java\.lang.*[,:]type=Compilation.*). Vous pouvez utiliser des groupes de capture dans votre expression régulière afin de fournir des valeurs de tag. Référez-vous à l’exemple de configuration ci-dessus.
attributeListe ou dictionnaire de noms d’attributs (voir ci-dessous pour plus de détails).

Les expressions régulières définies dans domain_regex et bean_regex doivent respecter le format des expressions régulières Java.

Les filtres domain_regex et bean_regex ont été ajoutés dans la version 5.5.0.

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 :

  • Un dictionnaire dont les clés correspondent à des noms d’attributs :

    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 alors spécifier un alias pour la métrique, qui correspond au nom de la métrique dans Datadog. Vous pouvez également indiquer le type de métrique : gauge, histogram, counter/rate ou monotonic_count. Si vous choisissez counter, un rate par seconde est calculé pour cette métrique et envoyé en tant que gauge.

  • Une liste de noms d’attributs :

    conf:
        - include:
              domain: org.apache.cassandra.db
              attribute:
                  - BloomFilterDiskSpaceUsed
                  - BloomFilterFalsePositives
                  - BloomFilterFalseRatio
                  - Capacity
                  - CompressionRatio
                  - CompletedTasks
                  - ExceptionCount
                  - Hits
                  - RecentHitRate

    Dans ce cas :

    • Le type de métrique est gauge.
    • 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 11 métriques depuis votre application JMX. Reportez-vous au Metrics Explorer pour consulter les métriques suivantes : 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