1 /* 2 * Copyright (c) 2018, 2019, 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 // We currently only support cgroupv1 60 Class<?> c = Class.forName("jdk.internal.platform.cgroupv1.Metrics"); 61 @SuppressWarnings("unchecked") 62 Method m = c.getMethod("getInstance"); 63 return (Metrics) m.invoke(null); 64 } catch (ClassNotFoundException e) { 65 return null; 66 } catch (ReflectiveOperationException e) { 67 throw new InternalError(e); 68 } 69 } 70 71 /** 72 * Returns the interface responsible for providing the 73 * platform metrics. 74 * 75 * @implNote 76 * Metrics are currently only supported Linux. 77 * The provider for Linux is cgroupsv1. 78 * 79 * @return The name of the provider. 80 * 81 */ 82 public String getProvider(); 83 84 85 /***************************************************************** 86 * CPU Accounting Subsystem 87 ****************************************************************/ 88 89 /** 90 * Returns the aggregate time, in nanoseconds, consumed by all 91 * tasks in the Isolation Group. 92 * 93 * @return Time in nanoseconds or 0L if metric is not available. 94 * 95 */ 96 public long getCpuUsage(); 97 98 /** 99 * Returns the aggregate time, in nanoseconds, consumed by all tasks in 100 * the Isolation Group, separated by CPU. If the current process 101 * is running within a container, the reported time will only be 102 * valid for processes running within the same container. The values 103 * are returned in an array, one entry for each physical processor 104 * on the system. Time values for processors unavailable to this 105 * Group are undefined. 106 * 107 * @return long array of time values. The size of the array is equal 108 * to the total number of physical processors in the system. If 109 * this metric is not available, a zero length array will be 110 * returned. 111 * 112 */ 113 public long[] getPerCpuUsage(); 114 115 /** 116 * Returns the aggregate user time, in nanoseconds, consumed by all 117 * tasks in the Isolation Group. 118 * 119 * @return User time in nanoseconds or 0L if metric is not available. 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 or 0L if metric is not available. 129 * 130 */ 131 public long getCpuSystemUsage(); 132 133 /***************************************************************** 134 * CPU Scheduling Metrics 135 ****************************************************************/ 136 137 /** 138 * Returns the length of the scheduling period, in 139 * microseconds, for processes within the Isolation Group. 140 * 141 * @return time in microseconds or 0L if metric is not available. 142 * 143 */ 144 public long getCpuPeriod(); 145 146 /** 147 * Returns the total available run-time allowed, in microseconds, 148 * during each scheduling period for all tasks in the Isolation 149 * Group. 150 * 151 * @return time in microseconds or -1 if the quota is unlimited. 152 * 153 */ 154 public long getCpuQuota(); 155 156 157 /** 158 * Returns the relative weighting of processes with the Isolation 159 * Group used for prioritizing the scheduling of processes across 160 * all Isolation Groups running on a host. 161 * 162 * @implNote 163 * Popular container orchestration systems have standardized shares 164 * to be multiples of 1024, where 1024 is interpreted as 1 CPU share 165 * of execution. Users can distribute CPU resources to multiple 166 * Isolation Groups by specifying the CPU share weighting needed by 167 * each process. To request 2 CPUS worth of execution time, CPU shares 168 * would be set to 2048. 169 * 170 * @return shares value or -1 if no share set. 171 * 172 */ 173 public long getCpuShares(); 174 175 /** 176 * Returns the number of time-slice periods that have elapsed if 177 * a CPU quota has been setup for the Isolation Group; otherwise 178 * returns 0. 179 * 180 * @return count of elapsed periods or 0 if the quota is unlimited. 181 * 182 */ 183 public long getCpuNumPeriods(); 184 185 /** 186 * Returns the number of time-slice periods that the group has 187 * been throttled or limited due to the group exceeding its quota 188 * if a CPU quota has been setup for the Isolation Group. 189 * 190 * @return count of throttled periods or 0 if the quota is unlimited. 191 * 192 */ 193 public long getCpuNumThrottled(); 194 195 /** 196 * Returns the total time duration, in nanoseconds, that the 197 * group has been throttled or limited due to the group exceeding 198 * its quota if a CPU quota has been setup for the Isolation Group. 199 * 200 * @return Throttled time in nanoseconds or 0 if the quota is unlimited. 201 * 202 */ 203 public long getCpuThrottledTime(); 204 205 206 /** 207 * Returns the number of effective processors that this Isolation 208 * group has available to it. This effective processor count is 209 * computed based on the number of dedicated CPUs, CPU shares and 210 * CPU quotas in effect for this isolation group. 211 * 212 * This method returns the same value as 213 * {@link java.lang.Runtime#availableProcessors()}. 214 * 215 * @return The number of effective CPUs. 216 * 217 */ 218 public long getEffectiveCpuCount(); 219 220 /***************************************************************** 221 * CPU Sets 222 ****************************************************************/ 223 224 /** 225 * Returns the CPUS that are available for execution of processes 226 * in the current Isolation Group. The size of the array is equal 227 * to the total number of CPUs and the elements in the array are the 228 * physical CPU numbers that are available. Some of the CPUs returned 229 * may be offline. To get the current online CPUs, use 230 * {@link getEffectiveCpuSetCpus()}. 231 * 232 * @return An array of available CPUs or a zero length array 233 * if the metric is not available. 234 * 235 */ 236 public int[] getCpuSetCpus(); 237 238 /** 239 * Returns the CPUS that are available and online for execution of 240 * processes within the current Isolation Group. The size of the 241 * array is equal to the total number of CPUs and the elements in 242 * the array are the physical CPU numbers. 243 * 244 * @return An array of available and online CPUs or a zero length 245 * array if the metric is not available. 246 * 247 */ 248 public int[] getEffectiveCpuSetCpus(); 249 250 /** 251 * Returns the memory nodes that are available for use by processes 252 * in the current Isolation Group. The size of the array is equal 253 * to the total number of nodes and the elements in the array are the 254 * physical node numbers that are available. Some of the nodes returned 255 * may be offline. To get the current online memory nodes, use 256 * {@link getEffectiveCpuSetMems()}. 257 * 258 * @return An array of available memory nodes or a zero length array 259 * if the metric is not available. 260 * 261 */ 262 public int[] getCpuSetMems(); 263 264 /** 265 * Returns the memory nodes that are available and online for use by 266 * processes within the current Isolation Group. The size of the 267 * array is equal to the total number of nodes and the elements in 268 * the array are the physical node numbers. 269 * 270 * @return An array of available and online nodes or a zero length 271 * array if the metric is not available. 272 * 273 */ 274 public int[] getEffectiveCpuSetMems(); 275 276 /** 277 * Returns the (attempts per second * 1000), if enabled, that the 278 * operating system tries to satisfy a memory request for any 279 * process in the current Isolation Group when no free memory is 280 * readily available. Use {@link #isCpuSetMemoryPressureEnabled()} to 281 * determine if this support is enabled. 282 * 283 * @return Memory pressure or 0 if not enabled or metric is not 284 * available. 285 * 286 */ 287 public double getCpuSetMemoryPressure(); 288 289 /** 290 * Returns the state of the memory pressure detection support. 291 * 292 * @return true if the support is available and enabled, otherwise false. 293 * 294 */ 295 public boolean isCpuSetMemoryPressureEnabled(); 296 297 /***************************************************************** 298 * Memory Subsystem 299 ****************************************************************/ 300 301 /** 302 * Returns the number of times that user memory requests in the 303 * Isolation Group have exceeded the memory limit. 304 * 305 * @return The number of exceeded requests or 0 if none or metric 306 * is not available. 307 * 308 */ 309 public long getMemoryFailCount(); 310 311 /** 312 * Returns the maximum amount of physical memory, in bytes, that 313 * can be allocated in the Isolation Group. 314 * 315 * @return The maximum amount of memory in bytes or -1 if either 316 * there is no limit set or this metric is not available. 317 * 318 */ 319 public long getMemoryLimit(); 320 321 /** 322 * Returns the largest amount of physical memory, in bytes, that 323 * have been allocated in the Isolation Group. 324 * 325 * @return The largest amount of memory in bytes or 0 if this 326 * metric is not available. 327 * 328 */ 329 public long getMemoryMaxUsage(); 330 331 /** 332 * Returns the amount of physical memory, in bytes, that is currently 333 * allocated in the current Isolation Group. 334 * 335 * @return The amount of memory in bytes allocated or 0 if this 336 * metric is not available. 337 * 338 */ 339 public long getMemoryUsage(); 340 341 /** 342 * Returns the number of times that kernel memory requests in the 343 * Isolation Group have exceeded the kernel memory limit. 344 * 345 * @return The number of exceeded requests or 0 if none or metric 346 * is not available. 347 * 348 */ 349 public long getKernelMemoryFailCount(); 350 351 /** 352 * Returns the maximum amount of kernel physical memory, in bytes, that 353 * can be allocated in the Isolation Group. 354 * 355 * @return The maximum amount of memory in bytes or -1 if either 356 * there is no limit set or this metric is not available. 357 * 358 */ 359 public long getKernelMemoryLimit(); 360 361 /** 362 * Returns the largest amount of kernel physical memory, in bytes, that 363 * have been allocated in the Isolation Group. 364 * 365 * @return The largest amount of memory in bytes or 0 if this 366 * metric is not available. 367 * 368 */ 369 public long getKernelMemoryMaxUsage(); 370 371 /** 372 * Returns the amount of kernel physical memory, in bytes, that 373 * is currently allocated in the current Isolation Group. 374 * 375 * @return The amount of memory in bytes allocated or 0 if this 376 * metric is not available. 377 * 378 */ 379 public long getKernelMemoryUsage(); 380 381 /** 382 * Returns the number of times that networking memory requests in the 383 * Isolation Group have exceeded the kernel memory limit. 384 * 385 * @return The number of exceeded requests or 0 if none or metric 386 * is not available. 387 * 388 */ 389 public long getTcpMemoryFailCount(); 390 391 /** 392 * Returns the maximum amount of networking physical memory, in bytes, 393 * that can be allocated in the Isolation Group. 394 * 395 * @return The maximum amount of memory in bytes or -1 if either 396 * there is no limit set or this metric is not available. 397 * 398 */ 399 public long getTcpMemoryLimit(); 400 401 /** 402 * Returns the largest amount of networking physical memory, in bytes, 403 * that have been allocated in the Isolation Group. 404 * 405 * @return The largest amount of memory in bytes or 0 if this 406 * metric is not available. 407 * 408 */ 409 public long getTcpMemoryMaxUsage(); 410 411 /** 412 * Returns the amount of networking physical memory, in bytes, that 413 * is currently allocated in the current Isolation Group. 414 * 415 * @return The amount of memory in bytes allocated or 0 if this 416 * metric is not available. 417 * 418 */ 419 public long getTcpMemoryUsage(); 420 421 /** 422 * Returns the number of times that user memory requests in the 423 * Isolation Group have exceeded the memory + swap limit. 424 * 425 * @return The number of exceeded requests or 0 if none or metric 426 * is not available. 427 * 428 */ 429 public long getMemoryAndSwapFailCount(); 430 431 /** 432 * Returns the maximum amount of physical memory and swap space, 433 * in bytes, that can be allocated in the Isolation Group. 434 * 435 * @return The maximum amount of memory in bytes or -1 if either 436 * there is no limit set or this metric is not available. 437 * 438 */ 439 public long getMemoryAndSwapLimit(); 440 441 /** 442 * Returns the largest amount of physical memory and swap space, 443 * in bytes, that have been allocated in the Isolation Group. 444 * 445 * @return The largest amount of memory in bytes or 0 if this 446 * metric is not available. 447 * 448 */ 449 public long getMemoryAndSwapMaxUsage(); 450 451 /** 452 * Returns the amount of physical memory and swap space, in bytes, 453 * that is currently allocated in the current Isolation Group. 454 * 455 * @return The amount of memory in bytes allocated or 0 if this 456 * metric is not available. 457 * 458 */ 459 public long getMemoryAndSwapUsage(); 460 461 /** 462 * Returns the state of the Operating System Out of Memory termination 463 * policy. 464 * 465 * @return Returns true if operating system will terminate processes 466 * in the Isolation Group that exceed the amount of available 467 * memory, otherwise false. Flase will be returned if this 468 * capability is not available on the current operating system. 469 * 470 */ 471 public boolean isMemoryOOMKillEnabled(); 472 473 /** 474 * Returns the hint to the operating system that allows groups 475 * to specify the minimum amount of physical memory that they need to 476 * achieve reasonable performance in low memory systems. This allows 477 * host systems to provide greater sharing of memory. 478 * 479 * @return The minimum amount of physical memory, in bytes, that the 480 * operating system will try to maintain under low memory 481 * conditions. If this metric is not available, 0 will be 482 * returned. 483 * 484 */ 485 public long getMemorySoftLimit(); 486 487 /***************************************************************** 488 * BlKIO Subsystem 489 ****************************************************************/ 490 491 /** 492 * Returns the number of block I/O requests to the disk that have been 493 * issued by the Isolation Group. 494 * 495 * @return The count of requests or 0 if this metric is not available. 496 * 497 */ 498 public long getBlkIOServiceCount(); 499 500 /** 501 * Returns the number of block I/O bytes that have been transferred 502 * to/from the disk by the Isolation Group. 503 * 504 * @return The number of bytes transferred or 0 if this metric is not available. 505 * 506 */ 507 public long getBlkIOServiced(); 508 }