Autodiscovery avec JMX

Docs > Agent > Guides de l'Agent > Autodiscovery avec JMX

Tirez profit des annotations Autodiscovery pour les intégrations ou utilisez les identificateurs de conteneur Autodiscovery afin de recueillir les métriques de vos applications JMX à partir de vos pods Kubernetes. Bien que les annotations Autodiscovery constituent la solution recommandée pour configurer l’intégration Datadog/JMX, si l’ensemble des paramètres de configuration est trop long pour rentrer dans des annotations, utilisez plutôt les identificateurs de conteneur Autodiscovery.

Annotations Autodiscovery

Les annotations Autodiscovery reposent sur une logique précise. Elles appliquent les éléments de configuration du check JMX à votre pod. L’Agent peut ainsi les découvrir automatiquement et configurer son check JMX en conséquence :

Lancez l’Agent dans votre cluster Kubernetes avec le nom d’image gcr.io/datadoghq/agent:latest-jmx, au lieu du nom gcr.io/datadoghq/agent:latest standard.

Appliquez les annotations Autodiscovery aux conteneurs comprenant votre application JMX :

apiVersion: v1
kind: Pod
metadata:
    name: <POD_NAME>
    annotations:
        ad.datadoghq.com/<CONTAINER_IDENTIFIER>.check_names: '["<INTEGRATION_NAME>"]'
        ad.datadoghq.com/<CONTAINER_IDENTIFIER>.init_configs: '[{"is_jmx": true, "collect_default_metrics": true}]'
        ad.datadoghq.com/<CONTAINER_IDENTIFIER>.instances: '[{"host": "%%host%%","port":"<JMX_PORT>"}]'
        ad.datadoghq.com/<CONTAINER_IDENTIFIER>.logs: '[{"source":"<INTEGRATION_NAME>","service":"<INTEGRATION_NAME>"}]'
    # (...)

spec:
    containers:
        - name: '<CONTAINER_IDENTIFIER>'
        # (...)
          env:
          - name: POD_IP
            valueFrom:
              fieldRef:
                fieldPath: status.podIP

          - name: JAVA_OPTS
            value: >-
              -Xms256m -Xmx6144m
              -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)

Vous devez créer la variable d’environnement JAVA_OPTS, afin que votre serveur JMX autorise l’Agent à se connecter au registre RMI.

Remarque :

<JMX_PORT> désigne le port qui expose les métriques JMX.
Dans l’exemple ci-dessus, la connexion vers le registre RMI ne s’effectue pas via SSL. Si vous souhaitez bénéficier d’une connexion SSL, indiquez "rmi_registry_ssl": true dans l’annotation ad.datadoghq.com/<IDENTIFICATEUR_CONTENEUR>.instances et supprimez l’option Dcom.sun.management.jmxremote correspondante de JAVA_OPTS.

Voici la liste des valeurs autorisées par JMX pour le nom d’intégration <INTEGRATION_NAME> :

Ainsi, si vous exécutez une intégration Tomcat qui expose ses métriques JMX sur le port 9012, vous devez utiliser ce qui suit :

apiVersion: v1
kind: Pod
metadata:
    name: tomcat-test
    annotations:
        ad.datadoghq.com/tomcat.check_names: '["tomcat"]'
        ad.datadoghq.com/tomcat.init_configs: '[{"is_jmx": true, "collect_default_metrics": true}]'
        ad.datadoghq.com/tomcat.instances: '[{"host": "%%host%%","port":"9012"}]'
        ad.datadoghq.com/tomcat.logs: '[{"source":"Tomcat","service":"Tomcat"}]'

spec:
    containers:
        - name: tomcat
          image: tomcat:8.0
          imagePullPolicy: Always
          ports:
              - containerPort: 9012
          env:
            - name: POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP

            - name: JAVA_OPTS
              value: >-
                -Xms256m -Xmx6144m
                -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)

Identificateurs de conteneur Autodiscovery

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

Préparation de l’Agent

Sélectionnez l’un des onglets ci-dessous selon que votre Agent s’exécute en tant que conteneur dans votre cluster ou directement sur votre host :

Si votre Agent s’exécute dans votre cluster et que vous souhaitez découvrir automatiquement votre conteneur afin de recueillir des métriques JMX :

Assurez-vous d’exécuter l’image gcr.io/datadoghq/agent:latest-jmx de l’Agent, et non l’image gcr.io/datadoghq/agent:latest standard.

Récupérez les fichiers de configuration conf.yaml et metrics.yaml associés à votre intégration. Vous trouverez ci-dessous la liste des intégrations Datadog basées sur JMX, ainsi que leurs fichiers associés :

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
hive	metrics.yaml	conf.yaml.example
jboss_wildfly	metrics.yaml	conf.yaml.example
kafka	metrics.yaml	conf.yaml.example
solr	metrics.yaml	conf.yaml.example
presto	metrics.yaml	conf.yaml.example
tomcat	metrics.yaml	conf.yaml.example

Remplacez le nom du fichier conf.yaml.example par conf.yaml.

Remplacez les valeurs des paramètres du fichier conf.yaml en suivant la logique de la fonction Autodiscovery de l’Agent. Les fichiers de configuration possèdent des valeurs de paramètre de host par défaut. Utilisez plutôt la logique des template variables Autodiscovery. Dans l’exemple de check Tomcat suivant, la valeur localhost du paramètre host a été remplacée par %%host%% :

init_config:
    ## @param is_jmx - boolean - required
    ## Whether or not this file is a configuration for a JMX integration.
    #
    is_jmx: true

    ## @param collect_default_metrics - boolean - required
    ## Whether or not the check should collect all default metrics.
    #
    collect_default_metrics: true

instances:
    ## @param host - string - required
    ## Tomcat JMX hostname to connect to.
    #
    - host: '%%host%%'

      ## @param port - integer - required
      ## Tomcat JMX port to connect to.
      #
      port: 9012

Pour indiquer à l’Agent que vous souhaitez appliquer ce fichier de configuration à votre conteneur d’application, définissez un paramètre ad_identifiers au début de votre fichier conf.yaml :
```
ad_identifiers:
    - '<CUSTOM_AD_IDENTIFIER>'

init_config:
    # (...)
instances:
    # (...)
```
Remarque : l’exemple ci-dessus utilise une valeur personnalisée pour ad_identifers, mais vous pouvez définir le nom raccourci de l’image du conteneur sur ad_identifiers si vous le souhaitez.
Montez ces fichiers de configuration (conf.yaml et metrics.yaml) dans le dossier conf.d/<NOM_INTÉGRATION>.d/ de votre Agent.
(Facultatif) Si vous ne pouvez pas monter ces fichiers dans le conteneur de l’Agent (par exemple si vous utilisez AWS ECS), créez une nouvelle image Docker de l’Agent en y intégrant ces deux fichiers de configuration :
```
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 en tant qu’Agent conteneurisé classique.

Si votre Agent s’exécute sur un host et que vous souhaitez découvrir automatiquement votre conteneur afin de recueillir des métriques JMX :

Activez Autodiscovery sur votre Agent.
Activez l’intégration JMX à utiliser en remplaçant le nom du fichier conf.yaml.example correspondant par conf.yaml dans le répertoire de l’intégration de l’Agent. Par exemple, pour Tomcat, remplacez le nom /etc/datadog-agent/conf.d/tomcat.d/conf.yaml.example par /etc/datadog-agent/conf.d/tomcat.d/conf.yaml.

Remplacez les valeurs des paramètres du fichier conf.yaml en suivant la logique de la fonction Autodiscovery de l’Agent. Les fichiers de configuration possèdent des valeurs de paramètre de host par défaut. Utilisez plutôt la logique des template variables Autodiscovery. Dans l’exemple de configuration Tomcat suivant, la valeur localhost du paramètre host a été remplacée par %%host%% :

init_config:
    ## @param is_jmx - boolean - required
    ## Whether or not this file is a configuration for a JMX integration.
    #
    is_jmx: true

    ## @param collect_default_metrics - boolean - required
    ## Whether or not the check should collect all default metrics.
    #
    collect_default_metrics: true

instances:
    ## @param host - string - required
    ## Tomcat JMX hostname to connect to.
    #
    - host: '%%host%%'

      ## @param port - integer - required
      ## Tomcat JMX port to connect to.
      #
      port: 9012

Pour indiquer à l’Agent que vous souhaitez appliquer ce fichier de configuration à vos conteneurs d’application, définissez un paramètre ad_identifiers au début de votre fichier conf.yaml :
```
ad_identifiers:
    - '<CUSTOM_AD_IDENTIFIER>'

init_config:
    # (...)
instances:
    # (...)
```
Remarque : l’exemple ci-dessus utilise une valeur personnalisée pour ad_identifers, mais vous pouvez définir le nom raccourci de l’image du conteneur sur ad_identifiers si vous le souhaitez.
Redémarrez votre Agent.

Préparation du conteneur

Docker

Une fois l’Agent configuré et exécuté, utilisez l’étiquette com.datadoghq.ad.check.id:"<IDENTIFICATEUR_AD_PERSONNALISÉ>" pour votre conteneur d’application afin d’appliquer la configuration du check via Autodiscovery :

Dockerfile :

LABEL "com.datadoghq.ad.check.id"= '<IDENTIFICATEUR_AD_PERSONNALISÉ>'

docker-compose.yaml :

labels:
    com.datadoghq.ad.check.id: '<IDENTIFICATEUR_AD_PERSONNALISÉ>'

Commande d’exécution Docker :

-l com.datadoghq.ad.check.id= '<IDENTIFICATEUR_AD_PERSONNALISÉ>'

Docker Swarm :

Pour utiliser le mode Swarm avec Docker Cloud, les étiquettes doivent être appliquées à l’image :

version: '1.0'
services:
# ...
project:
    image: '<NOM_IMAGE>'
    labels:
        com.datadoghq.ad.check.id: '<IDENTIFICATEUR_AD_PERSONNALISÉ>'

Remarque : si l’Agent et votre conteneur JMX se trouvent sur le même pont réseau, vous devez instancier votre serveur JMX avec -Djava.rmi.server.hostname=<NOM_CONTENEUR>", en remplaçant <NOM_CONTENEUR> par le nom de votre conteneur d’application JMX.