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 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 cgroupsv1.
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 0L 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, a zero length array 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 0L 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 0L 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 0L 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 -1 if the quota is unlimited.
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 -1 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 0 if the quota is unlimited.
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 0 if the quota is unlimited.
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 0 if the quota is unlimited.
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 a zero length array
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 a zero length
243 * array 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 a zero length array
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 a zero length
269 * array if the metric is not available.
270 *
271 */
272 public int[] getEffectiveCpuSetMems();
273
274 /**
275 * Returns the (attempts per second * 1000), if enabled, that the
276 * operating system tries to satisfy a memory request for any
277 * process in the current Isolation Group when no free memory is
278 * readily available. Use {@link #isCpuSetMemoryPressureEnabled()} to
279 * determine if this support is enabled.
280 *
281 * @return Memory pressure or 0 if not enabled or metric is not
282 * available.
283 *
284 */
285 public double getCpuSetMemoryPressure();
286
287 /**
288 * Returns the state of the memory pressure detection support.
289 *
290 * @return true if the support is available and enabled, otherwise false.
291 *
292 */
293 public boolean isCpuSetMemoryPressureEnabled();
294
295 /*****************************************************************
296 * Memory Subsystem
297 ****************************************************************/
298
299 /**
300 * Returns the number of times that user memory requests in the
301 * Isolation Group have exceeded the memory limit.
302 *
303 * @return The number of exceeded requests or 0 if none or metric
304 * is not available.
305 *
306 */
307 public long getMemoryFailCount();
308
309 /**
310 * Returns the maximum amount of physical memory, in bytes, that
311 * can be allocated in the Isolation Group.
312 *
313 * @return The maximum amount of memory in bytes or -1 if either
314 * there is no limit set or this metric is not available.
315 *
316 */
317 public long getMemoryLimit();
318
319 /**
320 * Returns the largest amount of physical memory, in bytes, that
321 * have been allocated in the Isolation Group.
322 *
323 * @return The largest amount of memory in bytes or 0 if this
324 * metric is not available.
325 *
326 */
327 public long getMemoryMaxUsage();
328
329 /**
330 * Returns the amount of physical memory, in bytes, that is currently
331 * allocated in the current Isolation Group.
332 *
333 * @return The amount of memory in bytes allocated or 0 if this
334 * metric is not available.
335 *
336 */
337 public long getMemoryUsage();
338
339 /**
340 * Returns the number of times that kernel memory requests in the
341 * Isolation Group have exceeded the kernel memory limit.
342 *
343 * @return The number of exceeded requests or 0 if none or metric
344 * is not available.
345 *
346 */
347 public long getKernelMemoryFailCount();
348
349 /**
350 * Returns the maximum amount of kernel physical memory, in bytes, that
351 * can be allocated in the Isolation Group.
352 *
353 * @return The maximum amount of memory in bytes or -1 if either
354 * there is no limit set or this metric is not available.
355 *
356 */
357 public long getKernelMemoryLimit();
358
359 /**
360 * Returns the largest amount of kernel physical memory, in bytes, that
361 * have been allocated in the Isolation Group.
362 *
363 * @return The largest amount of memory in bytes or 0 if this
364 * metric is not available.
365 *
366 */
367 public long getKernelMemoryMaxUsage();
368
369 /**
370 * Returns the amount of kernel physical memory, in bytes, that
371 * is currently allocated in the current Isolation Group.
372 *
373 * @return The amount of memory in bytes allocated or 0 if this
374 * metric is not available.
375 *
376 */
377 public long getKernelMemoryUsage();
378
379 /**
380 * Returns the number of times that networking memory requests in the
381 * Isolation Group have exceeded the kernel memory limit.
382 *
383 * @return The number of exceeded requests or 0 if none or metric
384 * is not available.
385 *
386 */
387 public long getTcpMemoryFailCount();
388
389 /**
390 * Returns the maximum amount of networking physical memory, in bytes,
391 * that can be allocated in the Isolation Group.
392 *
393 * @return The maximum amount of memory in bytes or -1 if either
394 * there is no limit set or this metric is not available.
395 *
396 */
397 public long getTcpMemoryLimit();
398
399 /**
400 * Returns the largest amount of networking physical memory, in bytes,
401 * that have been allocated in the Isolation Group.
402 *
403 * @return The largest amount of memory in bytes or 0 if this
404 * metric is not available.
405 *
406 */
407 public long getTcpMemoryMaxUsage();
408
409 /**
410 * Returns the amount of networking physical memory, in bytes, that
411 * is currently allocated in the current Isolation Group.
412 *
413 * @return The amount of memory in bytes allocated or 0 if this
414 * metric is not available.
415 *
416 */
417 public long getTcpMemoryUsage();
418
419 /**
420 * Returns the number of times that user memory requests in the
421 * Isolation Group have exceeded the memory + swap limit.
422 *
423 * @return The number of exceeded requests or 0 if none or metric
424 * is not available.
425 *
426 */
427 public long getMemoryAndSwapFailCount();
428
429 /**
430 * Returns the maximum amount of physical memory and swap space,
431 * in bytes, that can be allocated in the Isolation Group.
432 *
433 * @return The maximum amount of memory in bytes or -1 if either
434 * there is no limit set or this metric is not available.
435 *
436 */
437 public long getMemoryAndSwapLimit();
438
439 /**
440 * Returns the largest amount of physical memory and swap space,
441 * in bytes, that have been allocated in the Isolation Group.
442 *
443 * @return The largest amount of memory in bytes or 0 if this
444 * metric is not available.
445 *
446 */
447 public long getMemoryAndSwapMaxUsage();
448
449 /**
450 * Returns the amount of physical memory and swap space, in bytes,
451 * that is currently allocated in the current Isolation Group.
452 *
453 * @return The amount of memory in bytes allocated or 0 if this
454 * metric is not available.
455 *
456 */
457 public long getMemoryAndSwapUsage();
458
459 /**
460 * Returns the state of the Operating System Out of Memory termination
461 * policy.
462 *
463 * @return Returns true if operating system will terminate processes
464 * in the Isolation Group that exceed the amount of available
465 * memory, otherwise false. Flase will be returned if this
466 * capability is not available on the current operating system.
467 *
468 */
469 public boolean isMemoryOOMKillEnabled();
470
471 /**
472 * Returns the hint to the operating system that allows groups
473 * to specify the minimum amount of physical memory that they need to
474 * achieve reasonable performance in low memory systems. This allows
475 * host systems to provide greater sharing of memory.
476 *
477 * @return The minimum amount of physical memory, in bytes, that the
478 * operating system will try to maintain under low memory
479 * conditions. If this metric is not available, 0 will be
480 * returned.
481 *
482 */
483 public long getMemorySoftLimit();
484
485 /*****************************************************************
486 * BlKIO Subsystem
487 ****************************************************************/
488
489 /**
490 * Returns the number of block I/O requests to the disk that have been
491 * issued by the Isolation Group.
492 *
493 * @return The count of requests or 0 if this metric is not available.
494 *
495 */
496 public long getBlkIOServiceCount();
497
498 /**
499 * Returns the number of block I/O bytes that have been transferred
500 * to/from the disk by the Isolation Group.
501 *
502 * @return The number of bytes transferred or 0 if this metric is not available.
503 *
504 */
505 public long getBlkIOServiced();
506 }