1. Anders Welen Avatar Anders Welen
  2. JMole
  3. JMole

Wiki

Clone wiki

JMole / Configuration

View History

JMole Core

The core of JMole is controlled by Java system properties and can be easily be set using for example the "-D" flag.

JMole core system properties (default values within parentheses):

  • jmole.config.filename.XXX(-): Specify a JMole config file to read. Replace XXX to specify more than one config file. The file needs to be on the classpath or specified with a complete path
  • jmole.config.filenames("JMole_JVM.xml"): A list of config files (found in the configs directory) to use (separated by |). These needs to be on the classpath or specified with a complete path. THIS OPTION IS DEPRECATED, USE A COMBINATION OF "jmole.config.filename.XXX" INSTEAD!
  • jmole.config.xslt.XXX(-): Specifies a XSLT file to execute on the config file matching XXX (See option "jmole.config.filename.XXX"). Useful for overriding values or add extra setup without editing the base config file.
  • jmole.config.level(3): A threshold level controlling which measurements that should be activated. (1 means just a few very basic and 5 means all)
  • jmole.mbeanserver.agentid(null): If JMole should connect to some other MBean server/agent than the platform MBean server you can provide a regexp to identify which one. If you do not know the name of the MBean server just provide a regexp that will not match and look at the log message for a list of available MBean servers.

The configuration files are in XML which represents the actual internal Java Objects used in JMole for discovery and information gathering.

The MBean net.welen.jmole:service=jmole provide some methods that can be invoked in runtime (instead of having to restart the JVM):

  • configure: Trigger JMole to re-read its configuration files.

The various integration with monitoring tools have their own settings using the same approach and are described below.

JMX/MBean

The MBean net.welen.jmole:service=jmole can be used collect information. The following methods may be of interest:

  • collectMeasurements: Returns a list with all found measurements
  • collectMeasurements(String category): Returns a list with all found measurements for the specified category
  • collectMeasurements(String category, String name): Returns a list with all found measurements for the specified category and name
  • collectMeasurement(String category, String name, String attribute): Returns the measurement for the specified category, name and attribute
  • warningMessages: Return all current warning messages
  • criticalMessages: Return all current critical messages

Note that there are also variant of these that return JSON documents for easy parsing.

The JMole MBean also sends out JMX Notifications for warnings and critical messages. If you want to listen to these you need jmole-jmx/target/jmole-jmx-XXX.jar in your classpath.

An alternative to use remote JMX is Jolokia. In JEE just deploy the "WAR Agent" and try the following http requests:

http://localhost:8080/jolokia/exec/net.welen.jmole:service=jmole/warningMessages
http://localhost:8080/jolokia/exec/net.welen.jmole:service=jmole/criticalMessages
http://localhost:8080/jolokia/exec/net.welen.jmole:service=jmole/collectMeasurements()
http://localhost:8080/jolokia/exec/net.welen.jmole:service=jmole/collectMeasurements(java.lang.String)/JVM
http://localhost:8080/jolokia/exec/net.welen.jmole:service=jmole/collectMeasurements(java.lang.String,java.lang.String)/JVM/Threads
http://localhost:8080/jolokia/exec/net.welen.jmole:service=jmole/collectMeasurements(java.lang.String,java.lang.String,java.lang.String)/JVM/Threads/ThreadCount

Configuration of built-in and shipped monitoring systems/protocols

These protocols are built-in with JMole and are ready to activate out-of-the-box.

Built-in

Standard Java Logging

The standard java logging protocol system properties (default values within parentheses):

  • jmole.protocol.logger.enabled(false): Should the protocol be enabled?
  • jmole.protocol.logger.name(JMole): The logger name to use
  • jmole.protocol.logger.level(INFO): The logger level to use
  • jmole.protocol.logger.format("[%k] %a [%A] = %v %U"): Format (%k=Key, %a=Attribute, %A=Attribute description, %v=Value, %U=Unit). As an alternative output in JSON will be used if the property is set to "JSON".
  • jmole.protocol.logger.interval(60000): The interval between sending the data (in ms)

Munin

The Munin protocol consists of a TCP Server Socket implementing the Munin protocol. JMole should support version 1.4.0 and newer. The munin server needs to know of this new munin node by adding it to the munin.conf file:

[JMole]
    address myserver.welen.net
    port 4949

The Munin protocol system properties (default values within parentheses):

  • jmole.protocol.munin.enabled(false): Should the protocol be enabled?
  • jmole.protocol.munin.name("jmole"): The identifying string sent to the Munin server
  • jmole.protocol.munin.address(127.0.0.1): The network address to bind to
  • jmole.protocol.munin.port(4949): The TCP port to bind to
  • jmole.protocol.munin.tcpReadTimeOut(10000): TCP read timeout
  • jmole.protocol.munin.maxThreads(5): Maximal concurrent threads

logstash

The logstash protocol system properties (default values within parentheses):

  • jmole.protocol.logstash.enabled(false): Should the protocol be enabled?
  • jmole.protocol.logstash.host(localhost): logstash server hostname
  • jmole.protocol.logstash.port(5000): logstash server port
  • jmole.protocol.logstash.useSSL(false): Use SSL?
  • jmole.protocol.logstash.keepAlive(false): Use keepAlive?
  • jmole.protocol.logstash.interval(60000): The interval between sending the data (in ms)

The following setup is needed in logstash

input {
    tcp {
        port => 5000
        codec => json
    }
}

NRPE

JMole supports the NRPE protocol used by Nagios, Icinga etc.

The NRPE protocol system properties (default values within parentheses):

  • jmole.protocol.nrpe.enabled(false): Should the protocol be enabled?
  • jmole.protocol.nrpe.address(127.0.0.1): The network address to bind to
  • jmole.protocol.nrpe.port(5666): The TCP port to bind to
  • jmole.protocol.nrpe.acceptedHosts(127.0.0.1): List of hosts (separated by ,) to accept calls from (Not implemented yet!)
  • jmole.protocol.nrpe.useSSL(false): Use SSL? (Not implemented yet!)
  • jmole.protocol.nrpe.maxMessageSize(1024): Max messagebuffer size to return to NRPE.

Get all warning messages:

check_nrpe -n -H 127.0.0.1 -c checkWarnings

Get all critical messages:

check_nrpe -n -H 127.0.0.1 -c checkCriticals

Fetching individual values:

check_nrpe -n -H 127.0.0.1 -c getValue -a JVM Uptime Uptime

Some versions of check_nrpe seems to send an extra empty "$". In these cases the following alternative should work:

check_nrpe -n -H 127.0.0.1 -c getValue -a JVM Uptime Uptime 0:0 0:0

Fetching individual values with check (providing levels for Warning and Critical):

check_nrpe -n -H 127.0.0.1 -c getValue -a JVM Uptime Uptime 11:99 200:

Fetching all values for a measuremnt:

check_nrpe -n -H 127.0.0.1 -c getValue -a JVM "Heap Memory"

Use the MBean net.welen.jmole:service=jmole to find out the actual measurement (like "JVM Uptime Uptime" in the examples above).

See https://bitbucket.org/awelen/jmole/src/master/jmole-integrationtests/jmole-test-protocols/src/test/resources/nagios.cfg for an example how to configure Nagios to use it.

Eclipse Microprofile

Enabling this protocol is done by deployment jmole-microprofile2-XXX-jar-with-dependencies.jar or jmole-microprofile3-XXX-jar-with-dependencies.jar. All measurements found by JMole will appear as Eclipse Microprofile Metrics.

The Eclipse Microprofile protocol system properties (default values within parentheses):

  • jmole.protocol.microprofile.health.includeWarnings(false): Should warnings be included in report?
  • jmole.protocol.microprofile.health.downIfWarnings(false): Should any warnings indicate "down" status
  • jmole.protocol.microprofile.health.excludeErrors(false): Should errors be excluded from report?
  • jmole.protocol.microprofile.health.includeMeasurements(false): Should measurements be included in report?

Shipped with JMole

These protocols are shipped with JMole as separate JAR-files (jmole-protocol-* projects). These jarfiles needs to be on the classpath of the JVM.

StatsD

The StatsD protocol system properties (default values within parentheses):

  • jmole.protocol.statsd.enabled(false): Should the protocol be enabled?
  • jmole.protocol.statsd.prefix(JMole): The prefix to use
  • jmole.protocol.statsd.host(localhost): The address of the StatsD server
  • jmole.protocol.statsd.port(8125): The port of the StatsD server
  • jmole.protocol.statsd.interval(60000): The interval between sending the data (in ms)

syslog

The syslog protocol system properties (default values within parentheses):

  • jmole.protocol.syslog.enabled(false): Should the protocol be enabled?
  • jmole.protocol.syslog.useTCP(false): Use TCP?
  • jmole.protocol.syslog.messageHostName(-): Message hostname
  • jmole.protocol.syslog.applicationName(JMole):
  • jmole.protocol.syslog.format(RFC_3164): Messageformat (RFC_3164/RFC_5424)
  • jmole.protocol.syslog.logFormat("%k] %a [%A] = %v %U"): Format (%k=Key, %a=Attribute, %A=Attribute description, %v=Value, %U=Unit)
  • jmole.protocol.syslog.useSSL(false): Use SSL?
  • jmole.protocol.syslog.host(localhost): syslog server hostname
  • jmole.protocol.syslog.port(514): syslog server port
  • jmole.protocol.syslog.interval(60000): The interval between sending the data (in ms)

Zabbix

The Zabbix implementation supports auto discovery, value fetching and value triggering by importing the provided template (https://bitbucket.org/awelen/jmole/src/master/jmole-kernel/configs/JMole_Zabbix_Template.xml) into Zabbix and then configuring a new host that uses it.

The Zabbix protocol system properties (default values within parentheses):

  • jmole.protocol.zabbix.enabled(false): Should the protocol be enabled?
  • jmole.protocol.zabbix.passive(true): Should the agent be passive and wait for Zabbix to connect to it
  • jmole.protocol.zabbix.listen.address(0.0.0.0): If passive this states the bind address
  • jmole.protocol.zabbix.listen.port(10050): If passive this states the bind port
  • jmole.protocol.zabbix.active(false): Should the agent be active and connect to Zabbix itself
  • jmole.protocol.zabbix.hostname(JMole): If active this states which name it should be identified by in Zabbix
  • jmole.protocol.zabbix.server.address(localhost): If active this states which address Zabbix has
  • jmole.protocol.zabbix.server.port(10051): If active this states which port Zabbix has

Note: Issue #92

Amazon CloudWatch

The Amazon CloudWatch protocol system properties (default values within parentheses):

  • jmole.protocol.cloudwatch.enabled(false): Should the protocol be enabled?
  • jmole.protocol.cloudwatch.namespace(JMole): Namespace to use
  • jmole.protocol.cloudwatch.interval(60000): The interval between sending the data (in ms)

Adding your own protocol

Implementation needs to implement the interface net.welen.jmole.JMole.Protocol.

The following system properties is used to activate the protocol

  • jmole.protocol.XXX.enabled: Should the protocol be enabled?
  • jmole.protocol.XXX.classname: Specifies the class implementing the protocol
  • jmole.protocol.XXX.jars: Comma-separated list of URL's specifying the JAR files to load

An alternative to using "jmole.protocol.XXX.jars" is to put needed jars on the classpath of the JVM.

Updated