JMX Querier plugin

This document describes the functionality of the JMX plugin and its integration with PandoraFMS. The JMX plugin allows the integration of Mbeans statistics in PandoraFMS.

Introduction

Ver. 19-06-2024

This document describes the functionality of the JMX plugin and its integration with PandoraFMS. The JMX plugin allows the integration of Mbeans statistics in PandoraFMS.

Tipo: Plug-in server

Compatibility matrix

Systems where tested Rocky linux, Fedora
Systems where it works Any linux system

Pre requisites

1. Enabling Remote JMX Monitoring for Java Applications
A Java application does not require additional software installed, but it must be started with the following command line options to enable support for remote JMX monitoring.

At the very least, if you only want to start monitoring a basic Java application on a local host without security, use these options:

-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.authenticate=false \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.port=9090 \
-Dcom.sun.management.jmxremote.rmi.port=9090 \
-Djava.rmi.server.hostname=localhost"

This configures Java to accept incoming JMX connections on port 9090 from localhost only, with no authentication or SSL required.

If authentication is required, it must be enabled:

-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.authenticate=true \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.port=9090 \
-Dcom.sun.management.jmxremote.rmi.port=9090 \
-Djava.rmi.server.hostname=localhost \
-Dcom.sun.management.jmxremote.password.file=/usr/local/tomcat/conf/jmxremote.password \
-Dcom.sun.management.jmxremote.access.file=/usr/local/tomcat/conf/jmxremote.access


2. The system running the plugin must have connectivity and be able to reach the JMX server.

Parameters

JMX connection and configuration parameters

--jmx_url JMX server connection endpoint, example : service:jmx:rmi:///jndi/rmi://localhost:9090/jmxrmi
--list_mbeans Using this parameter, you can list all the Mbeans available on the JMX server. It is set to 1. 
--list_attr Using this parameter you can list all the available attributes of a Mbean, passing the mbean to it. Example: "java.lang:name=G1 Old Generation,type=GarbageCollector".
--conf File with the metrics that the plugin will monitor.
--user JMX server user if necessary to authenticate.
--password JMX server password if needed for authentication.

The use of --list_mbeans, --list_attr and conf parameters to discover and integrate statistics is described in more detail in the chapter: "Discovering statistics and integrating them in the execution".

Parámetros configuración Pandora

--agent_name
Name of the agent that will contain all the statistics modules
--module_prefix Prefix for all modules created by the plugin
--interval Agent monitoring interval
--data_dir
PandoraFMS Data Directory
--group Group in PandoraFMS
--transfer_mode
Data transfer mode, local or tentacle
--tentacle_port
Tentacle Port
--tentacle_address
Tentacle IP

Parámetros extra

--log_file Log file path

Manual execution

The plugin execution format is as follows :

/jmx_querier --jmx_url < jmx url endpoint > \.
[--list_mbeans < 1 or 0 >] \
[--list_attr < mbean name >]].
[--conf < path to conf file with stats >]]
--user < jmx server user >]] \ [--user < jmx server user >] \
--password < jmx server password >]] \ [--password < jmx server password >] \
--agent_name < agent's name >]] \ [--module_prefix < agent's name >] \
[--module_prefix < prefix for modules >] \] \
[--group <group>] \
--interval <interval>] \ [--interval <interval>] \
--temporal <temporal>] \ [--data_dir <temporal>] \
[--data_dir <data_dir>] \] [--transfer_mode <data_dir>] \
--transfer_mode <transfer_mode>] \ [--transfer_mode <transfer_mode>] \
[--tentacle_port <tentacle_port>] \ [--tentacle_port <tentacle_port>] \
[--tentacle_address <tentacle_address>] \ [--log_file <log_file>] \ [--log_file <log_file>] \
[--log_file <log_file>]

For example:

./jmx_querier --jmx_url "service:jmx:rmi:///jndi/rmi://localhost:9090/jmxrmi" --conf jmx.conf --user "controlRole" --password "myPassword"

 

Discovering statistics and integrating them into execution

The plugin has two discovery parameters, which will allow us to discover statistics, which can then be incorporated in a conf file, to monitor them.

--list_mbeans 
This parameter allows us to list all the mbeans on our server, e.g. :

image.png

--list_attr

If this parameter is used, with the name of one of the mbeans listed by the plugin, it will list all the attributes of the mbean, i.e. each statistic, which can then be defined in conf

image.png

Configuration in PandoraFMS

To configure the plugin in PandoraFMS, the following steps must be followed: 


1. Upload the plugin to PandoraFMS, for example in the following path:

/usr/share/pandora_server/util/plugin

2. Go to the plugins section and create a new one:

imagen.png

    3. Name, description and timeout are added:

image.png

4. The path of the plugin is added to the command and the necessary parameters for its execution. 

For each parameter a macro must be configured, the syntax of this macro being the following : _fieldx_, where x is the positional number of the parameter.

image.png

5. The previous macros are configured, adding the value of the parameter in each one:

image.png

6. Once configured, you should create a module in an agent that executes the plugin. In the modules menu of an agent we create a new plugin type module:

imagen.png

7. In the module configuration menu, we name it, select the plugin configured before and click on "create".

image.png

8. The agent will be created with the modules or the modules in the selected agent in the next execution of the plugin.

Agent and modules generated by the plugin

The plugin will create an agent, with the name given by the --agent_name parameter (or JMX by default) that will contain the modules of each statistic defined in the configuration file. So, for example, the execution of this plugin against the following conf:

java.lang:type=Threading/TotalThreadAllocatedBytes
java.lang:type=Threading/CurrentThreadAllocatedBytes
java.lang:type=Threading/ThreadAllocatedMemoryEnabled
java.lang:type=Threading/ThreadAllocatedMemorySupported
java.lang:type=Threading/ThreadCount
java.lang:type=Threading/TotalStartedThreadCount
java.lang:type=Threading/AllThreadIds
java.lang:type=Threading/CurrentThreadCpuTime
java.lang:type=Threading/CurrentThreadUserTime
java.lang:type=Threading/ThreadCpuTimeSupported
java.lang:type=Threading/ThreadCpuTimeEnabled
java.lang:type=Threading/ThreadContentionMonitoringEnabled
java.lang:type=Threading/ThreadContentionMonitoringSupported
java.lang:type=Threading/CurrentThreadCpuTimeSupported
java.lang:type=Threading/ObjectMonitorUsageSupported
java.lang:type=Threading/SynchronizerUsageSupported
java.lang:type=Threading/PeakThreadCount
java.lang:type=Threading/DaemonThreadCount
java.lang:type=Threading/ObjectName

I would create the following modules :

image.png

Defining statistics and thresholds in the configuration file

The statistics (attributes) discovered, can be copied in a configuration file, in which thresholds can also be defined.

For each line in the configuration file an attribute must be added and this will create a module with that statistic in Pandora. If thresholds need to be configured, they must be specified to the right of the attribute, each threshold separated by |. Example:

Metric without threshold 

java.lang:type=Threading/ThreadCount

image.png

Metric with threshold

java.lang:type=Threading/TotalStartedThreadCount|min_warning 30|min_critical 45

image.png