JMX ThreadInfo Plug-in - Technical Reference

Introduction

The Geneos JMX ThreadInfo Plug-in allows for the monitoring of the thread sub-system of JMX-enabled applications. These include applications which have been written to expose their state by implementing the JMX specification, for example, Tomcat 6.0.

Java requirements

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

Views

The plug-in produces a single view, a representative example of which is given below:

jmx-threadinfo2

Headline Legend

Name Description
DaemonThreadCount the current number of live daemon threads
PeakThreadCount the peak live thread count since the Java virtual machine started or peak was reset
ThreadCount the current number of live threads including both daemon and non-daemon threads
TotalStartedThreadCount the total number of threads created and also started since the Java virtual machine started.
ThreadContentionMonitoringEnabled if thread contention monitoring is enabled
ThreadContentionMonitoringSupported if the Java virtual machine supports thread contention monitoring
ThreadCpuTimeEnabled if thread CPU time measurement is enabled.
ThreadCpuTimeSupported if the Java virtual machine implementation supports CPU time measurement for any thread

Table Legend

Name Description
threadName The name of a particular thread in the jvm
threadId The id for a particular thread in the jvm
threadState One of the following states: NEW, RUNNABLE, BLOCKED, WAITING, TIMED_WAITING, TERMINATED
suspended Whether the thread is suspended or not
blockedCount the total number of times that this thread blocked to enter or reenter a monitor
blockedTime the approximate accumulated elapsed time (in milliseconds) that this thread has blocked to enter or reenter a monitor since thread contention monitoring is enabled
lockOwnerId the ID of the thread which owns the object for which this thread is blocked waiting
lockOwnerName the name of the thread which owns the object for which this thread is blocked waiting
lockName the string representation of the object for which this thread is blocked waiting
waitedCount the total number of times that this thread waited for notification
waitedTime the approximate accumulated elapsed time (in milliseconds) that this thread has waited for notification since thread contention monitoring is enabled
inNative Tests if this thread is executing native code via the Java Native Interface (JNI).
threadCpuTime the total CPU time for this thread in nanoseconds
threadUserTime the CPU time that this thread has executed in user mode in nanoseconds

Plug-in Configuration

Note: You can safely update most of the configuration options on this plug-in without causing the Netprobe to restart. The exception is the jproperties option. If you update this option, then the Netprobe restarts.

connection

Identifies the set of settings required to connect to the monitored Java application.

connection > serviceUrl

Specifies the location where the monitored application resides, e.g.

service:jmx:rmi:///jndi/rmi://192.168.10.161:25000/jmxrmi

connection > username

Identifies a particular setting required to connect to the monitored Java application.

connection > password

Specifies the password with which to connect to a secured Java application. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > timeout

Specifies the number of milliseconds to wait for connections to be established. This setting should not be used unless it is found that the sampler seems to be waiting for inordinate amounts of time to connect to an application which is clearly down. This allows a timeout which the user decides is appropriate, for which to wait for a connection, before deciding that the application should be considered down.

headlineLabels

Allows the user to configure just those headlines that they are interested in. If this section is blank, then all the headlines will be displayed in the dataview.

headlineLabels > headlineLabel

Identifies one of a prefixed set of thread attributes which should be displayed as a headline.

Possible values:

Setting Description
DaemonThreadCount the current number of live daemon threads
PeakThreadCount the peak live thread count since the Java virtual machine started or peak was reset
ThreadCount the current number of live threads including both daemon and non-daemon threads
TotalStartedThreadCount the total number of threads created and also started since the Java virtual machine started.
ThreadContentionMonitoringEnabled if thread contention monitoring is enabled
ThreadContentionMonitoringSupported if the Java virtual machine supports thread contention monitoring
ThreadCpuTimeEnabled if thread CPU time measurement is enabled.
ThreadCpuTimeSupported if the Java virtual machine implementation supports CPU time measurement for any thread

Mandatory: No

tablecolLabels

Allows the user to specify one or more column headers to display. If this is not enabled then all the column headers are displayed.

Mandatory: No

tablecolLabels > tablecolLabel

Identifies one of a prefixed set of thread attributes which should be displayed in a table column

Possible values:

Setting Description
threadId The id for a particular thread in the jvm
threadState One of the following states: NEW, RUNNABLE, BLOCKED, WAITING, TIMED_WAITING, TERMINATED
suspended Whether the thread is suspended or not
blockedCount the total number of times that this thread blocked to enter or reenter a monitor
blockedTime the approximate accumulated elapsed time (in milliseconds) that this thread has blocked to enter or reenter a monitor since thread contention monitoring is enabled
lockOwnerId the ID of the thread which owns the object for which this thread is blocked waiting
lockOwnerName the name of the thread which owns the object for which this thread is blocked waiting
lockName the string representation of the object for which this thread is blocked waiting
waitedCount the total number of times that this thread waited for notification
waitedTime the approximate accumulated elapsed time (in milliseconds) that this thread has waited for notification since thread contention monitoring is enabled
inNative Tests if this thread is executing native code via the Java Native Interface (JNI).
threadCpuTime the total CPU time for this thread in nanoseconds
threadUserTime the CPU time that this thread has executed in user mode in nanoseconds

Mandatory: No

jproperties

Allows the user to specify additional flags with which to configure the JVM which the probe creates.

Mandatory: No

jproperties > jproperty

Allows user to specify a comma separated list of supported JVM arguments. This comprises those flags which begin with -D or the -verbose flag. Flags starting with -X are JVM implementation dependent and may or may not work.

For example,

JProperties=-Xms2M,-Xmx4M,-verbose

Mandatory: No

logJavaMemoryInfo

Whether java heap usage should be logged every 10 minutes to the netprobe log file or not.

Possible values:

Setting Description
true java heap usage should be logged every 10 minutes
false java heap usage should not be logged every 10 minutes
Mandatory: No
Default: false

Additional Files

The plug-in requires the following files to be present in the net probe directory:

ITRS provided files:

  1. launchpad.jar
  2. jmx-plugins.jar
  3. jep-2.3.0.jar
  4. launchPad.dll (Windows) or liblaunchpad.so (UNIX/LINUX)

In addition, Microsoft.VC80.CRT redistributables are required when using AES-256 passwords in Windows machines.

Current Limitations

Attribute Types

The requested attribute must be either a primitive (e.g. boolean, short, integer, long, float, double) or a reference to an object for which toString() has been overidden to provide a sensible human viewable value. If an attribute is requested which violates these constraints, then the information published to the dataview is likely to not be useful. Please see section 2.7 for some exceptions to this rule.

Whitespaces In MBean Aliases

The plug-in does not accept mbean aliases that contain leading or trailing whitespace. It does however, accept mbean aliases which contain whitespace within the actual alias.

Connecting to applications using password and access files

Java supports the use of password files and access files to restrict access to a jmx-enabled application. In this case the plugin also needs to provide a username and password before being allowed to connect to and retrieve information from the application.

We explain how to configure a sample Java application for authenticated access and then show how to configure the plugin to connect to that application. The instructions given are suitable for UNIX and LINUX.

Please see http://java.sun.com/j2se/1.5.0/docs/guide/management/security-windows.html for instructions on how to secure an application for windows.

Securing the application

The first thing to ensure is that we have a valid rolename-permission pair in the access file that resides inside the JRE installation directory i.e. $JRE/management/jmxremote.access:

By default the following rolename-permission pairs exist:

monitorRole     readonly
controlRole     readwrite

So we add our own entry choosing kyoto as our rolename and granting it readwrite access.

Our file should now look like this:

monitorRole     readonly
controlRole     readwrite
kyoto           readwrite

We then create a local password file called jmxremote.password in our current working directory. We need to chmod 600 the file otherwise Java will complain and not use the file. We then add our rolename along with origami as the password of our choice.

The jmxremote.password file should now look like this:

kyoto           origami

Assuming our application is a standalone class file called JmxServer we can now start the application passing the following flags to the Java command:

java -Dcom.sun.management.jmxremote
     -Dcom.sun.management.jmxremote.port=5003
     -Dcom.sun.management.jmxremote.ssl=false
     -Dcom.sun.management.jmxremote.authenticate=true
     -D com.sun.management.jmxremote.password.file=/jmxremote.password
     JmxServer

Note: We have now specified true for the authenticate flag and passed in the absolute path of where to find the jmxremote.password file.

Finally we configure a jmx-threadinfo plugin to connect to our secured application and retrieve some information about the threads currently running in its JVM:

// Sampler Descriptor
Plugin=JMX-THREADINFO
Settings=@Settings
GroupName=JMX
ViewName=THREADS
HeadlineLabels=@Headlines
TableColLabels=@TableCols
// Additional Data section(Settings)
ServiceURL=service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi
username=kyoto
password=origami

Note: When setting a password, user will have the option of entering the password in encrypted form. Plugin settings will not show the password in plaintext, but in encrypted text.

// Additional Data section(Headlines)
DaemonThreadCount
PeakThreadCount
// Additional Data section(TableCols)
threadName
threadId
threadState