Autodiscovery avec JMX

Docs > Surveillance des conteneurs > Containers Guides > Autodiscovery avec JMX

Dans les environnements conteneurisés, il existe quelques différences dans la façon dont lʼAgent se connecte au serveur JMX. La fonctionnalité Autodiscovery permet de configurer ces intégrations de façon dynamique. Utilisez les intégrations basées sur JMX de Datadog pour collecter des métriques sur les applications JMX de vos pods dans Kubernetes.

Si vous utilisez le traceur Java pour vos applications, vous pouvez également tirer parti de la fonctionnalité de métriques sur le runtime Java pour envoyer ces métriques à lʼAgent.

Installation

Utiliser un Agent compatible avec JMX

Les utilitaires JMX ne sont pas installés par défaut sur lʼAgent. Pour mettre en place une intégration JMX, ajoutez -jmx to your Agent’s image tag. For example, gcr.io/datadoghq/agent:latest-jmx.

Si vous utilisez Datadog Operator ou Helm, les configurations suivantes ajoutent -jmx au tag de l’image de votre Agent :

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  #(...)
  override:
    nodeAgent:
      image:
        jmxEnabled: true

agents:
  image:
    tagSuffix: jmx

Configuration

Utilisez l’une des méthodes suivantes :

Annotations dʼAutodiscovery (conseillé)
Fichiers de configuration dʼAutodiscovery : pour une personnalisation poussée des paramètres de configuration.

Annotations Autodiscovery

Dans cette méthode, une configuration de check JMX est appliquée à vos Pods basés sur Java par le biais d’annotations. Cela permet à lʼAgent de configurer automatiquement le check JMX lorsqu’un nouveau conteneur démarre. Assurez-vous que ces annotations se trouvent sur le Pod créé et non sur l’objet (Deployment, DaemonSet, etc.) qui crée le Pod.

Utilisez le modèle suivant pour les annotations dʼAutodiscovery :

apiVersion: v1
kind: Pod
metadata:
  name: <POD_NAME>
  annotations:
    ad.datadoghq.com/<CONTAINER_IDENTIFIER>.checks: |
      {
        "<INTEGRATION_NAME>": {
          "init_config": {
            "is_jmx": true,
            "collect_default_metrics": true
          },
          "instances": [{
            "host": "%%host%%",
            "port": "<JMX_PORT>"
          }]
        }
      }      
    # (...)
spec:
  containers:
    - name: '<CONTAINER_IDENTIFIER>'
      # (...)
      env:
        - name: POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: JAVA_OPTS
          value: >-
            -Dcom.sun.management.jmxremote
            -Dcom.sun.management.jmxremote.authenticate=false
            -Dcom.sun.management.jmxremote.ssl=false
            -Dcom.sun.management.jmxremote.local.only=false
            -Dcom.sun.management.jmxremote.port=<JMX_PORT>
            -Dcom.sun.management.jmxremote.rmi.port=<JMX_PORT>
            -Djava.rmi.server.hostname=$(POD_IP)

Dans cet exemple :

<POD_NAME> est le nom de votre pod.
<CONTAINER_IDENTIFIER> correspond au conteneur souhaité dans votre pod.
<INTEGRATION_NAME> est le nom de l’intégration JMX souhaitée. Référez-vous à la liste des [intégrations JMX disponibles] (#integrations-JMX-disponibles).
Définissez <JMX_PORT> comme vous le souhaitez, en veillant à ce quʼil y ait une correspondance entre les annotations et JAVA_OPTS.

Avec cette configuration, lʼAgent Datadog découvre ce pod et envoie une requête au serveur JMX relative à la variable de modèle Autodiscovery %%host%%. Cette requête se résout en l’adresse IP du module découvert. C’est pourquoi java.rmi.server.hostname est défini sur l’adresse POD_IP précédemment renseignée avec la downward API Kubernetes.

Remarque : la variable dʼenvironnement JAVA_OPTS est couramment utilisée dans les images de conteneur basées sur Java comme paramètre de démarrage (par exemple, java $JAVA_OPTS -jar app.jar). Si vous utilisez une application personnalisée ou si votre application ne suit pas ce modèle, définissez manuellement ces propriétés du système.

Exemple d’annotation : Tomcat

La configuration suivante exécute lʼintégration JMX Tomcat sur le port 9012 :

apiVersion: v1
kind: Pod
metadata:
  name: tomcat-test
  annotations:
    ad.datadoghq.com/tomcat.checks: |
      {
        "tomcat": {
          "init_config": {
            "is_jmx": true,
            "collect_default_metrics": true
          },
          "instances": [{
            "host": "%%host%%",
            "port": "9012"
          }]
        }
      }      
spec:
  containers:
    - name: tomcat
      image: tomcat:8.0
      imagePullPolicy: Always
      ports:
        - name: jmx-metrics
          containerPort: 9012
      env:
        - name: POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: JAVA_OPTS
          value: >-
            -Dcom.sun.management.jmxremote
            -Dcom.sun.management.jmxremote.authenticate=false
            -Dcom.sun.management.jmxremote.ssl=false
            -Dcom.sun.management.jmxremote.local.only=false
            -Dcom.sun.management.jmxremote.port=9012
            -Dcom.sun.management.jmxremote.rmi.port=9012
            -Djava.rmi.server.hostname=$(POD_IP)

Modèle d’annotation de métrique personnalisée

Si vous devez collecter d’autres métriques à partir de ces intégrations, ajoutez-les à la section init_config :

ad.datadoghq.com/<CONTAINER_IDENTIFIER>.checks: |
  {
    "<INTEGRATION_NAME>": {
      "init_config": {
        "is_jmx": true,
        "collect_default_metrics": true,
        "conf": [{
          "include": {
            "domain": "java.lang",
            "type": "OperatingSystem",
            "attribute": {
               "FreePhysicalMemorySize": {
                 "metric_type": "gauge",
                 "alias": "jvm.free_physical_memory"
               } 
            }
          }
        }]
      },
      "instances": [{
        "host": "%%host%%",
        "port": "<JMX_PORT>"
      }]
    }
  }

Référez-vous à la documentation relative à lʼintégration JMX pour en savoir plus sur le formatage de ces métriques.

Fichiers de configuration Autodiscovery

Si vous devez transmettre une configuration personnalisée plus complexe pour votre intégration Datadog/JMX, vous pouvez utiliser les identificateurs de conteneur Autodiscovery pour envoyer un fichier de configuration d’intégration personnalisé ou un fichier metrics.yaml personnalisé.

2. Composer le fichier de configuration

Pour cette méthode, lʼAgent a besoin d’un fichier de configuration et d’un fichier metrics.yaml facultatif afin que les métriques puissent collecter les données. Ces fichiers peuvent être montés dans le pod de lʼAgent ou intégrés dans l’image de conteneur.

En matière de dénomination du fichier de configuration, on cherche tout d’abord à identifier lʼintégration souhaitée à partir des [étapes préalables des intégrations disponibles] (#integrations-jmx-disponibles). Une fois ce nom déterminé, lʼAgent a besoin d’un fichier de configuration nommé en rapport avec lʼintégration ou dans le répertoire de configuration de lʼintégration.

Par exemple, pour lʼintégration Tomcat, créez soit :

/etc/datadog-agent/conf.d/tomcat.yaml ou
/etc/datadog-agent/conf.d/tomcat.d/conf.yaml

Si vous utilisez un fichier metrics.yaml personnalisé, incluez-le dans le répertoire de configuration de lʼintégration. Par exemple : /etc/datadog-agent/conf.d/tomcat.d/metrics.yaml.

Ce fichier de configuration doit inclure ad_identifiers :

ad_identifiers:
  - "<SHORT_IMAGE>"

init_config:
  is_jmx: true
  conf:
    <METRICS_TO_COLLECT>

instances:
  - host: "%%host%%"
    port: "<JMX_PORT>"

Remplacez <SHORT_IMAGE> par le nom dʼimage court du conteneur de votre choix. Par exemple, lʼimage de conteneur gcr.io/CompanyName/my-app:latest a pour nom dʼimage court my-app. Lorsque lʼAgent Datadog découvre ce conteneur, il établit la configuration JMX comme décrit dans ce fichier.

Vous pouvez également spécifier des identifiants personnalisés pour vos conteneurs et y faire référence si vous ne souhaitez pas vous baser sur le nom court de l’image.

Comme les annotations Kubernetes, les fichiers de configuration peuvent utiliser les template variables Autodiscovery. Dans ce cas, la configuration host utilise %%host%% pour résoudre l’adresse IP du conteneur découvert.

Référez-vous à la documentation relative à lʼintégration JMX, ainsi quʼaux exemples pré-fournis de configurations pour les intégrations pour en savoir plus sur la structuration de votre configuration init_config et instances pour que la<METRICS_TO_COLLECT>.

2. Monter le fichier de configuration

Si vous utilisez Datadog Operator, ajoutez un override :

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  #(...)
  override:
    nodeAgent:
      image:
        jmxEnabled: true
      extraConfd:
        configDataMap:
          <INTEGRATION_NAME>.yaml: |-
            ad_identifiers:
              - "<SHORT_IMAGE>"

            init_config:
              is_jmx: true

            instances:
              - host: "%%host%%"
                port: "<JMX_PORT>"

Dans Helm, utilisez l’option datadog.confd :

datadog:
  confd:
    <INTEGRATION_NAME>.yaml: |
      ad_identifiers:
        - "<SHORT_IMAGE>"

      init_config:
        is_jmx: true

      instances:
        - host: "%%host%%"
          port: "<JMX_PORT>"

Si vous ne pouvez pas monter ces fichiers dans le conteneur de lʼAgent (par exemple, sur Amazon ECS), vous pouvez créer une image Docker de lʼAgent contenant les fichiers de configuration souhaités.

Par exemple :

FROM gcr.io/datadoghq/agent:latest-jmx
COPY <PATH_JMX_CONF_FILE> conf.d/tomcat.d/
COPY <PATH_JMX_METRICS_FILE> conf.d/tomcat.d/

Ensuite, utilisez cette nouvelle image personnalisée comme votre Agent conteneurisé classique.

3. Exposer le serveur JMX

Configurez le serveur JMX de manière à permettre à lʼAgent d’y accéder :

spec:
  containers:
    - # (...)
      env:
      - name: POD_IP
        valueFrom:
          fieldRef:
            fieldPath: status.podIP
      - name: JAVA_OPTS
        value: >-
          -Dcom.sun.management.jmxremote
          -Dcom.sun.management.jmxremote.authenticate=false
          -Dcom.sun.management.jmxremote.ssl=false
          -Dcom.sun.management.jmxremote.local.only=false
          -Dcom.sun.management.jmxremote.port=<JMX_PORT>
          -Dcom.sun.management.jmxremote.rmi.port=<JMX_PORT>
          -Djava.rmi.server.hostname=$(POD_IP)

Intégrations JMX disponibles

LʼAgent Datadog est fourni avec plusieurs intégrations JMX préconfigurées.

Nom de l’intégration	Fichier de métriques	Fichier de configuration
activemq	metrics.yaml	conf.yaml.example
cassandra	metrics.yaml	conf.yaml.example
confluent_platform	metrics.yaml	conf.yaml.example
hazelcast	metrics.yaml	conf.yaml.example
hive	metrics.yaml	conf.yaml.example
hivemq	metrics.yaml	conf.yaml.example
hudi	metrics.yaml	conf.yaml.example
ignite	metrics.yaml	conf.yaml.example
jboss_wildfly	metrics.yaml	conf.yaml.example
kafka	metrics.yaml	conf.yaml.example
presto	metrics.yaml	conf.yaml.example
solr	metrics.yaml	conf.yaml.example
sonarqube	metrics.yaml	conf.yaml.example
tomcat	metrics.yaml	conf.yaml.example
weblogic	metrics.yaml	conf.yaml.example

Chaque intégration du tableau ci-dessus possède un fichier metrics.yaml prédéfini pour correspondre au modèle attendu des métriques JMX renvoyées par chaque application. Utilisez les intégrations listées comme <INTEGRATION_NAME> dans vos annotations ou fichiers de configuration Autodiscovery.

Vous pouvez également utiliser jmx comme <INTEGRATION_NAME> pour mettre en place une intégration JMX basique et collecter les métriques jvm.* par défaut uniquement.