CLI-based utility
The command line (CLI)-based tool is not installed by default. It is available as an RPM package in the official repositories.
Installation
yum install opennms-jmx-config-generator
apt-get install opennms-jmx-config-generator
Installation from source
It is required to have the Java 8 Development Kit with Apache Maven installed.
The mvn
binary has to be in the path environment.
After cloning the repository you have to enter the source folder and compile an executable JAR.
cd opennms/features/jmx-config-generator
mvn package
Inside the newly created target
folder a file named jmxconfiggenerator-<VERSION>-onejar.jar
is present.
This file can be invoked by:
java -jar target/jmxconfiggenerator-2022.1.28-onejar.jar
Use
After installing the the JMX Config Generator the tool’s wrapper script is located in the ${OPENNMS_HOME}}/bin
directory.
$ cd /path/to/opennms/bin
$ ./jmx-config-generator
When invoked without parameters the usage and help information is printed. |
The JMX Config Generator uses sub-commands for the different configuration generation tasks. Each of these sub-commands provide different options and parameters. The command line tool accepts the following sub-commands.
Sub-command | Description |
---|---|
query |
Queries an MBean Server for certain MBeans and attributes. |
generate-conf |
Generates a valid |
generate-graph |
Generates an RRD graph definition file with matching graph definitions for a given |
The following global options are available in each of the sub-commands of the tool:
Option/Argument | Description | Default |
---|---|---|
-h (--help) |
Show help and usage information. |
false |
-v (--verbose) |
Enables verbose mode for debugging purposes. |
false |
Sub-command: query
This sub-command is used to query a MBean Server for its available MBean objects.
The following example queries the server myserver
with the credentials myusername/mypassword
on port 7199
for MBean objects in the java.lang
domain.
./jmx-config-generator query --host myserver --username myusername --password mypassword --port 7199 "java.lang:*"
java.lang:type=ClassLoading
description: Information on the management interface of the MBean
class name: sun.management.ClassLoadingImpl
attributes: (5/5)
TotalLoadedClassCount
id: java.lang:type=ClassLoading:TotalLoadedClassCount
description: TotalLoadedClassCount
type: long
isReadable: true
isWritable: false
isIs: false
LoadedClassCount
id: java.lang:type=ClassLoading:LoadedClassCount
description: LoadedClassCount
type: int
isReadable: true
isWritable: false
isIs: false
<output omitted>
The following command line options are available for the query sub-command.
Option/Argument | Description | Default |
---|---|---|
<filter criteria> |
A filter criteria to query the MBean Server for.
The format is |
- |
--host <host> |
Hostname or IP address of the remote JMX host. |
- |
--ids-only |
Only show the ids of the attributes. |
false |
--ignore <filter criteria> |
Set |
- |
--include-values |
Include attribute values. |
false |
--jmxmp |
Use JMXMP and not JMX over RMI. |
false |
--password <password> |
Password for JMX authentication. |
- |
--port <port> |
Port of JMX service. |
- |
--show-domains |
Only lists the available domains. |
true |
--show-empty |
Includes MBeans, even if they do not have attributes
Either due to the |
false |
--url <url> |
Custom connection URL |
- |
--username <username> |
Username for JMX authentication. |
- |
-h (--help) |
Show help and usage information. |
false |
-v (--verbose) |
Enables verbose mode for debugging purposes. |
false |
Sub-command: generate-conf
This sub-command can be used to generate a valid jmx-datacollection-config.xml
for a given set of MBean objects queried from a MBean Server.
The following example generate a configuration file myconfig.xml
for MBean objects in the java.lang
domain of the server myserver
on port 7199
with the credentials myusername/mypassword
.
You have to define either an URL or a hostname and port to connect to a JMX server.
jmx-config-generator generate-conf --host myserver --username myusername --password mypassword --port 7199 "java.lang:*" --output myconfig.xml
Dictionary entries loaded: '18'
The following options are available for the generate-conf sub-command.
Option/Argument | Description | Default |
---|---|---|
<attribute id> |
A list of attribute Ids to be included for the generation of the configuration file. |
- |
--dictionary <file> |
Path to a dictionary file for replacing attribute names and part of MBean attributes. The file should have for each line a replacement, e.g. Auxillary:Auxil. |
- |
--host <host> |
Hostname or IP address of JMX host. |
- |
--jmxmp |
Use JMXMP and not JMX over RMI. |
false |
--output <file> |
Output filename to write generated |
- |
--password <password> |
Password for JMX authentication. |
- |
--port <port> |
Port of JMX service |
- |
--print-dictionary |
Prints the used dictionary to STDOUT.
May be used with |
false |
--service <value> |
The service name used as JMX data collection name. |
anyservice |
--skipDefaultVM |
Skip default JavaVM Beans. |
false |
--skipNonNumber |
Skip attributes with non-number values |
false |
--url <url> |
Custom connection URL |
- |
--username <username> |
Username for JMX authentication |
- |
-h (--help) |
Show help and usage information. |
false |
-v (--verbose) |
Enables verbose mode for debugging purposes. |
false |
The option --skipDefaultVM offers the ability to ignore the MBeans provided as standard by the JVM and just create configurations for the MBeans provided by the java application itself.
This is particularly useful if an optimized configuration for the JVM already exists.
If the --skipDefaultVM option is not set the generated configuration will include the MBeans of the JVM and the MBeans of the Java Application.
|
Check the file and see if there are alias names with more than 19 characters.
This errors are marked with NAME_CRASH_AS_19_CHAR_VALUE
|
Sub-command: generate-graph
This sub-command generates a RRD graph definition file for a given configuration file.
The following example generates a graph definition file mygraph.properties
using the configuration in file myconfig.xml
.
./jmx-config-generator generate-graph --input myconfig.xml --output mygraph.properties
reports=java.lang.ClassLoading.MBeanReport, \
java.lang.ClassLoading.0TotalLoadeClassCnt.AttributeReport, \
java.lang.ClassLoading.0LoadedClassCnt.AttributeReport, \
java.lang.ClassLoading.0UnloadedClassCnt.AttributeReport, \
java.lang.Compilation.MBeanReport, \
<output omitted>
The following options are available for this sub-command.
Option/Argument | Description | Default |
---|---|---|
--input <jmx-datacollection.xml> |
Configuration file to use as input to generate the graph properties file |
- |
--output <file> |
Output filename for the generated graph properties file. |
- |
--print-template |
Prints the default template. |
false |
--template <file> |
Template file using Apache Velocity template engine to be used to generate the graph properties. |
- |
-h (--help) |
Show help and usage information. |
false |
-v (--verbose) |
Enables verbose mode for debugging purposes. |
false |
Graph Templates
The JMX Config Generator uses a template file to generate the graphs.
It is possible to use a user-defined template.
The option --template
followed by a file lets the JMX Config Generator use the external template file as base for the graph generation.
The following example illustrates how a custom template mytemplate.vm
is used to generate the graph definition file mygraph.properties
using the configuration in file myconfig.xml
.
./jmx-config-generator generate-graph --input myconfig.xml --output mygraph.properties --template mytemplate.vm
The template file has to be an Apache Velocity template. The following sample represents the template that is used by default:
reports=#foreach( $report in $reportsList )
${report.id}#if( $foreach.hasNext ), \
#end
#end
#foreach( $report in $reportsBody )
#[[###########################################]]#
#[[##]]# $report.id
#[[###########################################]]#
report.${report.id}.name=${report.name}
report.${report.id}.columns=${report.graphResources}
report.${report.id}.type=interfaceSnmp
report.${report.id}.command=--title="${report.title}" \
--vertical-label="${report.verticalLabel}" \
#foreach($graph in $report.graphs )
DEF:${graph.id}={rrd${foreach.count}}:${graph.resourceName}:AVERAGE \
AREA:${graph.id}#${graph.coloreB} \
LINE2:${graph.id}#${graph.coloreA}:"${graph.description}" \
GPRINT:${graph.id}:AVERAGE:" Avg \\: %8.2lf %s" \
GPRINT:${graph.id}:MIN:" Min \\: %8.2lf %s" \
GPRINT:${graph.id}:MAX:" Max \\: %8.2lf %s\\n" \
#end
#end
The JMX Config Generator generates different types of graphs from the jmx-datacollection-config.xml
.
The different types are listed below:
Type | Description |
---|---|
AttributeReport |
For each attribute of any MBean a graph will be generated. Composite attributes will be ignored. |
MbeanReport |
For each MBean a combined graph with all attributes of the MBeans is generated. Composite attributes will be ignored. |
CompositeReport |
For each composite attribute of every MBean a graph is generated. |
CompositeAttributeReport |
For each composite member of every MBean a combined graph with all composite attributes is generated. |