If your application exposes JMX metrics, a lightweight Java plugin named JMXFetch (only compatible with Java >= 1.7.) is called by the Datadog Agent to connect to the MBean Server and collect your application metrics. It also sends service checks that report on the status of your monitored instances. This plugin sends metrics to the Datadog Agent using the DogStatsD server running within the Agent. These integrations also use the JMX metrics:
ActiveMQ
Cassandra
Solr
Tomcat
Kafka
Note: When submitting a RATE metric type through DogStatsD, the metric appears as a GAUGE in-app to ensure relevant comparison across different Agents. For more information, see the Metric Submission: DogStatsD documentation.
Make sure you can open a JMX remote connection. A remote connection is required for the Datadog Agent to connect to the JVM, even when the two are on the same host. For security reasons, it is recommended not to use 0.0.0.0 for the listening address, and using com.sun.management.jmxremote.host=127.0.0.1 for a colocated JVM and Agent is recommended.
If running the Agent as a binary on a host, configure your JMX check as any other Agent integrations. If running the Agent as a DaemonSet in Kubernetes, configure your JMX check using auto-discovery.
Note: To run more than one JMX check, create configuration files with the format jmx_<INDEX>.d/conf.yaml, for example:jmx_1.d/conf.yaml, jmx_2.d/conf.yaml, etc. Each folder should be stored in the conf.d directory. with the is_jmx option set to true in the configuration file.
The standard gcr.io/datadoghq/agent:latest image for running the Datadog Agent container does not have JMX installed. Use the gcr.io/datadoghq/agent:latest-jmx image, this image is based on gcr.io/datadoghq/agent:latest, but it includes a JVM, which the Agent needs to run jmxfetch.
To run a JMX Check against one of your container:
Create a JMX check configuration file by referring to the Host, or by using a JMX check configuration file for one of Datadog officially supported JMX integration:
Mount this file inside the conf.d/ folder of your Datadog Agent: -v <HOST_FOLDER_PATH>:/conf.d. See the Setting up Check Templates documentation to learn more.
Note: Using %%port%% has proven problematic in practice. If you experience an issue, the best workaround is to replace %%port%% with a hard-coded JMX port.
Allows specifying custom jars that are added to the classpath of the Agent’s JVM.
jmx_url
No
If the Agent needs to connect to a non-default JMX URL, specify it here instead of a host and port. If you use this you need to specify a name for the instance.
is_jmx
No
Allows creating different configuration files for each application rather than using a single long JMX file. Include the option in each configuration file as explained in the note from the Configuration section.
collect_default_jvm_metrics
No
Instructs the integration to collect the default JVM metrics (jvm.*). Default is true. Note: If you are using an integration that doesn’t need JMX specific metrics, set collect_default_jvm_metrics: false
collect_default_metrics
No
Each integration contains a metrics.yaml file that contains a list of default beans to collect. Setting this to True automatically collects those metrics without explicitly adding them to the yaml file. This is typically used for setting up the configuration with Autodiscovery to reduce the size of the configuration object. This is not applicable to collecting JMX metrics with the Java Tracing Agent.
java_bin_path
No
Specify the path to your Java executable or binary if the Agent cannot find it, for example: C:/path/to/java.exe or /etc/alternatives/java
java_options
No
Java JVM options
name
No
Used in conjunction with jmx_url.
new_gc_metrics
No
Set to true to use better metric names for garbage collection metrics. Default is false
process_name_regex
No
Instead of specifying a host and port or jmx_url, the Agent can connect using the attach API. This requires the JDK to be installed and the path to tools.jar to be set.
refresh_beans
No
Refresh period for refreshing the matching MBeans list. Default is 600 seconds. Decreasing this value may result in increased CPU usage.
refresh_beans_initial
No
Refresh period for refreshing the matching MBeans list immediately post initialization. Default is the value of refresh_beans.
rmi_connection_timeout
No
The connection timeout, in milliseconds, when connecting to a JVM using host and port or a jmx_url.
rmi_client_timeout
No
Specify the duration without reply from the connected JVM, in milliseconds, after which the Agent gives up on an existing connection and retries.
service
No
Attach a service:<SERVICE> tag to every metric, event, and service check emitted by this integration.
service_check_prefix
No
Custom service check prefix, for example my_prefix to get a service check called my_prefix.can_connect. Integration name is used as the default if not set.
tools_jar_path
No
To be set when process_name_regex is set.
trust_store_path and trust_store_password
No
Should be set if SSL is enabled.
The conf parameter is a list of dictionaries. Only 2 keys are allowed in this dictionary:
Key
Required
Description
include
Yes
A dictionary of filters - any attribute that matches these filters are collected unless it also matches the “exclude” filters (see below).
exclude
No
A dictionary of filters - attributes that match these filters are not collected.
Tags are automatically added to metrics based on the actual MBean name. You can explicitly specify supplementary tags. For instance, assuming the following MBean is exposed by your monitored application:
mydomain:attr0=val0,attr1=val1
It would create a metric called mydomain (or some variation depending on the attribute inside the bean) with tags: attr0:val0, attr1:val1, domain:mydomain, simple:val0, raw_value:my_chosen_value, multiple:val0-val1.
If you specify an alias in an include key that is formatted as camel case, it is converted to snake case. For example, MyMetricName is shown in Datadog as my_metric_name.
Each include or exclude dictionary supports the following keys:
Key
Description
domain
A domain name or list of domain names, for example: java.lang.
domain_regex
A regex pattern or list of patterns matching the domain name, for example: java\.lang.*.
bean or bean_name
A bean name or list of full bean names, for example: java.lang:type=Compilation.
bean_regex
A regex pattern or list of patterns matching the full bean names, for example: java\.lang.*[,:]type=Compilation.*. You can use capture groups in your regex to supply as tag values. See example configuration above.
class
A class of list of class names, for example: org.datadog.jmxfetch.SimpleTestJavaApp.
class_regex
A regex pattern or list of patterns matching the class names, for example: org\.datadog\.jmxfetch\.SimpleTestJavaApp.
exclude_tags
A list of tag keys to remove from the final metrics. This can be used to improve the metric tag cardinality, for example: ["attr1", "id", "partition-id"].
attribute
A list or a dictionary of attribute names (see below for more details).
Notes:
The regexes defined in domain_regex and bean_regex must conform to Java’s regular expression format. These filters were added in version 5.5.0.
Except for regex patterns, all values are case sensitive.
On top of these parameters, the filters support “custom” keys which allows you to filter by bean parameters. For example, if you want to collect metrics regarding the Cassandra cache, you could use the type: - Caches filter:
You can specify an alias for the attribute that becomes the metric name in Datadog.
You can also specify the metric type: gauge, histogram, counter/rate, or monotonic_count. If you choose counter, a rate per second is computed for the metric and it is sent as a gauge.
Additionally, JMX checks have a default configuration that collect metrics from your JMX application. Check the Metrics Explorer for: jvm.heap_memory, jvm.non_heap_memory, or jvm.gc.cms.count.
jmx.can_connect Returns CRITICAL if the Agent is unable to connect to and collect metrics from the monitored JVM instance, WARNING if no metrics are collected, and OK otherwise. Statuses: ok, critical, warning