Monitoring Tomcat with Nagios Core and jmx4perl

This articles serves as a reference for Nagios plugin check_jmx4perl and does not aim to provide any installation nor configuration instructions. 

Nagios Environment

Our environment:

1. CentOS 7
2. Nagios Core 4.3.4
3. jmx4perl 1.12

JMX (Java Management Extensions) is the standard management solution in the Java world.

1. jmx4perl is a CLI tool for gathering JMX information,
2. check_jmx4perl is a Nagios plugin for accessing JMX data remotely.

Below is a summary of our application server as well as the URL under which the agent is reachable.

# jmx4perl http://example.com/j4psecured
Name:      Apache Tomcat
Vendor:    Apache
Version:   8.0.35

The following can be used to list all JMX MBeans with their attributes and operations:

# jmx4perl http://example.com/j4psecured list

Plugin version:

# /usr/local/nagios/libexec/check_jmx4perl -V
check_jmx4perl 1.12 [http://www.jmx4perl.org]

Monitoring Tomcat with jmx4perl

Aliases are shortcuts for certain MBean attributes and operations.

How to get a list of available aliases (output truncated):

# perl -MJMX::Jmx4Perl::Alias -e 'JMX::Jmx4Perl::Alias::help'
CL_LOADED                      attr Number of currently loaded classes
CL_TOTAL                       attr Number of classes loaded in total
...
MEMORY_HEAP_MAX                attr Maximum available heap memory
MEMORY_HEAP_USED               attr Used heap memory
...
MEMORY_NONHEAP_MAX             attr Maximum available non-heap memory
MEMORY_NONHEAP_USED            attr Used non-heap memory (like a 'method area')
...
THREAD_COUNT                   attr Active threads in the system
THREAD_COUNT_PEAK              attr Peak thread count
THREAD_COUNT_STARTED           attr Count of threads started since system start
...

How to check for available heap memory:

# ./check_jmx4perl --url http://example.com/j4psecured \
  --alias MEMORY_HEAP_MAX

How to check for used heap memory:

# ./check_jmx4perl --url http://example.com/j4psecured \
  --alias MEMORY_HEAP_USED

We can use MBean attributes to achieve the same if we like:

# ./check_jmx4perl --url http://example.com/j4psecured \
  --mbean "java.lang:type=Memory" \
  --attribute HeapMemoryUsage \
  --path max

# ./check_jmx4perl --url http://example.com/j4psecured \
  --mbean "java.lang:type=Memory" \
  --attribute HeapMemoryUsage \
  --path used

Now, while collecting actual values is useful for graphing and presentation purposes, having them as relative in the range 0 .. 100% is better for monitoring, e.g. we can configure Nagios to send an email when the value reaches 90%.

How to check that used heap memory is less than 90% of the available memory:

# ./check_jmx4perl --url http://example.com/j4psecured \
  --alias MEMORY_HEAP_USED \
  --base MEMORY_HEAP_MAX \
  --critical 90

The same result as above, but using MBean attributes:

# ./check_jmx4perl --url http://example.com/j4psecured \
  --value "java.lang:type=Memory/HeapMemoryUsage/used" \
  --base "java.lang:type=Memory/HeapMemoryUsage/max" \
  --critical 90

How to check for garbage collection time:

# ./check_jmx4perl --url http://example.com/j4psecured \
 --mbean "java.lang:type=GarbageCollector,name=PS MarkSweep" \
 --attribute CollectionTime \
 --name GC_CollectionTime

How to check for garbage collection count:

# ./check_jmx4perl --url http://example.com/j4psecured \
 --mbean "java.lang:type=GarbageCollector,name=PS MarkSweep" \
 --attribute CollectionTime \
 --name GC_CollectionCount

How to check for a number of threads started in one hour (3600 seconds):

# ./check_jmx4perl --url http://example.com/j4psecured \
 --alias THREAD_COUNT_STARTED \
 --delta 3600 \
 --critical 200

How to check for active threads compared with a count of threads started since system start:

# ./check_jmx4perl --url http://example.com/j4psecured \
 --alias THREAD_COUNT \
 --base THREAD_COUNT_STARTED

How to check for metaspace usage:

# ./check_jmx4perl --url http://example.com/j4psecured \
 --value "java.lang:type=MemoryPool,name=Metaspace/Usage/used" \
 --base "java.lang:type=MemoryPool,name=Metaspace/Usage/max" \
 --critical 90

How to check for code cache usage:

# ./check_jmx4perl --url http://example.com/j4psecured \
 --value "java.lang:type=MemoryPool,name=Code Cache/Usage/used" \
 --base "java.lang:type=MemoryPool,name=Code Cache/Usage/max" \
 --critical 95

How to check for loaded class usage:

# ./check_jmx4perl --url http://example.com/j4psecured \
 --alias CL_LOADED \
 --base CL_TOTAL \
 --critical 95

References

https://exchange.nagios.org/directory/Plugins/Java-Applications-and-Servers/check_jmx4perl/details
http://search.cpan.org/~roland/jmx4perl/