Summary

Add a method to java.lang.management.MemoryMXBean to return the accumulated CPU time in nanoseconds for GC related activity.

Problem

The HotSpot VM supports retrieval of GC CPU time since JDK 26 (JDK-8359110) and logs these values via -Xlog:cpu during VM shutdown. To support a refined understanding, during critical sections, of GC CPU time, sampling this at will is needed. There is no viable alternative to sample this from Java application code or JMX tooling today.

Solution

Add method to java.lang.management.MemoryMXBean.getTotalGcCpuTime() to return a long result with the accumulated CPU time in nanoseconds for GC related activity.

Alternative solutions have been explored, including adding to the standard and JDK-specific GarbageCollectorMXBean interfaces. These interfaces are ill-suited to this "property" as they don't model GC in the whole. Introducing a new JDK-specific management interface was also explored.

The proposal addition allows for VM implementations that do not support this feature.

Although added as a standard API, possibly usage may be in conjunction with the ProcessCpuTime property defined by the JDK-specific management interface com.sun.management.OperatingSystemMXBean.

A release note will be added.

Specification

    /**
     * Returns the approximate accumulated time, in nanoseconds,
     * spent in garbage collection (GC).
     *
     * <p> The time spent in spent in GC is the CPU time used by
     * all GC activity, including any overhead, which means the
     * result may be non-zero even if no GC has occurred.
     *
     * This method returns {@code -1} if the platform does
     * not support this operation or the information is not
     * available.
     *
     * @apiNote
     * May be used in conjunction with {@link jdk.management/com.sun.management.OperatingSystemMXBean#getProcessCpuTime()}
     * for calculating the GC's usage of CPU time as a whole.
     *
     * @implNote The specifics on what constitutes the time spent
     * in GC are highly implementation dependent. In the HotSpot
     * Virtual Machine, this time includes relevant
     * implementation-specific details such as driver threads,
     * workers, VM Operations and string deduplication (if
     * enabled). Driver threads may be created by a GC to
     * orchestrate its work. The return value can be -1 if called
     * when measurement is not possible, such as during shutdown.
     *
     * @implSpec The default implementation returns {@code -1}.
     *
     * @return the total accumulated CPU time for GC in
     * nanoseconds, or {@code -1}.
     *
     * @since 26
     */
    default long getTotalGcCpuTime() { .. }