1 /* 2 * Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package jdk.internal.platform; 26 27 import java.lang.reflect.Method; 28 29 /** 30 * Operating System Metrics class 31 * 32 * @implNote Some of the APIs within this class return metrics for an 33 * "Isolation Group" or "Container". When the term "Isolation Group" 34 * is used in the API description, this refers to either: 35 * 36 *<ol> 37 *<li> All processes, including the current process within a container. 38 * 39 *<li> All processes, including the current process running together 40 * isolated from other non-isolated processes. 41 * 42 *<li> All processes running on a host when that there is no isolation 43 * in effect. 44 *</ol> 45 * 46 * @author bobv 47 * @since 11 48 */ 49 50 public interface Metrics { 51 52 /** 53 * Returns an instance of the Metrics class. 54 * 55 * @return Metrics object or null if not supported on this platform. 56 */ 57 public static Metrics systemMetrics() { 58 try { 59 Class<?> c = Class.forName("jdk.internal.platform.CgroupMetrics"); 60 Method m = c.getMethod("getInstance"); 61 return (Metrics) m.invoke(null); 62 } catch (ClassNotFoundException e) { 63 return null; 64 } catch (ReflectiveOperationException e) { 65 throw new InternalError(e); 66 } 67 } 68 69 /** 70 * Returns the interface responsible for providing the 71 * platform metrics. 72 * 73 * @implNote 74 * Metrics are currently only supported Linux. 75 * The provider for Linux is cgroups (version 1 or 2). 76 * 77 * @return The name of the provider. 78 * 79 */ 80 public String getProvider(); 81 82 83 /***************************************************************** 84 * CPU Accounting Subsystem 85 ****************************************************************/ 86 87 /** 88 * Returns the aggregate time, in nanoseconds, consumed by all 89 * tasks in the Isolation Group. 90 * 91 * @return Time in nanoseconds or -2 if metric is not available. 92 * 93 */ 94 public long getCpuUsage(); 95 96 /** 97 * Returns the aggregate time, in nanoseconds, consumed by all tasks in 98 * the Isolation Group, separated by CPU. If the current process 99 * is running within a container, the reported time will only be 100 * valid for processes running within the same container. The values 101 * are returned in an array, one entry for each physical processor 102 * on the system. Time values for processors unavailable to this 103 * Group are undefined. 104 * 105 * @return long array of time values. The size of the array is equal 106 * to the total number of physical processors in the system. If 107 * this metric is not available, null will be 108 * returned. 109 * 110 */ 111 public long[] getPerCpuUsage(); 112 113 /** 114 * Returns the aggregate user time, in nanoseconds, consumed by all 115 * tasks in the Isolation Group. 116 * 117 * @return User time in nanoseconds or -2 if metric is not available. 118 * 119 */ 120 public long getCpuUserUsage(); 121 122 /** 123 * Returns the aggregate system time, in nanoseconds, consumed by 124 * all tasks in the Isolation Group. 125 * 126 * @return System time in nanoseconds or -2 if metric is not available. 127 * 128 */ 129 public long getCpuSystemUsage(); 130 131 /***************************************************************** 132 * CPU Scheduling Metrics 133 ****************************************************************/ 134 135 /** 136 * Returns the length of the scheduling period, in 137 * microseconds, for processes within the Isolation Group. 138 * 139 * @return time in microseconds or -2 if metric is not available. 140 * 141 */ 142 public long getCpuPeriod(); 143 144 /** 145 * Returns the total available run-time allowed, in microseconds, 146 * during each scheduling period for all tasks in the Isolation 147 * Group. 148 * 149 * @return time in microseconds or -2 if not supported. 150 * 151 */ 152 public long getCpuQuota(); 153 154 155 /** 156 * Returns the relative weighting of processes with the Isolation 157 * Group used for prioritizing the scheduling of processes across 158 * all Isolation Groups running on a host. 159 * 160 * @implNote 161 * Popular container orchestration systems have standardized shares 162 * to be multiples of 1024, where 1024 is interpreted as 1 CPU share 163 * of execution. Users can distribute CPU resources to multiple 164 * Isolation Groups by specifying the CPU share weighting needed by 165 * each process. To request 2 CPUS worth of execution time, CPU shares 166 * would be set to 2048. 167 * 168 * @return shares value or -2 if no share set. 169 * 170 */ 171 public long getCpuShares(); 172 173 /** 174 * Returns the number of time-slice periods that have elapsed if 175 * a CPU quota has been setup for the Isolation Group; otherwise 176 * returns 0. 177 * 178 * @return count of elapsed periods or -2 if not supported. 179 * 180 */ 181 public long getCpuNumPeriods(); 182 183 /** 184 * Returns the number of time-slice periods that the group has 185 * been throttled or limited due to the group exceeding its quota 186 * if a CPU quota has been setup for the Isolation Group. 187 * 188 * @return count of throttled periods or -2 if not supported. 189 * 190 */ 191 public long getCpuNumThrottled(); 192 193 /** 194 * Returns the total time duration, in nanoseconds, that the 195 * group has been throttled or limited due to the group exceeding 196 * its quota if a CPU quota has been setup for the Isolation Group. 197 * 198 * @return Throttled time in nanoseconds or -2 if not supported. 199 * 200 */ 201 public long getCpuThrottledTime(); 202 203 204 /** 205 * Returns the number of effective processors that this Isolation 206 * group has available to it. This effective processor count is 207 * computed based on the number of dedicated CPUs, CPU shares and 208 * CPU quotas in effect for this isolation group. 209 * 210 * This method returns the same value as 211 * {@link java.lang.Runtime#availableProcessors()}. 212 * 213 * @return The number of effective CPUs. 214 * 215 */ 216 public long getEffectiveCpuCount(); 217 218 /***************************************************************** 219 * CPU Sets 220 ****************************************************************/ 221 222 /** 223 * Returns the CPUS that are available for execution of processes 224 * in the current Isolation Group. The size of the array is equal 225 * to the total number of CPUs and the elements in the array are the 226 * physical CPU numbers that are available. Some of the CPUs returned 227 * may be offline. To get the current online CPUs, use 228 * {@link getEffectiveCpuSetCpus()}. 229 * 230 * @return An array of available CPUs or null 231 * if the metric is not available. 232 * 233 */ 234 public int[] getCpuSetCpus(); 235 236 /** 237 * Returns the CPUS that are available and online for execution of 238 * processes within the current Isolation Group. The size of the 239 * array is equal to the total number of CPUs and the elements in 240 * the array are the physical CPU numbers. 241 * 242 * @return An array of available and online CPUs or null 243 * if the metric is not available. 244 * 245 */ 246 public int[] getEffectiveCpuSetCpus(); 247 248 /** 249 * Returns the memory nodes that are available for use by processes 250 * in the current Isolation Group. The size of the array is equal 251 * to the total number of nodes and the elements in the array are the 252 * physical node numbers that are available. Some of the nodes returned 253 * may be offline. To get the current online memory nodes, use 254 * {@link getEffectiveCpuSetMems()}. 255 * 256 * @return An array of available memory nodes or null 257 * if the metric is not available. 258 * 259 */ 260 public int[] getCpuSetMems(); 261 262 /** 263 * Returns the memory nodes that are available and online for use by 264 * processes within the current Isolation Group. The size of the 265 * array is equal to the total number of nodes and the elements in 266 * the array are the physical node numbers. 267 * 268 * @return An array of available and online nodes or null 269 * if the metric is not available. 270 * 271 */ 272 public int[] getEffectiveCpuSetMems(); 273 274 /***************************************************************** 275 * Memory Subsystem 276 ****************************************************************/ 277 278 /** 279 * Returns the number of times that user memory requests in the 280 * Isolation Group have exceeded the memory limit. 281 * 282 * @return The number of exceeded requests or -2 if metric 283 * is not available. 284 * 285 */ 286 public long getMemoryFailCount(); 287 288 /** 289 * Returns the maximum amount of physical memory, in bytes, that 290 * can be allocated in the Isolation Group. 291 * 292 * @return The maximum amount of memory in bytes or -1 if 293 * there is no limit or -2 if this metric is not available. 294 * 295 */ 296 public long getMemoryLimit(); 297 298 /** 299 * Returns the amount of physical memory, in bytes, that is currently 300 * allocated in the current Isolation Group. 301 * 302 * @return The amount of memory in bytes allocated or -2 if this 303 * metric is not available. 304 * 305 */ 306 public long getMemoryUsage(); 307 308 /** 309 * Returns the amount of networking physical memory, in bytes, that 310 * is currently allocated in the current Isolation Group. 311 * 312 * @return The amount of memory in bytes allocated or -2 if this 313 * metric is not available. 314 * 315 */ 316 public long getTcpMemoryUsage(); 317 318 /** 319 * Returns the maximum amount of physical memory and swap space, 320 * in bytes, that can be allocated in the Isolation Group. 321 * 322 * @return The maximum amount of memory in bytes or -1 if 323 * there is no limit set or -2 if this metric is not available. 324 * 325 */ 326 public long getMemoryAndSwapLimit(); 327 328 /** 329 * Returns the amount of physical memory and swap space, in bytes, 330 * that is currently allocated in the current Isolation Group. 331 * 332 * @return The amount of memory in bytes allocated or -2 if this 333 * metric is not available. 334 * 335 */ 336 public long getMemoryAndSwapUsage(); 337 338 /** 339 * Returns the hint to the operating system that allows groups 340 * to specify the minimum amount of physical memory that they need to 341 * achieve reasonable performance in low memory systems. This allows 342 * host systems to provide greater sharing of memory. 343 * 344 * @return The minimum amount of physical memory, in bytes, that the 345 * operating system will try to maintain under low memory 346 * conditions. If this metric is not available, -2 will be 347 * returned. 348 * 349 */ 350 public long getMemorySoftLimit(); 351 352 /***************************************************************** 353 * BlKIO Subsystem 354 ****************************************************************/ 355 356 /** 357 * Returns the number of block I/O requests to the disk that have been 358 * issued by the Isolation Group. 359 * 360 * @return The count of requests or -2 if this metric is not available. 361 * 362 */ 363 public long getBlkIOServiceCount(); 364 365 /** 366 * Returns the number of block I/O bytes that have been transferred 367 * to/from the disk by the Isolation Group. 368 * 369 * @return The number of bytes transferred or -2 if this metric is not available. 370 * 371 */ 372 public long getBlkIOServiced(); 373 }