examples/mp-metrics-gauge/README.adoc

= 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:

[source,bash]
----
$ 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:

[source,bash]
----
$ 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`.

[source,java]
----
@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:

[source,bash]
----
$ curl -X GET http://localhost:8080/mp-metrics-gauge/metrics/application/weather_day_temperature
----

=== Prometeus Response:

[source]
----
 # 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

[source,javascript]
----
 {
     "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

[source,bash]
----
$ curl -X OPTIONS http://localhost:8080/mp-metrics-gauge/metrics/application/weather_day_temperature
----

 == Response:

[source,javascript]
----
 {
     "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.