Eclipse MicroProfile Metrics API

Since Payara Server 4.1.2.181 and 5.181

Provided version of the API: MicroProfile Metrics 3.0

The Metrics API was designed to provide monitoring support for applications as well as the underlying runtime. This is considered separate to health checks which are concerned with a binary status of "healthy" or "unhealthy". In design, the Metrics API has borrowed heavily from DropWizard Metrics, so many of the concepts in the API will be familiar.

For a full overview of the API, review the documentation for the appropriate release.

A key goal of the specification was to provide HTTP endpoints in Prometheus format (as well as JSON). Since the Prometheus Text format is widely used by monitoring products other than Prometheus, this gives a lot of compatibility out-of-the-box.

Upgrading from MicroProfile 3.x to 4.x

MicroProfile 4.0 brings with it a number of changes to MicroProfile Metrics, among these changes are some which break previous behaviour. The majority of the breaking changes only affect those using the MicroProfile Metrics API programmatically (rather than using the annotations).

All Metrics Now Reusable

In Metrics 3.0 all metrics are now considered reusable, and as such a number of methods related to this have been removed from the API.

There isn’t a workaround for this, you must simply make sure that you’re not using any of the methods from the API and that you were not expecting any of your custom metrics to not be reusable.

MetadataBuilder.withOptional* Methods Removed

Only relevant to those using the MicroProfile Metrics API programmatically (rather than using the annotations), these methods have simply been removed.

You should instead use the MetadataBuilder.with* methods, which all accept null as a "not present" value (with the exception of the withName method which must have a defined value).

As an example, if you were using the MetadataBuilder.withOptionalDisplayName(String displayName) method, you must now use the MetadataBuilder.withDisplayName(String displayName) method.

Metadata.getDescription() and Metadata.getUnit() Return Type Changed

Only relevant to those using the MicroProfile Metrics API programmatically (rather than using the annotations), these methods now return a String rather than an Optional<String>.

Two new methods have been added to the API for those who wish to still get an Optional<String> return type: Metadata.description() and Metadata.unit()

Timer.update(long duration, TimeUnit unit) Removed

Only relevant to those using the MicroProfile Metrics API programmatically (rather than using the annotations), this method has been replaced by Timer.update(Duration duration).

There is no workaround for this, the original method has simply been removed and you must now use the new one.