java/13 : java.base/jdk/internal/platform/Metrics.java

Metrics
https://openjdk.java.net/
GPLv2 + Classpath Exception
/*
 * Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package jdk.internal.platform;

import java.lang.reflect.Method;

Operating System Metrics class
Author: bobv
Implementation Note: Some of the APIs within this class return metrics for an
"Isolation Group" or "Container".  When the term "Isolation Group"
is used in the API description, this refers to either:

 All processes, including the current process within a container.
 All processes, including the current process running together
   isolated from other non-isolated processes.
 All processes running on a host when that there is no isolation
    in effect.
Since: 11/**
 * Operating System Metrics class
 *
 * @implNote Some of the APIs within this class return metrics for an
 * "Isolation Group" or "Container".  When the term "Isolation Group"
 * is used in the API description, this refers to either:
 *
 *<ol>
 *<li> All processes, including the current process within a container.
 *
 *<li> All processes, including the current process running together
 *    isolated from other non-isolated processes.
 *
 *<li> All processes running on a host when that there is no isolation
 *     in effect.
 *</ol>
 *
 * @author bobv
 * @since 11
 */

public interface Metrics {

    Returns an instance of the Metrics class.
Returns: Metrics object or null if not supported on this platform./**
     * Returns an instance of the Metrics class.
     *
     * @return Metrics object or null if not supported on this platform.
     */
    public static Metrics systemMetrics() {
        try {
            // We currently only support cgroupv1
            Class<?> c = Class.forName("jdk.internal.platform.cgroupv1.Metrics");
            @SuppressWarnings("unchecked")
            Method m = c.getMethod("getInstance");
            return (Metrics) m.invoke(null);
        } catch (ClassNotFoundException e) {
            return null;
        } catch (ReflectiveOperationException e) {
            throw new InternalError(e);
        }
    }

    Returns the interface responsible for providing the
platform metrics.
Implementation Note: 
Metrics are currently only supported Linux.
The provider for Linux is cgroupsv1.
Returns: The name of the provider./**
     * Returns the interface responsible for providing the
     * platform metrics.
     *
     * @implNote
     * Metrics are currently only supported Linux.
     * The provider for Linux is cgroupsv1.
     *
     * @return The name of the provider.
     *
     */
    public String getProvider();


    /*****************************************************************
     * CPU Accounting Subsystem
     ****************************************************************/

    Returns the aggregate time, in nanoseconds, consumed by all
tasks in the Isolation Group.
Returns: Time in nanoseconds or 0L if metric is not available./**
     * Returns the aggregate time, in nanoseconds, consumed by all
     * tasks in the Isolation Group.
     *
     * @return Time in nanoseconds or 0L if metric is not available.
     *
     */
    public long getCpuUsage();

    Returns the aggregate time, in nanoseconds, consumed by all tasks in
the Isolation Group, separated by CPU. If the current process
is running within a container, the reported time will only be
valid for processes running within the same container.  The values
are returned in an array, one entry for each physical processor
on the system.  Time values for processors unavailable to this
Group are undefined.
Returns: long array of time values.  The size of the array is equal
        to the total number of physical processors in the system. If
        this metric is not available, a zero length array will be
        returned./**
     * Returns the aggregate time, in nanoseconds, consumed by all tasks in
     * the Isolation Group, separated by CPU. If the current process
     * is running within a container, the reported time will only be
     * valid for processes running within the same container.  The values
     * are returned in an array, one entry for each physical processor
     * on the system.  Time values for processors unavailable to this
     * Group are undefined.
     *
     * @return long array of time values.  The size of the array is equal
     *         to the total number of physical processors in the system. If
     *         this metric is not available, a zero length array will be
     *         returned.
     *
     */
    public long[] getPerCpuUsage();

    Returns the aggregate user time, in nanoseconds, consumed by all
tasks in the Isolation Group.
Returns: User time in nanoseconds or 0L if metric is not available./**
     * Returns the aggregate user time, in nanoseconds, consumed by all
     * tasks in the Isolation Group.
     *
     * @return User time in nanoseconds or 0L if metric is not available.
     *
     */
    public long getCpuUserUsage();

    Returns the aggregate system time, in nanoseconds, consumed by
all tasks in the Isolation Group.
Returns: System time in nanoseconds or 0L if metric is not available./**
     * Returns the aggregate system time, in nanoseconds, consumed by
     * all tasks in the Isolation Group.
     *
     * @return System time in nanoseconds or 0L if metric is not available.
     *
     */
    public long getCpuSystemUsage();

    /*****************************************************************
     * CPU Scheduling Metrics
     ****************************************************************/

    Returns the length of the scheduling period, in
microseconds, for processes within the Isolation Group.
Returns: time in microseconds or 0L if metric is not available./**
     * Returns the length of the scheduling period, in
     * microseconds, for processes within the Isolation Group.
     *
     * @return time in microseconds or 0L if metric is not available.
     *
     */
    public long getCpuPeriod();

    Returns the total available run-time allowed, in microseconds,
during each scheduling period for all tasks in the Isolation
Group.
Returns: time in microseconds or -1 if the quota is unlimited./**
     * Returns the total available run-time allowed, in microseconds,
     * during each scheduling period for all tasks in the Isolation
     * Group.
     *
     * @return time in microseconds or -1 if the quota is unlimited.
     *
     */
    public long getCpuQuota();


    Returns the relative weighting of processes with the Isolation
Group used for prioritizing the scheduling of processes across
all Isolation Groups running on a host.
Implementation Note: 
Popular container orchestration systems have standardized shares
to be multiples of 1024, where 1024 is interpreted as 1 CPU share
of execution.  Users can distribute CPU resources to multiple
Isolation Groups by specifying the CPU share weighting needed by
each process.  To request 2 CPUS worth of execution time, CPU shares
would be set to 2048.
Returns: shares value or -1 if no share set./**
     * Returns the relative weighting of processes with the Isolation
     * Group used for prioritizing the scheduling of processes across
     * all Isolation Groups running on a host.
     *
     * @implNote
     * Popular container orchestration systems have standardized shares
     * to be multiples of 1024, where 1024 is interpreted as 1 CPU share
     * of execution.  Users can distribute CPU resources to multiple
     * Isolation Groups by specifying the CPU share weighting needed by
     * each process.  To request 2 CPUS worth of execution time, CPU shares
     * would be set to 2048.
     *
     * @return shares value or -1 if no share set.
     *
     */
    public long getCpuShares();

    Returns the number of time-slice periods that have elapsed if
a CPU quota has been setup for the Isolation Group; otherwise
returns 0.
Returns: count of elapsed periods or 0 if the quota is unlimited./**
     * Returns the number of time-slice periods that have elapsed if
     * a CPU quota has been setup for the Isolation Group; otherwise
     * returns 0.
     *
     * @return count of elapsed periods or 0 if the quota is unlimited.
     *
     */
    public long getCpuNumPeriods();

    Returns the number of time-slice periods that the group has
been throttled or limited due to the group exceeding its quota
if a CPU quota has been setup for the Isolation Group.
Returns: count of throttled periods or 0 if the quota is unlimited./**
     * Returns the number of time-slice periods that the group has
     * been throttled or limited due to the group exceeding its quota
     * if a CPU quota has been setup for the Isolation Group.
     *
     * @return count of throttled periods or 0 if the quota is unlimited.
     *
     */
    public long getCpuNumThrottled();

    Returns the total time duration, in nanoseconds, that the
group has been throttled or limited due to the group exceeding
its quota if a CPU quota has been setup for the Isolation Group.
Returns: Throttled time in nanoseconds or 0 if the quota is unlimited./**
     * Returns the total time duration, in nanoseconds, that the
     * group has been throttled or limited due to the group exceeding
     * its quota if a CPU quota has been setup for the Isolation Group.
     *
     * @return Throttled time in nanoseconds or 0 if the quota is unlimited.
     *
     */
    public long getCpuThrottledTime();


    Returns the number of effective processors that this Isolation group has available to it. This effective processor count is computed based on the number of dedicated CPUs, CPU shares and CPU quotas in effect for this isolation group. This method returns the same value as Runtime.availableProcessors(). 
Returns: The number of effective CPUs./**
     * Returns the number of effective processors that this Isolation
     * group has available to it.  This effective processor count is
     * computed based on the number of dedicated CPUs, CPU shares and
     * CPU quotas in effect for this isolation group.
     *
     * This method returns the same value as
     * {@link java.lang.Runtime#availableProcessors()}.
     *
     * @return The number of effective CPUs.
     *
     */
    public long getEffectiveCpuCount();

    /*****************************************************************
     * CPU Sets
     ****************************************************************/

    Returns the CPUS that are available for execution of processes in the current Isolation Group. The size of the array is equal to the total number of CPUs and the elements in the array are the physical CPU numbers that are available. Some of the CPUs returned may be offline. To get the current online CPUs, use getEffectiveCpuSetCpus(). 
Returns: An array of available CPUs or a zero length array
        if the metric is not available./**
     * Returns the CPUS that are available for execution of processes
     * in the current Isolation Group. The size of the array is equal
     * to the total number of CPUs and the elements in the array are the
     * physical CPU numbers that are available.  Some of the CPUs returned
     * may be offline.  To get the current online CPUs, use
     * {@link getEffectiveCpuSetCpus()}.
     *
     * @return An array of available CPUs or a zero length array
     *         if the metric is not available.
     *
     */
    public int[] getCpuSetCpus();

    Returns the CPUS that are available and online for execution of
processes within the current Isolation Group. The size of the
array is equal to the total number of CPUs and the elements in
the array are the physical CPU numbers.
Returns: An array of available and online CPUs or a zero length
        array if the metric is not available./**
     * Returns the CPUS that are available and online for execution of
     * processes within the current Isolation Group. The size of the
     * array is equal to the total number of CPUs and the elements in
     * the array are the physical CPU numbers.
     *
     * @return An array of available and online CPUs or a zero length
     *         array if the metric is not available.
     *
     */
    public int[] getEffectiveCpuSetCpus();

    Returns the memory nodes that are available for use by processes in the current Isolation Group. The size of the array is equal to the total number of nodes and the elements in the array are the physical node numbers that are available. Some of the nodes returned may be offline. To get the current online memory nodes, use getEffectiveCpuSetMems(). 
Returns: An array of available memory nodes or a zero length array
        if the metric is not available./**
     * Returns the memory nodes that are available for use by processes
     * in the current Isolation Group. The size of the array is equal
     * to the total number of nodes and the elements in the array are the
     * physical node numbers that are available.  Some of the nodes returned
     * may be offline.  To get the current online memory nodes, use
     * {@link getEffectiveCpuSetMems()}.
     *
     * @return An array of available memory nodes or a zero length array
     *         if the metric is not available.
     *
     */
    public int[] getCpuSetMems();

    Returns the memory nodes that are available and online for use by
processes within the current Isolation Group. The size of the
array is equal to the total number of nodes and the elements in
the array are the physical node numbers.
Returns: An array of available and online nodes or a zero length
        array if the metric is not available./**
     * Returns the memory nodes that are available and online for use by
     * processes within the current Isolation Group. The size of the
     * array is equal to the total number of nodes and the elements in
     * the array are the physical node numbers.
     *
     * @return An array of available and online nodes or a zero length
     *         array if the metric is not available.
     *
     */
    public int[] getEffectiveCpuSetMems();

    Returns the (attempts per second * 1000), if enabled, that the operating system tries to satisfy a memory request for any process in the current Isolation Group when no free memory is readily available. Use isCpuSetMemoryPressureEnabled() to determine if this support is enabled. 
Returns: Memory pressure or 0 if not enabled or metric is not
        available./**
     * Returns the (attempts per second * 1000), if enabled, that the
     * operating system tries to satisfy a memory request for any
     * process in the current Isolation Group when no free memory is
     * readily available.  Use {@link #isCpuSetMemoryPressureEnabled()} to
     * determine if this support is enabled.
     *
     * @return Memory pressure or 0 if not enabled or metric is not
     *         available.
     *
     */
    public double getCpuSetMemoryPressure();

    Returns the state of the memory pressure detection support.
Returns: true if the support is available and enabled, otherwise false./**
     * Returns the state of the memory pressure detection support.
     *
     * @return true if the support is available and enabled, otherwise false.
     *
     */
    public boolean isCpuSetMemoryPressureEnabled();

    /*****************************************************************
     * Memory Subsystem
     ****************************************************************/

    Returns the number of times that user memory requests in the
Isolation Group have exceeded the memory limit.
Returns: The number of exceeded requests or 0 if none or metric
        is not available./**
     * Returns the number of times that user memory requests in the
     * Isolation Group have exceeded the memory limit.
     *
     * @return The number of exceeded requests or 0 if none or metric
     *         is not available.
     *
     */
    public long getMemoryFailCount();

    Returns the maximum amount of physical memory, in bytes, that
can be allocated in the Isolation Group.
Returns: The maximum amount of memory in bytes or -1 if either
        there is no limit set or this metric is not available./**
     * Returns the maximum amount of physical memory, in bytes, that
     * can be allocated in the Isolation Group.
     *
     * @return The maximum amount of memory in bytes or -1 if either
     *         there is no limit set or this metric is not available.
     *
     */
    public long getMemoryLimit();

    Returns the largest amount of physical memory, in bytes, that
have been allocated in the Isolation Group.
Returns: The largest amount of memory in bytes or 0 if this
        metric is not available./**
     * Returns the largest amount of physical memory, in bytes, that
     * have been allocated in the Isolation Group.
     *
     * @return The largest amount of memory in bytes or 0 if this
     *         metric is not available.
     *
     */
    public long getMemoryMaxUsage();

    Returns the amount of physical memory, in bytes, that is currently
allocated in the current Isolation Group.
Returns: The amount of memory in bytes allocated or 0 if this
        metric is not available./**
     * Returns the amount of physical memory, in bytes, that is currently
     * allocated in the current Isolation Group.
     *
     * @return The amount of memory in bytes allocated or 0 if this
     *         metric is not available.
     *
     */
    public long getMemoryUsage();

    Returns the number of times that kernel memory requests in the
Isolation Group have exceeded the kernel memory limit.
Returns: The number of exceeded requests or 0 if none or metric
        is not available./**
     * Returns the number of times that kernel memory requests in the
     * Isolation Group have exceeded the kernel memory limit.
     *
     * @return The number of exceeded requests or 0 if none or metric
     *         is not available.
     *
     */
    public long getKernelMemoryFailCount();

    Returns the maximum amount of kernel physical memory, in bytes, that
can be allocated in the Isolation Group.
Returns: The maximum amount of memory in bytes or -1 if either
        there is no limit set or this metric is not available./**
     * Returns the maximum amount of kernel physical memory, in bytes, that
     * can be allocated in the Isolation Group.
     *
     * @return The maximum amount of memory in bytes or -1 if either
     *         there is no limit set or this metric is not available.
     *
     */
    public long getKernelMemoryLimit();

    Returns the largest amount of kernel physical memory, in bytes, that
have been allocated in the Isolation Group.
Returns: The largest amount of memory in bytes or 0 if this
        metric is not available./**
     * Returns the largest amount of kernel physical memory, in bytes, that
     * have been allocated in the Isolation Group.
     *
     * @return The largest amount of memory in bytes or 0 if this
     *         metric is not available.
     *
     */
    public long getKernelMemoryMaxUsage();

    Returns the amount of kernel physical memory, in bytes, that
is currently allocated in the current Isolation Group.
Returns: The amount of memory in bytes allocated or 0 if this
        metric is not available./**
     * Returns the amount of kernel physical memory, in bytes, that
     * is currently allocated in the current Isolation Group.
     *
     * @return The amount of memory in bytes allocated or 0 if this
     *         metric is not available.
     *
     */
    public long getKernelMemoryUsage();

    Returns the number of times that networking memory requests in the
Isolation Group have exceeded the kernel memory limit.
Returns: The number of exceeded requests or 0 if none or metric
        is not available./**
     * Returns the number of times that networking memory requests in the
     * Isolation Group have exceeded the kernel memory limit.
     *
     * @return The number of exceeded requests or 0 if none or metric
     *         is not available.
     *
     */
    public long getTcpMemoryFailCount();

    Returns the maximum amount of networking physical memory, in bytes,
that can be allocated in the Isolation Group.
Returns: The maximum amount of memory in bytes or -1 if either
        there is no limit set or this metric is not available./**
     * Returns the maximum amount of networking physical memory, in bytes,
     * that can be allocated in the Isolation Group.
     *
     * @return The maximum amount of memory in bytes or -1 if either
     *         there is no limit set or this metric is not available.
     *
     */
    public long getTcpMemoryLimit();

    Returns the largest amount of networking physical memory, in bytes,
that have been allocated in the Isolation Group.
Returns: The largest amount of memory in bytes or 0 if this
        metric is not available./**
     * Returns the largest amount of networking physical memory, in bytes,
     * that have been allocated in the Isolation Group.
     *
     * @return The largest amount of memory in bytes or 0 if this
     *         metric is not available.
     *
     */
    public long getTcpMemoryMaxUsage();

    Returns the amount of networking physical memory, in bytes, that
is currently allocated in the current Isolation Group.
Returns: The amount of memory in bytes allocated or 0 if this
        metric is not available./**
     * Returns the amount of networking physical memory, in bytes, that
     * is currently allocated in the current Isolation Group.
     *
     * @return The amount of memory in bytes allocated or 0 if this
     *         metric is not available.
     *
     */
    public long getTcpMemoryUsage();

    Returns the number of times that user memory requests in the
Isolation Group have exceeded the memory + swap limit.
Returns: The number of exceeded requests or 0 if none or metric
        is not available./**
     * Returns the number of times that user memory requests in the
     * Isolation Group have exceeded the memory + swap limit.
     *
     * @return The number of exceeded requests or 0 if none or metric
     *         is not available.
     *
     */
    public long getMemoryAndSwapFailCount();

    Returns the maximum amount of physical memory and swap space,
in bytes, that can be allocated in the Isolation Group.
Returns: The maximum amount of memory in bytes or -1 if either
        there is no limit set or this metric is not available./**
     * Returns the maximum amount of physical memory and swap space,
     * in bytes, that can be allocated in the Isolation Group.
     *
     * @return The maximum amount of memory in bytes or -1 if either
     *         there is no limit set or this metric is not available.
     *
     */
    public long getMemoryAndSwapLimit();

    Returns the largest amount of physical memory and swap space,
in bytes, that have been allocated in the Isolation Group.
Returns: The largest amount of memory in bytes or 0 if this
        metric is not available./**
     * Returns the largest amount of physical memory and swap space,
     * in bytes, that have been allocated in the Isolation Group.
     *
     * @return The largest amount of memory in bytes or 0 if this
     *         metric is not available.
     *
     */
    public long getMemoryAndSwapMaxUsage();

    Returns the amount of physical memory and swap space, in bytes,
that is currently allocated in the current Isolation Group.
Returns: The amount of memory in bytes allocated or 0 if this
        metric is not available./**
     * Returns the amount of physical memory and swap space, in bytes,
     * that is currently allocated in the current Isolation Group.
     *
     * @return The amount of memory in bytes allocated or 0 if this
     *         metric is not available.
     *
     */
    public long getMemoryAndSwapUsage();

    Returns the state of the Operating System Out of Memory termination
policy.
Returns: Returns true if operating system will terminate processes
        in the Isolation Group that exceed the amount of available
        memory, otherwise false.  Flase will be returned if this
        capability is not available on the current operating system./**
     * Returns the state of the Operating System Out of Memory termination
     * policy.
     *
     * @return Returns true if operating system will terminate processes
     *         in the Isolation Group that exceed the amount of available
     *         memory, otherwise false.  Flase will be returned if this
     *         capability is not available on the current operating system.
     *
     */
    public boolean isMemoryOOMKillEnabled();

    Returns the hint to the operating system that allows groups
to specify the minimum amount of physical memory that they need to
achieve reasonable performance in low memory systems.  This allows
host systems to provide greater sharing of memory.
Returns: The minimum amount of physical memory, in bytes, that the
        operating system will try to maintain under low memory
        conditions.  If this metric is not available, 0 will be
        returned./**
     * Returns the hint to the operating system that allows groups
     * to specify the minimum amount of physical memory that they need to
     * achieve reasonable performance in low memory systems.  This allows
     * host systems to provide greater sharing of memory.
     *
     * @return The minimum amount of physical memory, in bytes, that the
     *         operating system will try to maintain under low memory
     *         conditions.  If this metric is not available, 0 will be
     *         returned.
     *
     */
    public long getMemorySoftLimit();

    /*****************************************************************
     * BlKIO Subsystem
     ****************************************************************/

    Returns the number of block I/O requests to the disk that have been
issued by the Isolation Group.
Returns: The count of requests or 0 if this metric is not available./**
     * Returns the number of block I/O requests to the disk that have been
     * issued by the Isolation Group.
     *
     * @return The count of requests or 0 if this metric is not available.
     *
     */
    public long getBlkIOServiceCount();

    Returns the number of block I/O bytes that have been transferred
to/from the disk by the Isolation Group.
Returns: The number of bytes transferred or 0 if this metric is not available./**
     * Returns the number of block I/O bytes that have been transferred
     * to/from the disk by the Isolation Group.
     *
     * @return The number of bytes transferred or 0 if this metric is not available.
     *
     */
    public long getBlkIOServiced();
}
Author:	bobv
Implementation Note:	Some of the APIs within this class return metrics for an "Isolation Group" or "Container". When the term "Isolation Group" is used in the API description, this refers to either: All processes, including the current process within a container. All processes, including the current process running together isolated from other non-isolated processes. All processes running on a host when that there is no isolation in effect.
Since:	11
Implementation Note:	Metrics are currently only supported Linux. The provider for Linux is cgroupsv1.
Returns:	The name of the provider.
Implementation Note:	Popular container orchestration systems have standardized shares to be multiples of 1024, where 1024 is interpreted as 1 CPU share of execution. Users can distribute CPU resources to multiple Isolation Groups by specifying the CPU share weighting needed by each process. To request 2 CPUS worth of execution time, CPU shares would be set to 2048.
Returns:	shares value or -1 if no share set.
/

java/ 13/ java.base/jdk/internal/platform/Metrics.java
