required-metrics.adoc

Required Metrics

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.

General JVM Stats

UsedHeapMemory

Name	memory.usedHeap
DisplayName	Used Heap Memory
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
DisplayName	Committed Heap Memory
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
DisplayName	Max Heap Memory
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
DisplayName	Garbage Collection Count
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
DisplayName	Garbage Collection 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
DisplayName	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.

Thread JVM Stats

ThreadCount

Name	thread.count
DisplayName	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
DisplayName	Daemon Thread 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
DisplayName	Peak Thread 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

Thread Pool Stats

(Optional) ActiveThreads

Name	threadpool.activeThreads
DisplayName	Active Threads
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
DisplayName	Thread Pool 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.

ClassLoading JVM Stats

LoadedClassCount

Name	classloader.loadedClasses.count
DisplayName	Current Loaded Class 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
DisplayName	Total Loaded Class Count
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
DisplayName	Total Unloaded Class Count
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

Operating System

AvailableProcessors

Name	cpu.availableProcessors
DisplayName	Available Processors
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
DisplayName	System Load Average
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
DisplayName	Process CPU Load
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
DisplayName	Process CPU Time
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.

(Optional) REST

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.

Mapped and Unmapped Exceptions

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
DisplayName	Total Requests and Response Time
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 %s1 should be substituted with the fully qualified name of the RESTful resource class. The %s2 should be substituted with the name of the RESTful resource method and appended with its parameter types using an underscore _. Multiple parameter types are appended one after another (e.g. <methodName>_<paramType1>_<paramType2>). Parameter type formatting rules: - The paramter types are fully qualified (e.g. java.lang.Object). - Array paramter types will be formatted as paramType[] (e.g java.lang.Object[]). - A Vararg parameter will be treated as an array. - Generics will be ignored. For example List<String> will be formatted as java.util.List.

(Optional) RESTRequestUnmappedExceptions

Name	REST.request.unmappedException.total
DisplayName	Total Unmapped Exceptions count
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 %s1 should be substituted with the fully qualified name of the RESTful resource class. The %s2 should be substituted with the name of the RESTful resource method and appended with its parameter types using an underscore _. Multiple parameter types are appended one after another (e.g. <methodName>_<paramType1>_<paramType2>). Parameter type formatting rules: - The paramter types are fully qualified (e.g. java.lang.Object). - If the implementation supports array parameters, array parameter types will be formatted as paramType[] (e.g java.lang.Object[]). - A Vararg parameter will be treated as an array. - Generics will be ignored. For example List<String> will be formatted as java.util.List.

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