Summary

com.sun.management.OperatingSystemMXBean is the JDK-specific monitoring interface for the operating system. Update the description of the methods getProcessCpuLoad(), getCpuLoad(), and getSystemCpuLoad() to better describe how this methods should be used.

Problem

The CPU usage related methods in com.sun.management.OperatingSystemMXBean; getProcessCpuLoad() and getCpuLoad() (and its deprecated counterpart getSystemCpuLoad()) each return a value representing the "recent CPU usage". The recent CPU usage is typically calculated by observing the number of ticks spent in either the JVM process or the whole system for a period of time. The observation period is defined by the time passed since the last call to the method; this is not clearly explained in the Javadoc leading to confusion among users. If a method is called twice with not enough ticks in between, results can be reported as 0.0, or 1.0, due to not having enough data points.

This being an MXBean means it can also be called indirectly and remotely, which makes it hard, if not impossible, to have full control of what the observation period will be.

Solution

The documentation will be updated to more clearly describe what constitutes an observation period, and make users aware of the effects of intervening callers.

Specification

All three methods have virtually the same wording. A section explaining the observation period will be added and an API note will mention the effects of intervening callers.

Original (only showing getProcessCpuLoad())

Returns the "recent cpu usage" for the Java Virtual Machine process. This value is a double in the [0.0,1.0] interval. A value of 0.0 means that none of the CPUs were running threads from the JVM process during the recent period of time observed, while a value of 1.0 means that all CPUs were actively running threads from the JVM 100% of the time during the recent period being observed. Threads from the JVM include the application threads as well as the JVM internal threads. All values between 0.0 and 1.0 are possible depending of the activities going on in the JVM process and the whole system. If the Java Virtual Machine recent CPU usage is not available, the method returns a negative value.

Updated

 Returns the "recent CPU usage" for the Java Virtual Machine process.
 This value is a double in the [0.0,1.0] interval. A value of 0.0 means
 that none of the CPUs were running threads from the JVM process during
 the recent period of time observed, while a value of 1.0 means that all
 CPUs were actively running threads from the JVM 100% of the time
 during the recent period being observed. Threads from the JVM include
 the application threads as well as the JVM internal threads.

 The recent period of observation is implementation-specific, and
 typically relates to the duration since the last call made to this
 method. For the very first invocation, the recent period of observation
 is undefined.

 All values between 0.0 and 1.0 are possible dependent on the activities
 going on in the JVM process and the whole system. If the Java Virtual
 Machine recent CPU usage is not available, the method returns a negative
 value.

 @apiNote Callers should be aware of the possibility of other callers
 affecting the observation period and the result.