Preloader image

MicroProfile Metrics Gauge

This is an example on how to use MicroProfile metrics in TomEE.

Run the application:

$ mvn clean install tomee:run

Within the application there is an endpoint that will give you the weather temperature in celsius for the day.

For the day temperature call:

$ curl -X GET http://localhost:8080/mp-metrics-gauge/weather/day/temperature

Response:

30

Gauge Feature

MicroProfile metrics has a gauge feature. The gauge value and type is equal to the annotated method return value and type.

To use this feature you need to annotate the JAX-RS resource method with @Gauge.

@Path("/weather")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@ApplicationScoped
public class WeatherService {

    @Path("/day/temperature")
    @Gauge(name = "weather_day_temperature", absolute = true, unit = "celsius",
            displayName = "Weather Day Temperature",
            description = "This metric shows the day temperature.",
            tags = {"weather=temperature"})
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public Integer dayTemperature() {
        return 30;
    }
}

There are some configurations, as part of @Gauge, that you need to know:

String name Optional. Sets the name of the metric. If not explicitly given the name of the annotated object is used.

boolean absolute If true, uses the given name as the absolute name of the metric. If false, prepends the package name and class name before the given name. Default value is false.

String displayName Optional. A human-readable display name for metadata.

String description Optional. A description of the metric.

String[] tags Optional. Array of Strings in the <key>=<value> format to supply special tags to a metric.

String unit Unit of the metric. Check the MetricUnits class for a set of pre-defined units.

Metric data

Check the gauge metric doing a GET request:

Prometheus format:

$ curl -X GET http://localhost:8080/mp-metrics-gauge/metrics/application/weather_day_temperature

Prometeus Response:

 # TYPE application:weather_day_temperature_celsius gauge
 application:weather_day_temperature_celsius{weather="temperature"} 30.0

JSON Format:

For json format add the header Accept=application/json to the request.

JSON Response

 {
     "weather_day_temperature": 30
 }

Metric metadata

A metric will have a metadata so you can know more information about it, like displayName, description, tags, etc.

Check the metric metadata doing a OPTIONS request:

OPTIONS HTTP Request

$ curl -X OPTIONS http://localhost:8080/mp-metrics-gauge/metrics/application/weather_day_temperature
== Response:
 {
     "weather_day_temperature": {
         "unit": "celsius",
         "displayName": "Weather Day Temperature",
         "name": "weather_day_temperature",
         "typeRaw": "GAUGE",
         "description": "This metric shows the day temperature.",
         "type": "gauge",
         "value": {
             "unit": "celsius",
             "displayName": "Weather Day Temperature",
             "name": "weather_day_temperature",
             "tagsAsString": "weather=\"temperature\"",
             "typeRaw": "GAUGE",
             "description": "This metric shows the day temperature.",
             "type": "gauge",
             "reusable": false,
             "tags": {
                 "weather": "temperature"
             }
         },
         "reusable": false,
         "tags": "weather=temperature"
     }
 }

You can also try it out using the WeatherServiceTest.java available in the project.

APIs Used