Base metrics is a list of metrics that all vendors need to implement. Optional base metrics are recommended to be implemented but are not required.
These metrics are exposed under /metrics/base
.
The following is a list of required and optional base metrics. All metrics are singletons and have Multi:
set to false
unless otherwise stated.
Visit architecture.adoc for the meaning of each key
Note
|
Although vendors are required to implement these base metrics, some virtual machines can not provide them. Vendors should either use other metrics that are close enough as substitute or not fill these base metrics at all. |
UsedHeapMemory
Name |
memory.usedHeap |
Type |
Gauge |
Unit |
Bytes |
Description |
Displays the amount of used heap memory in bytes. |
MBean |
java.lang:type=Memory/HeapMemoryUsage#used |
CommittedHeapMemory
Name |
memory.committedHeap |
Type |
Gauge |
Unit |
Bytes |
Description |
Displays the amount of memory in bytes that is committed for the Java virtual machine to use. This amount of memory is guaranteed for the Java virtual machine to use. |
MBean |
java.lang:type=Memory/HeapMemoryUsage#committed |
Notes |
Also from JSR 77 |
MaxHeapMemory
Name |
memory.maxHeap |
Type |
Gauge |
Unit |
Bytes |
Description |
Displays the maximum amount of heap memory in bytes that can be used for memory management. This attribute displays -1 if the maximum heap memory size is undefined. This amount of memory is not guaranteed to be available for memory management if it is greater than the amount of committed memory. The Java virtual machine may fail to allocate memory even if the amount of used memory does not exceed this maximum size. |
MBean |
java.lang:type=Memory/HeapMemoryUsage#max |
GCCount
Name |
gc.total |
Type |
Counter |
Unit |
None |
Multi |
true |
Tags |
{name=%s} |
Description |
Displays the total number of collections that have occurred. This attribute lists -1 if the collection count is undefined for this collector. |
MBean |
java.lang:type=GarbageCollector,name=%s/CollectionCount |
Notes |
There can be multiple garbage collectors active that are assigned to different memory pools. The %s should be substituted with the name of the garbage collector. |
GCTime - Approximate accumulated collection elapsed time in ms
Name |
gc.time |
Type |
Gauge |
Unit |
Seconds |
Multi |
true |
Tags |
{name=%s} |
Description |
Displays the approximate accumulated collection elapsed time in seconds. This attribute displays -1 if the collection elapsed time is undefined for this collector. The Java virtual machine implementation may use a high resolution timer to measure the elapsed time. This attribute may display the same value even if the collection count has been incremented if the collection elapsed time is very short. |
MBean |
java.lang:type=GarbageCollector,name=%s/CollectionTime |
Notes |
There can be multiple garbage collectors active that are assigned to different memory pools. The %s should be substituted with the name of the garbage collector. The MicroProfile Metrics runtime will need to convert the metric’s value to seconds if the value is provided in a different unit. |
JVM Uptime - Up time of the Java Virtual machine
Name |
jvm.uptime |
Type |
Gauge |
Unit |
Seconds |
Description |
Displays the time elapsed since the start of the Java virtual machine in seconds. |
MBean |
java.lang:type=Runtime/Uptime |
Notes |
Also from JSR 77. The MicroProfile Metrics runtime will need to convert the metric’s value to seconds if the value is provided in a different unit. |
ThreadCount
Name |
thread.count |
Type |
Gauge |
Unit |
None |
Description |
Displays the current number of live threads including both daemon and non-daemon threads |
MBean |
java.lang:type=Threading/ThreadCount |
DaemonThreadCount
Name |
thread.daemon.count |
Type |
Gauge |
Unit |
None |
Description |
Displays the current number of live daemon threads. |
MBean |
java.lang:type=Threading/DaemonThreadCount |
PeakThreadCount
Name |
thread.max.count |
Type |
Gauge |
Unit |
None |
Description |
Displays the peak live thread count since the Java virtual machine started or peak was reset. This includes daemon and non-daemon threads. |
MBean |
java.lang:type=Threading/PeakThreadCount |
(Optional) ActiveThreads
Name |
threadpool.activeThreads |
Type |
Gauge |
Unit |
None |
Multi |
true |
Tags |
{pool=%s} |
Description |
Number of active threads that belong to a specific thread pool. |
Notes |
The %s should be substituted with the name of the thread pool. This is a vendor specific attribute/operation that is not defined in java.lang. |
(Optional) PoolSize
Name |
threadpool.size |
Type |
Gauge |
Unit |
None |
Multi |
true |
Tags |
{pool=%s} |
Description |
The size of a specific thread pool. |
Notes |
The %s should be substituted with the name of the thread pool. This is a vendor specific attribute/operation that is not defined in java.lang. |
LoadedClassCount
Name |
classloader.loadedClasses.count |
Type |
Gauge |
Unit |
None |
Description |
Displays the number of classes that are currently loaded in the Java virtual machine. |
MBean |
java.lang:type=ClassLoading/LoadedClassCount |
TotalLoadedClassCount
Name |
classloader.loadedClasses.total |
Type |
Counter |
Unit |
None |
Description |
Displays the total number of classes that have been loaded since the Java virtual machine has started execution. |
MBean |
java.lang:type=ClassLoading/TotalLoadedClassCount |
UnloadedClassCount
Name |
classloader.unloadedClasses.total |
Type |
Counter |
Unit |
None |
Description |
Displays the total number of classes unloaded since the Java virtual machine has started execution. |
MBean |
java.lang:type=ClassLoading/UnloadedClassCount |
AvailableProcessors
Name |
cpu.availableProcessors |
Type |
Gauge |
Unit |
None |
Description |
Displays the number of processors available to the Java virtual machine. This value may change during a particular invocation of the virtual machine. |
MBean |
java.lang:type=OperatingSystem/AvailableProcessors |
(Optional) SystemLoadAverage
Name |
cpu.systemLoadAverage |
Type |
Gauge |
Unit |
None |
Description |
Displays the system load average for the last minute. The system load average is the sum of the number of runnable entities queued to the available processors and the number of runnable entities running on the available processors averaged over a period of time. The way in which the load average is calculated is operating system specific but is typically a damped time-dependent average. If the load average is not available, a negative value is displayed. This attribute is designed to provide a hint about the system load and may be queried frequently. The load average may be unavailable on some platforms where it is expensive to implement this method. |
MBean |
java.lang:type=OperatingSystem/SystemLoadAverage |
(Optional) ProcessCpuLoad
Name |
cpu.processCpuLoad |
Type |
Gauge |
Unit |
Percent |
Description |
Displays the "recent cpu usage" for the Java Virtual Machine process |
MBean |
java.lang:type=OperatingSystem (com.sun.management.UnixOperatingSystemMXBean for Oracle Java, similar one exists for IBM Java: com.ibm.lang.management.ExtendedOperatingSystem) Note: This is a vendor specific attribute/operation that is not defined in java.lang |
(Optional) ProcessCpuTime
Name |
cpu.processCpuTime |
Type |
Gauge |
Unit |
Seconds |
Description |
Displays the CPU time used by the process on which the Java virtual machine is running in seconds. |
MBean |
java.lang:type=OperatingSystem (com.sun.management.UnixOperatingSystemMXBean for Oracle Java, similar one exists for IBM Java: com.ibm.lang.management.ExtendedOperatingSystem) Note: This is a vendor specific attribute/operation that is not defined in java.lang. The MicroProfile Metrics runtime will need to convert the metric’s value to seconds if the value is provided in a different unit. |
Metrics gathered from REST stats are optional and therefore may not be available in every implementation.
The MicroProfile Metrics runtime will track metrics from RESTful resource method calls during runtime (i.e GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD). It is up to the implementation to decide how to enable the REST metrics.
The metrics defined below will treat a REST request that ends in a mapped exception or an unmapped exception differently. For the MicroProfile Metrics runtime, mapped exceptions and succesful REST requests should be considered and handled the same way. This is because mapped exceptions are expected by the developer and may then be handled appropriately as part of the application’s expected behviour. Unmapped exceptions on the other hand are unexpected and can skew metric data if its' respective REST request is recorded. To avoid contaminating the metric values with these unsuccesful REST requests, the below metrics may omit tracking a REST request that ends with an unmapped exception. There are also metrics that purposely track REST requests that end with an unmapped exception.
(Optional) RESTRequest
Name |
REST.request |
Type |
SimpleTimer |
Unit |
None |
Multi |
true |
Tags |
{class=%s1,method=%s2} |
Description |
The number of invocations and total response time of this RESTful resource method since the start of the server. The metric will not record the elapsed time nor count of a REST request if it resulted in an unmapped exception. Also tracks the highest recorded time duration within the previous completed full minute and lowest recorded time duration within the previous completed full minute. |
Notes |
With an asynchronous request the timing that is tracked by the REST metric must incorporate the time spent by the asynchronous call. The The Parameter type formatting rules: |
(Optional) RESTRequestUnmappedExceptions
Name |
REST.request.unmappedException.total |
Type |
Counter |
Unit |
None |
Multi |
true |
Tags |
{class=%s1,method=%s2} |
Description |
The total number of unmapped exceptions that occur from this RESTful resouce method since the start of the server. |
Notes |
The The Parameter type formatting rules: |
For example given the following RESTful resource:
package org.eclipse.microprofile.metrics.demo;
@ApplicationScoped
public class RestDemo {
@POST
public void postMethod(Object o, String... s){
...
}
}
The OpenMetrics formatted rest metrics would be:
# TYPE base_REST_request_total counter
base_REST_request_total{class="org.eclipse.microprofile.metrics.demo.RestDemo",method="postMethod_java.lang.Object_java.lang.String[]"} 1
# TYPE base_REST_request_elapsedTime_seconds gauge
base_REST_request_elapsedTime_seconds{class="org.eclipse.microprofile.metrics.demo.RestDemo",method="postMethod_java.lang.Object_java.lang.String[]"} 1.000
# TYPE base_REST_request_maxTimeDuration_seconds gauge
base_REST_request_maxTimeDuration_seconds{class="org.eclipse.microprofile.metrics.demo.RestDemo",method="postMethod_java.lang.Object_java.lang.String[]"} 1.000
# TYPE base_REST_request_minTimeDuration_seconds gauge
base_REST_request_minTimeDuration_seconds{class="org.eclipse.microprofile.metrics.demo.RestDemo",method="postMethod_java.lang.Object_java.lang.String[]"} 1.000
# TYPE base_REST_request_unmappedException_total counter
base_REST_request_unmappedException_total{class="org.eclipse.microprofile.metrics.demo.RestDemo",method="postMethod_java.lang.Object_java.lang.String[]"} 0