graal/21.0.0.2 : substratevm/com.oracle.svm.core/com/oracle/svm/core/containers/Metrics.java

/*
 * Copyright (c) 2018, 2020, 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.
 */
// @formatter:off
package com.oracle.svm.core.containers;

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 {
            Class<?> c = Class.forName("com.oracle.svm.core.containers.CgroupMetrics");
            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 cgroups (version 1 or 2).
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 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.
Returns: Time in nanoseconds, -1 if unknown or
        -2 if the metric is not supported./**
     * 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.
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 supported or not available, null 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 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.
Returns: User time in nanoseconds, -1 if the metric is not available or
        -2 if the metric is not supported./**
     * 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.
Returns: System time in nanoseconds, -1 if the metric is not available or
        -2 if the metric is not supported./**
     * 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.
Returns: time in microseconds, -1 if the metric is not available or
        -2 if the metric is not supported./**
     * 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.
Returns: time in microseconds, -1 if the quota is unlimited or
        -2 if not supported./**
     * 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.
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, -1 if the metric is not available or
        -2 if cpu shares are not supported./**
     * 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
Returns: count of elapsed periods, -1 if the metric is not available
        or -2 if the metric is not supported./**
     * 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.
Returns: count of throttled periods, -1 if the metric is not available or
        -2 if it is not supported./**
     * 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.
Returns: Throttled time in nanoseconds, -1 if the metric is not available
        or -2 if it is not supported./**
     * 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 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. Returns null if the metric is not
        available or the metric is not supported./**
     * 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.
Returns: An array of available and online CPUs. Returns null
        if the metric is not available or the metric is not supported./**
     * 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 getEffectiveCpuSetMems(). 
Returns: An array of available memory nodes or null
        if the metric is not available or is not supported./**
     * 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.
Returns: An array of available and online nodes or null
        if the metric is not available or is not supported./**
     * 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.
Returns: The number of exceeded requests or -1 if the metric
        is not available. Returns -2 if the metric is not
        supported./**
     * 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.
Returns: The maximum amount of memory in bytes or -1 if
        there is no limit or -2 if this metric is not supported./**
     * 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.
Returns: The amount of memory in bytes allocated or -1 if
        the metric is not available or -2 if the metric is not
        supported./**
     * 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.
Returns: The amount of memory in bytes allocated or -1 if the metric
        is not available. Returns -2 if this metric is not supported./**
     * 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.
Returns: The maximum amount of memory in bytes or -1 if
        there is no limit set or -2 if this metric is not supported./**
     * 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.
Returns: The amount of memory in bytes allocated or -1 if
        the metric is not available. Returns -2 if this metric is not
        supported./**
     * 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.
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, -1 will be
        returned. Returns -2 if the metric is not supported./**
     * 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.
Returns: The count of requests or -1 if the metric is not available.
        Returns -2 if this metric is not supported./**
     * 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.
Returns: The number of bytes transferred or -1 if the metric is not
        available. Returns -2 if this metric is not supported./**
     * 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();
}
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 cgroups (version 1 or 2).
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, -1 if the metric is not available or -2 if cpu shares are not supported.
/

graal/ 21.0.0.2/ substratevm/com.oracle.svm.core/com/oracle/svm/core/containers/Metrics.java
