This is a translation of the original English documentation page. Help us make it better.

4 Discovery of JMX objects

Overview

It is possible to discover all JMX MBeans or MBean attributes or to specify a pattern for the discovery of these objects.

It is mandatory to understand the difference between Mbean and Mbean attributes for discovery rule configuration. An MBean is an object which can represent a device, an application, or any resource that needs to be managed. For example, there is an Mbean which represents a web-server. Its attributes are connection count, thread count, request timeout, http file cache, memory usage, etc. Expressing this thought in human comprehensive language we can define a coffee machine as an Mbean which has the following attributes to be monitored: water amount per cup, average consumption of water for a certain period of time, number of coffee beans required per cup, coffee beans and water refill time, etc.

Item key

In discovery rule configuration, select JMX agent in the Type field.

The item key to use is

jmx.discovery[<discovery mode>,<object name>]

where

  • discovery mode - one of the following: attributes (retrieve JMX MBean attributes, default) or beans (retrieve JMX MBeans)
  • object name - object name pattern identifying the MBean names to be retrieved (empty by default, retrieving all registered beans).

You may consult ObjectName documentation for the options of specifying object name pattern.

If no parameters are passed, all MBean attributes from JMX are requested.

Not specifying parameters for JMX discovery or trying to receive all attributes for a wide range like *:type=*,name=* may lead to potential performance problems.

This item key is supported since Zabbix Java gateway 3.4.

Item key examples:

jmx.discovery  #Retrieve all JMX MBean attributes
       jmx.discovery[beans]  #Retrieve all JMX MBeans
       jmx.discovery[attributes,"*:type=GarbageCollector,name=*"]  #Retrieve all garbage collector attributes
       jmx.discovery[beans,"*:type=GarbageCollector,name=*"]  #Retrieve all garbage collectors

This item returns a JSON object. For example, in the discovery of MBean attributes (reformatted for clarity):

{
          "data":[
             {
                "{#JMXVALUE}":"0",
                "{#JMXTYPE}":"java.lang.Long",
                "{#JMXOBJ}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXDESC}":"java.lang:type=GarbageCollector,name=PS Scavenge,CollectionCount",
                "{#JMXATTR}":"CollectionCount"
             },
             {
                "{#JMXVALUE}":"0",
                "{#JMXTYPE}":"java.lang.Long",
                "{#JMXOBJ}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXDESC}":"java.lang:type=GarbageCollector,name=PS Scavenge,CollectionTime",
                "{#JMXATTR}":"CollectionTime"
             },
             {
                "{#JMXVALUE}":"true",
                "{#JMXTYPE}":"java.lang.Boolean",
                "{#JMXOBJ}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXDESC}":"java.lang:type=GarbageCollector,name=PS Scavenge,Valid",
                "{#JMXATTR}":"Valid"
             },
             {
                "{#JMXVALUE}":"PS Scavenge",
                "{#JMXTYPE}":"java.lang.String",
                "{#JMXOBJ}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXDESC}":"java.lang:type=GarbageCollector,name=PS Scavenge,Name",
                "{#JMXATTR}":"Name"
             },
             {
                "{#JMXVALUE}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXTYPE}":"javax.management.ObjectName",
                "{#JMXOBJ}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXDESC}":"java.lang:type=GarbageCollector,name=PS Scavenge,ObjectName",
                "{#JMXATTR}":"ObjectName"
             }
          ]
       }

In the discovery of MBeans (reformatted for clarity):

{
          "data":[
             {  
                "{#JMXDOMAIN}":"java.lang",
                "{#JMXTYPE}":"GarbageCollector",
                "{#JMXOBJ}":"java.lang:type=GarbageCollector,name=PS Scavenge",
                "{#JMXNAME}":"PS Scavenge"
             }
          ]
       }

Supported macros

The following macros are supported for use in the discovery rule filter and prototypes of items, triggers and graphs:

Macro Description
Discovery of MBean attributes
{#JMXVALUE} Attribute value.
{#JMXTYPE} Attribute type.
{#JMXOBJ} Object name.
{#JMXDESC} Object name including attribute name.
{#JMXATTR} Attribute name.
Discovery of MBeans
{#JMXDOMAIN} MBean domain. (Zabbix reserved name)
{#JMXOBJ} Object name. (Zabbix reserved name)
{#JMX<key property>} MBean properties (like {#JMXTYPE}, {#JMXNAME}). Some important notes to pay attention to when defining MBean attribute name that is created from MBean property name by the following algorithm:

* attribute name case is changed to uppercase;
* attribute name case is ignored (no LLD macro is generated) in case it consists of not supported characters. Supported characters can be described by the following regular expression: "A-Z0-9_\.";
* if an attribute name is called "obj" or "domain" it will be replaced with the values of Zabbix properties {#JMXOBJ} and {#JMXDOMAIN} (supported since Zabbix 3.4.3.).

Please consider this jmx.discovery (with "beans" mode) example. MBean has the following properties defined:

name=test
       тип=Type
       attributes []=1,2,3
       Name=NameOfTheTest
       domAin=some

As a result of JMX discovery, the following LLD macros will be generated:

  • {#JMXDOMAIN} - Zabbix internal, describing the domain of MBean
  • {#JMXOBJ} - Zabbix internal, describing MBean object
  • {#JMXNAME} - created from "name" property

Ignored properties are:

  • тип : its name contains unsupported characters (non-ASCII)
  • attributes[] : its name contains unsupported characters (square brackets are not supported)
  • Name : it's already defined (name=test)
  • domAin : it's a Zabbix reserved name

Let’s review two more practical examples of a LLD rule creation with the use of Mbean. To understand the difference between a LLD rule collecting Mbeans and a LLD rule collecting Mbean attributes better please take a look at following table:

MBean1 MBean2 MBean3
MBean1Attribute1 MBean2Attribute1 MBean3Attribute1
MBean1Attribute2 MBean2Attribute2 MBean3Attribute2
MBean1Attribute3 MBean2Attribute3 MBean3Attribute3

LLD rule collecting Mbeans

This rule will return 3 objects: the top row of the column: MBean1, MBean2, MBean3.

For more information about objects please refer to supported macros table, Discovery of MBeans section.

Discovery rule configuration collecting Mbeans (without the attributes) looks like the following:

discovery_rule_mbean_1.png

Key used:

jmx.discovery[beans,"*:type=GarbageCollector,name=*"]

All the garbage collectors without attributes will be discovered. As Garbage collectors have the same attribute set, we can use desired attributes in item prototypes the following way:

discovery_rule_mbean_2.png

Keys used:

jmx[{#JMXOBJ},CollectionCount] 
       jmx[{#JMXOBJ},CollectionTime] 
       jmx[{#JMXOBJ},Valid] 

LLD discovery rule will result in something close to this (items are discovered for two Garbage collectors):

discovery_rule_mbean_3.png

LLD rule collecting Mbean attributes

This rule will return 9 objects with the following fields: MBean1Attribute1, MBean2Attribute1, Mbean3Attribute1,MBean1Attribute2,MBean2Attribute2, Mbean3Attribute2, MBean1Attribute3, MBean2Attribute3, Mbean3Attribute3.

For more information about objects please refer to supported macros table, Discovery of MBean attributes section.

Discovery rule configuration collecting Mbean attributes looks like the following:

discovery_rule_mbean_attributes_1.png

Key used:

jmx.discovery[attributes,"*:type=GarbageCollector,name=*"]

All the garbage collectors with a single item attribute will be discovered.

discovery_rule_mbean_attributes_2.png

In this particular case an item will be created from prototype for every MBean attribute. The main drawback of this configuration is that trigger creation from trigger prototypes is impossible as there is only one item prototype for all attributes. So this setup can be used for data collection, but is not recommended for automatic monitoring.

Examples

Let’s review two more practical examples of a LLD rule creation with the use of Mbean. To understand the difference between a LLD rule collecting Mbeans and a LLD rule collecting Mbean attributes better please take a look at following table:

MBean1 MBean2 MBean3
MBean1Attribute1 MBean2Attribute1 MBean3Attribute1
MBean1Attribute2 MBean2Attribute2 MBean3Attribute2
MBean1Attribute3 MBean2Attribute3 MBean3Attribute3
Example 1: Discovering Mbeans

This rule will return 3 objects: the top row of the column: MBean1, MBean2, MBean3.

For more information about objects please refer to supported macros table, Discovery of MBeans section.

Discovery rule configuration collecting Mbeans (without the attributes) looks like the following:

lld_rule_mbean0.png

Key used:

jmx.discovery[beans,"*:type=GarbageCollector,name=*"]

All the garbage collectors without attributes will be discovered. As Garbage collectors have the same attribute set, we can use desired attributes in item prototypes the following way:

discovery_rule_mbean_2.png

Keys used:

jmx[{#JMXOBJ},CollectionCount] 
       jmx[{#JMXOBJ},CollectionTime] 
       jmx[{#JMXOBJ},Valid] 

LLD discovery rule will result in something close to this (items are discovered for two Garbage collectors):

discovery_rule_mbean_3.png

Example 2: Discovering Mbean attributes

This rule will return 9 objects with the following fields: MBean1Attribute1, MBean2Attribute1, Mbean3Attribute1,MBean1Attribute2,MBean2Attribute2, Mbean3Attribute2, MBean1Attribute3, MBean2Attribute3, Mbean3Attribute3.

For more information about objects please refer to supported macros table, Discovery of MBean attributes section.

Discovery rule configuration collecting Mbean attributes looks like the following:

lld_rule_mbean_attr.png

Key used:

jmx.discovery[attributes,"*:type=GarbageCollector,name=*"]

All the garbage collectors with a single item attribute will be discovered.

discovery_rule_mbean_attributes_2.png

In this particular case an item will be created from prototype for every MBean attribute. The main drawback of this configuration is that trigger creation from trigger prototypes is impossible as there is only one item prototype for all attributes. So this setup can be used for data collection, but is not recommended for automatic monitoring.

Using jmx.get

jmx.get[] is similar to the jmx.discovery[] item, but is does not turn Java object properties into low-level discovery macro names and therefore can return values without limitations that are associated with LLD macro name generation such as hyphens or non-ASCII characters.

When using jmx.get[] for discovery, low-level discovery macros can be defined separately in the custom LLD macro tab of the discovery rule configuration, using JSONPath to point to the required values.

Discovering MBeans

Discovery item: jmx.get[beans,"com.example:type=*,*"]

Response:

[
           {
               "object": "com.example:type=Hello,data-src=data-base,ключ=значение",
               "domain": "com.example",
               "properties": {
                   "data-src": "data-base",
                   "ключ": "значение",
                   "type": "Hello"
               }
           },
           {
               "object": "com.example:type=Atomic",
               "domain": "com.example",
               "properties": {
                   "type": "Atomic"
               }
           }
       ]
Discovering MBean attributes

Discovery item: jmx.get[attributes,"com.example:type=*,*"]

Response:

[
           {
               "object": "com.example:type=*",
               "domain": "com.example",
               "properties": {
                   "type": "Simple"
               }
           },
           {
               "object": "com.zabbix:type=yes,domain=zabbix.com,data-source=/dev/rand,ключ=значение,obj=true",
               "domain": "com.zabbix",
               "properties": {
                   "type": "Hello",
                   "domain": "com.example",
                   "data-source": "/dev/rand",
                   "ключ": "значение",
                   "obj": true
               }
           }
       ]