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

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 :

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

  2. 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 :

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

  2. 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égrationFichier de métriquesFichier de configuration
    activemqmetrics.yamlconf.yaml.example
    cassandrametrics.yamlconf.yaml.example
    confluent_platformmetrics.yamlconf.yaml.example
    hivemetrics.yamlconf.yaml.example
    jboss_wildflymetrics.yamlconf.yaml.example
    kafkametrics.yamlconf.yaml.example
    solrmetrics.yamlconf.yaml.example
    prestometrics.yamlconf.yaml.example
    tomcatmetrics.yamlconf.yaml.example
  3. Remplacez le nom du fichier conf.yaml.example par conf.yaml.

  4. 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
  5. 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.

  6. Montez ces fichiers de configuration (conf.yaml et metrics.yaml) dans le dossier conf.d/<NOM_INTÉGRATION>.d/ de votre Agent.

  7. (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 datadog/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 :

  1. Activez Autodiscovery sur votre Agent.

  2. 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.

  3. 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
  4. 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.

  5. Redémarrez votre Agent.

Préparation du conteneur

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

apiVersion: v1
kind: Pod
# (...)
metadata:
    name: '<NOM_POD>'
    annotations:
        ad.datadoghq.com/<IDENTIFICATEUR_CONTENEUR>.check.id: '<IDENTIFICATEUR_AD_PERSONNALISÉ>'
        # (...)
spec:
    containers:
        - name: '<IDENTIFICATEUR_CONTENEUR>'
          # (...)
          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)
# (...)

Remarques :

  • Pour appliquer une configuration spécifique à un conteneur donné, Autodiscovery identifie les conteneurs via leur nom, et non via leur image. II cherche à faire correspondre <IDENTIFICATEUR_CONTENEUR> à .spec.containers[0].name, et non à .spec.containers[0].image.
  • Si vous définissez directement vos pods Kubernetes (avec kind: Pod), ajoutez les annotations de chaque pod directement dans sa section metadata. Si vous définissez indirectement les pods avec des ReplicationControllers, des ReplicaSets ou des Deployments, ajoutez les annotations de pod dans .spec.template.metadata.
  • Vous devez créer la variable d’environnement JAVA_OPTS, afin que votre serveur JMX autorise l’Agent à se connecter au registre RMI.
  • <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.

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.

Pour aller plus loin