/* * 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. */ 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: * *
    *
  1. All processes, including the current process within a container. * *
  2. All processes, including the current process running together * isolated from other non-isolated processes. * *
  3. All processes running on a host when that there is no isolation * in effect. *
* * @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() { try { Class c = Class.forName("jdk.internal.platform.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. * * @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(); }