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