Payara Platform 5.193 Supports MicroProfile Metrics 2.0

Payara Platform 5.193 includes full support for MicroProfile Metrics 2.0. While MP Metrics has been covered in previous blogs, some important changes have been introduced that we will cover here.

Basic Metrics

Metrics can still be accessed via:

curl http://localhost:8080/metrics

# TYPE vendor_sytem_cpu_load gauge
# HELP vendor_system_cpu_load Display the "recent cpu usage" for the whole system. This value is a double in the [0.0,1.0] interval. A value of 0.0 means that all CPUs were idle during the recent period of time observed, while a value of 1.0 means that all CPUs were actively running 100% of the time during the recent period being observed. All values betweens 0.0 and 1.0 are possible depending of the activities going on in the system. If the system recent cpu usage is not available, the method returns a negative value.
vendor_system_cpu_load 0.1491192437579042
# TYPE base_classloader_total_loaded_class_count counter
# HELP base_classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the JVM has started execution.
base_classloader_total_loaded_class_count 11250
# TYPE base_cpu_system_load_average gauge
# HELP base_cpu_system_load_average 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 platform where it is expensive to implement this method.
base:cpu_system_load_average -1.0
# TYPE base_thread_count counter
# HELP base_thread_count Displays the current number of live threads including both daemon and non-daemon threads.
base:thread_count 73
# TYPE base_classloader_current_loaded_class_count counter
# HELP base_classloader_current_loaded_class_count Displays the number of classes that are currently loaded in the JVM.
base_classloader_current_loaded_class_count 10992

...etc

Note that instead of a colon between the registry and the metric name there is now an underscore.

Tags Added to Metrics

The biggest change in Metrics 2.0 is the addition of tags to metrics. Tags can be set at the server level with the MicroProfile Config property mp.metrics.tags. It can also be set using the "tags" property of the annotation on the method or class, in the form tags"key=value, otherKey=otherValue". Keys must be in the format [a-zA-Z_][a-zA-Z0-9_]* while the tags can be any valid UTF-8 character, for example:

@Gauge(unit = MetricUnits.NONE, name = "inventorySize", description = "Number of items", tags="foo=bar")
public int getTotal() {
    return 5;
}

In the metrics page this will be displayed as:

#TYPE application_package_ClassName_inventorySize gauge

#HELP application_package_ClassName_inventorySize Number of items

application_package_ClassName_inventorySize{foo="bar"} 5

As in earlier version of Metrics, the /metrics endpoint can also be fetched in JSON format, in which case the above example would display as so:

application {

"package.ClassName.inventorySize;foo=rab": 5

// Any other application metrics

}

There is also a global tag which is applied to all metrics, which is set with the MicroProfile Config property of mp.metrics.tags, which can be set in the admin console of Payara Server under Server -> Properties -> MicroProfile Properties.

Counters Changes

The other big change to Metrics 2.0 is with the @Counted annotation. In previous versions it had the monotonic attribute, which has now been removed. All Counters now only increase; they are used to count the number of invocations of a method.

For the previously non-monotonic Counters, there is ConcurrentGauge. ConcurrentGauge is a new metric type, and can both increase and decrease (but only by 1 at a time) and when used as a method annotation measures number of concurrent invocations of the annotated method. ConcurrentGauge returns three metrics, the current amount, the minimum and the maximum in the previous minute. Note that by previous minute, this is not the previous 60 seconds but the 60 seconds leading up to the last time the clock was at 00 seconds, this means that if the endpoint is called at 10:34:53, the minimum and maximum displayed will be the minimum and maximum invocations of the method in the from 10:33:00 up until 10:34:00.

Other Breaking Changes

In OpenMetrics format the separator between the scope and metric name is now a _ instead of a : and reserved characters must be escaped. The garbage collection metrics have also changes, instead of being in the form of gc.%s.total with %s being the name of the garbage collector, it is now gc.total with the tag of name=%s.

For an example of an application using MicroProfile Metrics 2.0, see https://github.com/payara/Payara-Examples/tree/master/microprofile/metrics-example.

For the full specification see https://github.com/eclipse/microprofile-metrics/releases/download/2.0.2/microprofile-metrics-spec-2.0.2.pdf.

Payara Services and MicroProfile

Payara's is a Strategic Member of MicroProfile. To give MicroProfile Metrics 2.0 a try, download Payara Micro and  use the MicroProfile Starter to generate a MicroProfile Maven Project with code examples: https://start.microprofile.io/. 

Download Payara Micro