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, -1 if unknown or 92 * -2 if the metric is not supported. 93 * 94 */ 95 public long getCpuUsage(); 96 97 /** 98 * Returns the aggregate time, in nanoseconds, consumed by all tasks in 99 * the Isolation Group, separated by CPU. If the current process 100 * is running within a container, the reported time will only be 101 * valid for processes running within the same container. The values 102 * are returned in an array, one entry for each physical processor 103 * on the system. Time values for processors unavailable to this 104 * Group are undefined. 105 * 106 * @return long array of time values. The size of the array is equal 107 * to the total number of physical processors in the system. If 108 * this metric is not supported or not available, null will be 109 * returned. 110 * 111 */ 112 public long[] getPerCpuUsage(); 113 114 /** 115 * Returns the aggregate user time, in nanoseconds, consumed by all 116 * tasks in the Isolation Group. 117 * 118 * @return User time in nanoseconds, -1 if the metric is not available or 119 * -2 if the metric is not supported. 120 * 121 */ 122 public long getCpuUserUsage(); 123 124 /** 125 * Returns the aggregate system time, in nanoseconds, consumed by 126 * all tasks in the Isolation Group. 127 * 128 * @return System time in nanoseconds, -1 if the metric is not available or 129 * -2 if the metric is not supported. 130 * 131 */ 132 public long getCpuSystemUsage(); 133 134 /***************************************************************** 135 * CPU Scheduling Metrics 136 ****************************************************************/ 137 138 /** 139 * Returns the length of the scheduling period, in 140 * microseconds, for processes within the Isolation Group. 141 * 142 * @return time in microseconds, -1 if the metric is not available or 143 * -2 if the metric is not supported. 144 * 145 */ 146 public long getCpuPeriod(); 147 148 /** 149 * Returns the total available run-time allowed, in microseconds, 150 * during each scheduling period for all tasks in the Isolation 151 * Group. 152 * 153 * @return time in microseconds, -1 if the quota is unlimited or 154 * -2 if not supported. 155 * 156 */ 157 public long getCpuQuota(); 158 159 160 /** 161 * Returns the relative weighting of processes with the Isolation 162 * Group used for prioritizing the scheduling of processes across 163 * all Isolation Groups running on a host. 164 * 165 * @implNote 166 * Popular container orchestration systems have standardized shares 167 * to be multiples of 1024, where 1024 is interpreted as 1 CPU share 168 * of execution. Users can distribute CPU resources to multiple 169 * Isolation Groups by specifying the CPU share weighting needed by 170 * each process. To request 2 CPUS worth of execution time, CPU shares 171 * would be set to 2048. 172 * 173 * @return shares value, -1 if the metric is not available or 174 * -2 if cpu shares are not supported. 175 * 176 */ 177 public long getCpuShares(); 178 179 /** 180 * Returns the number of time-slice periods that have elapsed if 181 * a CPU quota has been setup for the Isolation Group 182 * 183 * @return count of elapsed periods, -1 if the metric is not available 184 * or -2 if the metric is not supported. 185 * 186 */ 187 public long getCpuNumPeriods(); 188 189 /** 190 * Returns the number of time-slice periods that the group has 191 * been throttled or limited due to the group exceeding its quota 192 * if a CPU quota has been setup for the Isolation Group. 193 * 194 * @return count of throttled periods, -1 if the metric is not available or 195 * -2 if it is not supported. 196 * 197 */ 198 public long getCpuNumThrottled(); 199 200 /** 201 * Returns the total time duration, in nanoseconds, that the 202 * group has been throttled or limited due to the group exceeding 203 * its quota if a CPU quota has been setup for the Isolation Group. 204 * 205 * @return Throttled time in nanoseconds, -1 if the metric is not available 206 * or -2 if it is not supported. 207 * 208 */ 209 public long getCpuThrottledTime(); 210 211 212 /** 213 * Returns the number of effective processors that this Isolation 214 * group has available to it. This effective processor count is 215 * computed based on the number of dedicated CPUs, CPU shares and 216 * CPU quotas in effect for this isolation group. 217 * 218 * This method returns the same value as 219 * {@link java.lang.Runtime#availableProcessors()}. 220 * 221 * @return The number of effective CPUs. 222 * 223 */ 224 public long getEffectiveCpuCount(); 225 226 /***************************************************************** 227 * CPU Sets 228 ****************************************************************/ 229 230 /** 231 * Returns the CPUS that are available for execution of processes 232 * in the current Isolation Group. The size of the array is equal 233 * to the total number of CPUs and the elements in the array are the 234 * physical CPU numbers that are available. Some of the CPUs returned 235 * may be offline. To get the current online CPUs, use 236 * {@link getEffectiveCpuSetCpus()}. 237 * 238 * @return An array of available CPUs. Returns null if the metric is not 239 * available or the metric is not supported. 240 * 241 */ 242 public int[] getCpuSetCpus(); 243 244 /** 245 * Returns the CPUS that are available and online for execution of 246 * processes within the current Isolation Group. The size of the 247 * array is equal to the total number of CPUs and the elements in 248 * the array are the physical CPU numbers. 249 * 250 * @return An array of available and online CPUs. Returns null 251 * if the metric is not available or the metric is not supported. 252 * 253 */ 254 public int[] getEffectiveCpuSetCpus(); 255 256 /** 257 * Returns the memory nodes that are available for use by processes 258 * in the current Isolation Group. The size of the array is equal 259 * to the total number of nodes and the elements in the array are the 260 * physical node numbers that are available. Some of the nodes returned 261 * may be offline. To get the current online memory nodes, use 262 * {@link getEffectiveCpuSetMems()}. 263 * 264 * @return An array of available memory nodes or null 265 * if the metric is not available or is not supported. 266 * 267 */ 268 public int[] getCpuSetMems(); 269 270 /** 271 * Returns the memory nodes that are available and online for use by 272 * processes within the current Isolation Group. The size of the 273 * array is equal to the total number of nodes and the elements in 274 * the array are the physical node numbers. 275 * 276 * @return An array of available and online nodes or null 277 * if the metric is not available or is not supported. 278 * 279 */ 280 public int[] getEffectiveCpuSetMems(); 281 282 /***************************************************************** 283 * Memory Subsystem 284 ****************************************************************/ 285 286 /** 287 * Returns the number of times that user memory requests in the 288 * Isolation Group have exceeded the memory limit. 289 * 290 * @return The number of exceeded requests or -1 if the metric 291 * is not available. Returns -2 if the metric is not 292 * supported. 293 * 294 */ 295 public long getMemoryFailCount(); 296 297 /** 298 * Returns the maximum amount of physical memory, in bytes, that 299 * can be allocated in the Isolation Group. 300 * 301 * @return The maximum amount of memory in bytes or -1 if 302 * there is no limit or -2 if this metric is not supported. 303 * 304 */ 305 public long getMemoryLimit(); 306 307 /** 308 * Returns the amount of physical memory, in bytes, that is currently 309 * allocated in the current Isolation Group. 310 * 311 * @return The amount of memory in bytes allocated or -1 if 312 * the metric is not available or -2 if the metric is not 313 * supported. 314 * 315 */ 316 public long getMemoryUsage(); 317 318 /** 319 * Returns the amount of networking physical memory, in bytes, that 320 * is currently allocated in the current Isolation Group. 321 * 322 * @return The amount of memory in bytes allocated or -1 if the metric 323 * is not available. Returns -2 if this metric is not supported. 324 * 325 */ 326 public long getTcpMemoryUsage(); 327 328 /** 329 * Returns the maximum amount of physical memory and swap space, 330 * in bytes, that can be allocated in the Isolation Group. 331 * 332 * @return The maximum amount of memory in bytes or -1 if 333 * there is no limit set or -2 if this metric is not supported. 334 * 335 */ 336 public long getMemoryAndSwapLimit(); 337 338 /** 339 * Returns the amount of physical memory and swap space, in bytes, 340 * that is currently allocated in the current Isolation Group. 341 * 342 * @return The amount of memory in bytes allocated or -1 if 343 * the metric is not available. Returns -2 if this metric is not 344 * supported. 345 * 346 */ 347 public long getMemoryAndSwapUsage(); 348 349 /** 350 * Returns the hint to the operating system that allows groups 351 * to specify the minimum amount of physical memory that they need to 352 * achieve reasonable performance in low memory systems. This allows 353 * host systems to provide greater sharing of memory. 354 * 355 * @return The minimum amount of physical memory, in bytes, that the 356 * operating system will try to maintain under low memory 357 * conditions. If this metric is not available, -1 will be 358 * returned. Returns -2 if the metric is not supported. 359 * 360 */ 361 public long getMemorySoftLimit(); 362 363 /***************************************************************** 364 * BlKIO Subsystem 365 ****************************************************************/ 366 367 /** 368 * Returns the number of block I/O requests to the disk that have been 369 * issued by the Isolation Group. 370 * 371 * @return The count of requests or -1 if the metric is not available. 372 * Returns -2 if this metric is not supported. 373 * 374 */ 375 public long getBlkIOServiceCount(); 376 377 /** 378 * Returns the number of block I/O bytes that have been transferred 379 * to/from the disk by the Isolation Group. 380 * 381 * @return The number of bytes transferred or -1 if the metric is not 382 * available. Returns -2 if this metric is not supported. 383 * 384 */ 385 public long getBlkIOServiced(); 386 }