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