Metrics.java

/*
 * Copyright (c) 2018, 2021, 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
 *
 * @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.
     *
     * @return Metrics object or null if not supported on this platform.
     */
    public static Metrics systemMetrics() {
        return SystemMetrics.instance();
    }

    /**
     * Returns the interface responsible for providing the
     * platform metrics.
     *
     * @implNote
     * Metrics are currently only supported Linux.
     * The provider for Linux is cgroups (version 1 or 2).
     *
     * @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.
     *
     * @return Time in nanoseconds, -1 if unknown or
     *         -2 if the metric is not supported.
     *
     */
    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.
     *
     * @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 supported or not available, null will be
     *         returned.
     *
     */
    public long[] getPerCpuUsage();

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

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

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

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

    /**
     * Returns the total available run-time allowed, in microseconds,
     * during each scheduling period for all tasks in the Isolation
     * Group.
     *
     * @return time in microseconds, -1 if the quota is unlimited or
     *         -2 if not supported.
     *
     */
    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.
     *
     * @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, -1 if the metric is not available or
     *         -2 if cpu shares are not supported.
     *
     */
    public long getCpuShares();

    /**
     * Returns the number of time-slice periods that have elapsed if
     * a CPU quota has been setup for the Isolation Group
     *
     * @return count of elapsed periods, -1 if the metric is not available
     *         or -2 if the metric is not supported.
     *
     */
    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.
     *
     * @return count of throttled periods, -1 if the metric is not available or
     *         -2 if it is not supported.
     *
     */
    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.
     *
     * @return Throttled time in nanoseconds, -1 if the metric is not available
     *         or -2 if it is not supported.
     *
     */
    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
     * {@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
     * {@link getEffectiveCpuSetCpus()}.
     *
     * @return An array of available CPUs. Returns null if the metric is not
     *         available or the metric is not supported.
     *
     */
    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.
     *
     * @return An array of available and online CPUs. Returns null
     *         if the metric is not available or the metric is not supported.
     *
     */
    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
     * {@link getEffectiveCpuSetMems()}.
     *
     * @return An array of available memory nodes or null
     *         if the metric is not available or is not supported.
     *
     */
    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.
     *
     * @return An array of available and online nodes or null
     *         if the metric is not available or is not supported.
     *
     */
    public int[] getEffectiveCpuSetMems();

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

    /**
     * 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 -1 if the metric
     *         is not available. Returns -2 if the metric is not
     *         supported.
     *
     */
    public long getMemoryFailCount();

    /**
     * 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
     *         there is no limit or -2 if this metric is not supported.
     *
     */
    public long getMemoryLimit();

    /**
     * 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 -1 if
     *         the metric is not available or -2 if the metric is not
     *         supported.
     *
     */
    public long getMemoryUsage();

    /**
     * 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 -1 if the metric
     *         is not available. Returns -2 if this metric is not supported.
     *
     */
    public long getTcpMemoryUsage();

    /**
     * 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
     *         there is no limit set or -2 if this metric is not supported.
     *
     */
    public long getMemoryAndSwapLimit();

    /**
     * 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 -1 if
     *         the metric is not available. Returns -2 if this metric is not
     *         supported.
     *
     */
    public long getMemoryAndSwapUsage();

    /**
     * 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, -1 will be
     *         returned. Returns -2 if the metric is not supported.
     *
     */
    public long getMemorySoftLimit();

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

    /**
     * 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 -1 if the metric is not available.
     *         Returns -2 if this metric is not supported.
     *
     */
    public long getBlkIOServiceCount();

    /**
     * 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 -1 if the metric is not
     *         available. Returns -2 if this metric is not supported.
     *
     */
    public long getBlkIOServiced();
}