JMX data source

Dynatrace provides a framework to create metrics from JMX MBeans. Every process monitored by OneAgent Java code module is capable of processing JMX 2.0 extensions.

You need to enable the Java Metric Extensions 2.0 (JMX) OneAgent feature

Background

JMX organizes data and functionality in an object oriented way. Every Java process has a platform MBean server which manages a set of monitoring objects called MBeans.

Every MBean has a unique object name. Every object name consists of a domain name and a list of key properties. Every key property consists of a name and a (string) value.

JMX defines a standardized syntax to write those object names, for example, java.lang:type=GarbageCollector,name=YoungGen. Every MBean has 0 or more attributes (see MBeanServer::getAttribute). Attributes can be of any Java type (including booleans, numbers and strings).

Numeric attributes can be directly used to produce metrics in Dynatrace. It's also possible to extract numeric values from complex attributes.

Prerequisites

We assume the following:

Supported Dynatrace versions

JMX extension YAML file

Let's start with a minimal JMX extension:

# required extension metadata
name: custom:com.example.jmx
version: 1.0.0
minDynatraceVersion: 1.265.0
author:
  name: John Doe

# optional metric metadata
metrics:
  - key: com.example.jmx.thread_count
    metadata:
      displayName: Thread Count
      description: Number of active Java threads
      unit: Count

# defines how to create metrics from JMX MBeans
jmx:
  groups:
    - group: jvm
      subgroups:
        - subgroup: basic
          query: java.lang:type=Threading
          metrics:
            - key: com.example.jmx.thread_count
              type: gauge
              value: attribute:ThreadCount

The first two parts should already be familiar to you, we will focus on the jmx section of the YAML file.

Groups and subgroups can be used to share configuration between multiple metrics. In our specific sample, we only have one group and one subgroup.

Extract metrics from MBeans

Every subgroup has to select a set of MBeans that should contribute to a metric. This is done with the query field and follows the standard JMX object name syntax

Here, the query is java.lang:type=Threading. This breaks down into looking for a bean in domain java.lang that has exactly one property with name type and value Threading.

Every subgroup also needs to define at least one metric that should be extracted from the selected MBeans. In our sample we create a Dynatrace gauge metric called com.example.jmx.thread_count by querying the numeric JMX attribute ThreadCount from the MBean java.lang:type=Threading.

OneAgent will automatically add the following dimensions to your metric:

For more information, see JMX data source reference.