= MicroProfile Metrics Gauge

:index-group: MicroProfile
:jbake-type: page
:jbake-status: published

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:
 GET http://localhost:8080/mp-metrics-gauge/weather/day/temperature

.Response:
 30

[discrete]
==== 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.+++</value>++++++</key>+++

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

[discrete]
==== Metric data

Check the gauge metric doing a _GET_ request:

.Prometheus format:
 GET http://localhost:8080/mp-metrics-gauge/metrics/application/weather_day_temperature

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

[discrete]
===== JSON Format:

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

 {
     "weather_day_temperature": 30
 }

[discrete]
==== Metric metadata

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

Check the metric metadata doing a _OPTIONS_ request:

.Request
 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.
