Module jdk.management

Package com.ibm.lang.management

Interface JvmCpuMonitorMXBean

All Superinterfaces:

PlatformManagedObject

All Known Implementing Classes:

JvmCpuMonitor

public interface JvmCpuMonitorMXBean
extends PlatformManagedObject

This interface provides APIs to obtain JVM CPU usage information in terms of thread categories. APIs are also available to get and set the thread category.

1. The top level thread categories are "System-JVM", "Application", and "Resource-Monitor".
2. The "System-JVM" category is further divided into "GC", "JIT", and "Other" and is an aggregate of the three categories.
3. The "Application" category can be further divided, if required, in to a maximum of five user defined categories. These are called "Application-User1" through to "Application-User5".
4. The application can designate any of its threads to be part of any user defined category.
5. The application can also designate any of its threads as a "Resource-Monitor". "Resource-Monitor" threads are special because they do not participate in idle accounting. This means that any CPU usage of these threads does not count towards determining the state of the application.
6. A thread can be part of only one category at any given time but can change categories any number of times during its timeline.
7. The usage information is in microseconds and increases monotonically.
8. The CPU usage information consists of the following data:
   1. Attached threads that are live.
   2. Attached threads that have previously exited.
   3. Threads attached to the JVM for the period that they were attached.
9. CPU usage information notes:
   1. Unattached native threads are not reflected.
   2. Finalizer worker threads are considered as "Application" threads.
   3. Threads of any category that participate in GC activity are accounted for in the "GC" category for the duration of the activity if the -XX:-ReduceCPUMonitorOverhead is specified. See the user guide for more information on this option.
   4. If the application thread switches categories, the CPU usage is measured against each category for the duration of time that the thread spends in that category.

This information is based on repeatedly checking the CPU usage in the following use case scenarios:

1. Monitoring application idle and active behavior.
2. Calculating the JVM Overhead over a specific interval.
3. Collecting transaction metrics for a specific set of application threads over a specific duration.

Usage example for the JvmCpuMonitorMXBean

 
   ...
   try {
      mxbeanName = new ObjectName("com.ibm.lang.management:type=JvmCpuMonitor");
   } catch (MalformedObjectNameException e) {
      // Exception Handling
   }
   try {
      MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
      if (true != mbeanServer.isRegistered(mxbeanName)) {
         // JvmCpuMonitorMXBean not registered
      }
      JvmCpuMonitorMXBean jcmBean = JMX.newMXBeanProxy(mbeanServer, mxbeanName, JvmCpuMonitorMXBean.class); 
   } catch (Exception e) {
      // Exception Handling
   }
 
 

Method Summary

Modifier and Type	Method	Description
String	getThreadCategory(long id)	This function gets the current value of the thread category for the target thread.
JvmCpuMonitorInfo	getThreadsCpuUsage()	This function creates a new JvmCpuMonitorInfo object and populates it with CPU usage statistics of the various thread categories.
JvmCpuMonitorInfo	getThreadsCpuUsage(JvmCpuMonitorInfo jcmInfo)	This function updates the user provided JvmCpuMonitorInfo object with CPU usage statistics of the various thread categories.
int	setThreadCategory(long id, String category)	This function sets the thread category of the target thread.

Methods declared in interface java.lang.management.PlatformManagedObject

getObjectName

Method Detail

getThreadsCpuUsage

JvmCpuMonitorInfo getThreadsCpuUsage(JvmCpuMonitorInfo jcmInfo)
                              throws NullPointerException,
                                     UnsupportedOperationException

This function updates the user provided JvmCpuMonitorInfo object with CPU usage statistics of the various thread categories. The statistics are an aggregate across all CPUs of the operating system.

Parameters:

jcmInfo - User provided JvmCpuMonitorInfo object.

Returns:

the updated JvmCpuMonitorInfo instance.

Throws:

NullPointerException - if a null reference is passed.

UnsupportedOperationException - if CPU monitoring is disabled.

getThreadsCpuUsage

JvmCpuMonitorInfo getThreadsCpuUsage()
                              throws UnsupportedOperationException

This function creates a new JvmCpuMonitorInfo object and populates it with CPU usage statistics of the various thread categories. The statistics are an aggregate across all CPUs of the operating system.

Returns:

the new JvmCpuMonitorInfo instance.

Throws:

UnsupportedOperationException - if CPU monitoring is disabled.

setThreadCategory

int setThreadCategory(long id,
                      String category)
               throws IllegalArgumentException

This function sets the thread category of the target thread. Valid categories are

1. "Resource-Monitor"
2. "Application"
3. "Application-User1" through to "Application-User5"

Some notes on the setting the thread categories

1. "Application" threads cannot be changed to any "System-JVM" category.
2. Threads in the "System-JVM" category cannot be modified.
3. Once a thread is designated as "Resource-Monitor", it cannot be changed.

Parameters:

id - The target thread id for which the type needs to be set.

category - The category of the target thread.

Returns:

-1 to indicate failure or 0 on success.

Throws:

IllegalArgumentException - if a value is passed for the thread category or thread id that is not valid.

getThreadCategory

String getThreadCategory(long id)
                  throws IllegalArgumentException

This function gets the current value of the thread category for the target thread.

Parameters:

id - The target thread id for which we need the thread category.

Returns:

NULL to indicate failure, else the category string of the target thread.

Throws:

IllegalArgumentException - if the thread id is not valid.