Customize JMX extensions

JMX extensions are defined by JSON files.

An extension definition consists of three main elements: metadata, metrics, and UI.

JSONcopydownload
The basic format is as follows:
  {
    "version": "1.0",
    "name": "custom.jmx.hornetq",
    "type": "JMX",
    "entity": "PROCESS_GROUP_INSTANCE",
    "metricGroup": "tech.HornetQ",
    "configUI" : {
      "displayName": "HornetQ JMX"
    },
    "metrics": [ ],
    "ui": {
      "keycharts" : [ ],
      "charts": [ ]
    }
  }

Metadata

Each JMX extension has the following mandatory properties:

Metrics

This part of the JSON defines which metrics are collected by the extension. Each metric is defined by JSON in a format similar to the following:

JSONcopydownload
{
    "timeseries": {
      "key": "Queue.ConsumerCount",
      "unit": "Count",
      "displayname": "Queue Consumer Count",
      "dimensions": [
        "rx_pid"
      ]
    },
    "alert_settings": [
      {
        "alert_id": "too_many_consumers",
        "event_type": "PERFORMANCE_EVENT",
        "event_name": "Too many consumers",
        "description": "The {metricname} of {severity} is {alert_condition} the threshold of {threshold}",
        "threshold": 35.0,
        "alert_condition": "ABOVE",
        "samples":5,
        "violating_samples":3,
        "dealerting_samples":5,
        "value_extractor": "MAX"
      }
    ]
    "source": {
      "domain": "org.hornetq",
      "keyProperties": {
        "type": "Queue",
      },
      "attribute": "ConsumerCount"
    }
  }

Timeseries

This part specifies the metadata of a metric.

Available units: NanoSecond, MicroSecond, MilliSecond, Second, Byte, KiloByte, MegaByte, BytePerSecond, BytePerMinute, KiloBytePerSecond, KiloBytePerMinute, MegaBytePerSecond, MegaBytePerMinute, Count, PerSecond, PerMinute

Alert settings

This part specifies the configuration of one or more alerts for a given timeseries.

Source

This part specifies how a metric is collected using JMX. The following attributes are required for all metrics:

Optional attributes are:

Splitting

Splittings can be used to define an additional dimension for a metric. This dimension must be defined in the dimension property of the timeseries and the splitting property of the source.

jsoncopydownload
"splitting": {
    "name": "name",
    "type": "keyProperty",
    "keyProperty": "name"
  }

To define multiple splittings, use the following format:

jsoncopydownload
"splittings":[
   {
      "name":"name",
      "type":"keyProperty",
      "keyProperty":"name"
   },
   {
      "name":"context",
      "type":"keyProperty",
      "keyProperty":"context"
   }
]

The following attributes must be present for each splitting:

Example of a metric with an additional splitting

The following example shows how to define a metric that provides multiple timeseries within a single metric:

JSONcopydownload
{
    "timeseries": {
      "key": "XY.Size",
      "unit": "Count",
      "displayname": "Queue Consumer Count",
      "dimensions": [
        "rx_pid",
        "name"
      ]
    }
    "source": {
      "domain": "com.sample",
      "keyProperties": {
        "type": "XY",
        "name": "*"
      },
      "attribute": "Size",
      "splitting": {
        "name": "name",
        "type": "keyProperty",
        "keyProperty": "name"
      }
    }
  }

For example, MBeans com.sample:type=XY,name=A and com.sample:type=XY,name=B will result in two timeseries, the first for "A" and the second for "B".

CompositeData

To extract values of individual keys returned as CompositeData type by an attribute, you need to use the attributePath mechanism and point to the key you're interested in.

For example, let's say you want to extract the value of used from the HeapMemoryUsage attribute. HeapMemoryUsage is a CompositeData type that returns the following list of value-key pairs:

jsoncopydownload
{
    committed: integer,
    init: integer,
    max: integer,
    used: integer
}

Define the metric that points to the MBean with the HeapMemoryUsage attribute and, in the source section, point the attributePath to the used key. For example:

jsoncopydownload
"source": {
      "domain": "java.lang",
      "keyProperties": {
        "type": "Memory",
      },
      "attribute": "HeapMemoryUsage",
      "attributePath": "get(\"used\")"
    }

UI config

This part of the JSON defines how metrics are charted on the process page. It contains a mandatory charts section and an optional keycharts section. Each section has the same format and looks like this:

jsoncopydownload
{
        "ui": {
            "keymetrics" : [
             {
                    "key" : "requestCount",
                    "aggregation" : "avg",
                    "mergeaggregation" : "sum",
                    "displayname" : "Requests"
             }
            ],
            "keycharts" : [ ],
            "charts": [ ]
        }
    }

The keymetrics section is completely optional and allows you to define up to two metrics that should be part of the Process infographic. It has the following attributes:

Each chart section has the same format and looks like this:

JSONcopydownload
{
                "group": "Section Name",
                "title": "Chart Name",
                "series": [
                 {
                        "key": "MetricName",
                        "aggregation": "avg",
                        "displayname": "Display name for metric",
                        "seriestype": "area"
                 },
                 {
                        "key": "Other Metric Name",
                        "aggregation": "avg",
                        "displayname": "Display name for metric",
                        "color": "rgba(42, 182, 244, 0.6)",
                        "seriestype": "area"
                 }
                ]
         }

The charts section describes how to chart each metric in the details section of the process page (available by selecting Further details).

Both sections allow an array of charts to be defined. A chart has the following required attributes:

A series has the following attributes: