Autodiscovery with JMX

Docs > Agent > Agent Guides > Autodiscovery with JMX

Leverage integrations autodiscovery annotations or use Autodiscovery Container Identifiers to collect your JMX-applications metrics from your pods in Kubernetes. Autodiscovery annotations is the recommended way to configure your Datadog-JMX integration, if the set of configuration parameters is too long to fit in annotations, use the Autodiscovery Container Identifiers method.

Autodiscovery annotations

The autodiscovery annotations logic consists in applying the JMX check configuration elements, through annotations, to your pod in order to allow the Agent to “automatically discover” them and configure its JMX check accordingly:

Launch the Agent in your Kubernetes cluster with the gcr.io/datadoghq/agent:latest-jmx image name instead of the regular gcr.io/datadoghq/agent:latest.

Apply the Autodiscovery annotations to the containers containing your JMX-application:

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)

The JAVA_OPTS environment variable needs to be created, so that your JMX server allows the agent to connect to the RMI registry.

Note:

<JMX_PORT> references the port that exposes JMX metrics.
In the example above, the connection to the RMI registry is not in SSL if you want to use SSL, use "rmi_registry_ssl": true in the ad.datadoghq.com/<CONTAINER_IDENTIFIER>.instances annotation and remove the corresponding Dcom.sun.management.jmxremote from JAVA_OPTS.

The list of JMX-ready integrations name <INTEGRATION_NAME> are:

For instance if you have a tomcat running exposing its JMX metrics on port 9012 you would do:

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)

Autodiscovery container identifiers

If you need to pass a more complex configuration for your Datadog-JMX integration, leverage Autodiscovery Container Identifiers to pass custom integration configuration file or custom metrics.yaml file.

Agent preparation

Choose whether your Agent is running as a container in your cluster, or on your host directly:

If your Agent is running in your cluster and you want to autodiscover your container to collect JMX metrics:

Make sure to run the Agent image the gcr.io/datadoghq/agent:latest-jmx instead of the regular gcr.io/datadoghq/agent:latest image.

Get the configuration files conf.yaml and metrics.yaml associated to your integration. Find below the list of Datadog-JMX based integration with their associated files:

Integration Name	Metrics file	Configuration file
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

Rename the conf.yaml.example file into conf.yaml.

Replace the parameter values from conf.yaml to fit the Agent Autodiscovery logic. The configuration files have host parameter values by default, use the Autodiscovery Template Variables logic instead. In the following Tomcat check example, the host parameter value is changed from localhost to %%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

To specify to the Agent that you want to apply this configuration file to your application container, configure an ad_identifiers parameter at the beginning of your conf.yaml file:
```
ad_identifiers:
    - '<CUSTOM_AD_IDENTIFIER>'

init_config:
    # (...)
instances:
    # (...)
```
Note: The example above uses a custom ad_identifers value, but you can specify the container short image as ad_identifiers if needed.
Mount those configuration files (conf.yaml and metrics.yaml) in your Agent in the conf.d/<INTEGRATION_NAME>.d/ folder.
(Optional) - If you can’t mount those files in the Agent container (like on AWS ECS), you should re-build the Agent docker image with those two configuration files in it:
```
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/
```
Then use this new custom image as the regular containerized Agent.

If your Agent is running on a host and you want to autodiscover your container to collect JMX metrics:

Enable autodiscovery for your Agent.
Enable the JMX integration you want to use by renaming the corresponding conf.yaml.example file into conf.yaml in the Agent integration directory. For instance for tomcat you would rename /etc/datadog-agent/conf.d/tomcat.d/conf.yaml.example into: /etc/datadog-agent/conf.d/tomcat.d/conf.yaml

Replace the parameters values from conf.yaml file to fit the Agent Autodiscovery logic. The configuration files have host parameter values by default, use the Autodiscovery Template Variables instead. In the following Tomcat configuration example, the host parameter value is changed from localhost to %%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

To specify to the Agent that you want to apply this configuration file to your application containers, configure an ad_identifiers parameter at the beginning of your conf.yaml file:
```
ad_identifiers:
    - '<CUSTOM_AD_IDENTIFIER>'

init_config:
    # (...)
instances:
    # (...)
```
Note: The example above uses a custom ad_identifers value, but you can specify the container short image as ad_identifiers if needed.
Restart your Agent

Container preparation

Docker

Once the Agent is configured and running, use the com.datadoghq.ad.check.id:"<CUSTOM_AD_IDENTIFIER>" label for your application container to apply the check configuration through Autodiscovery:

Dockerfile:

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

docker-compose.yaml:

labels:
    com.datadoghq.ad.check.id: '<CUSTOM_AD_IDENTIFIER>'

docker run command:

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

Docker Swarm:

When using Swarm mode for Docker Cloud, labels must be applied to the image:

version: '1.0'
services:
# ...
project:
    image: '<IMAGE_NAME>'
    labels:
        com.datadoghq.ad.check.id: '<CUSTOM_AD_IDENTIFIER>'

Note: If the Agent and your JMX container are on the same network bridge, you need to instantiate your JMX server with -Djava.rmi.server.hostname=<CONTAINER_NAME>" where <CONTAINER_NAME> is your JMX-application container name.