examples/mp-metrics-metered/README.adoc

= MicroProfile Metrics Metered
: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 enpoint that will give you a weather status
for the day and week.

== For the day status call:

[source,bash]
----
$ curl -X GET http://localhost:8080/mp-metrics-metered/weather/day/status
----

== Response:

[source,text]
----
Hi, today is a sunny day!
----

== Metered Feature
MicroProfile metrics has a feature that can be used to find the rate of
requests to a service.

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

[source,java]
----
@Path("/weather")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@ApplicationScoped
public class WeatherService {

    @Path("/day/status")
    @Metered(name = "dailyStatus",
             unit = MetricUnits.MINUTES,
             description = "Metrics to daily weather status method",
             absolute = true)
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String dayStatus() {
        return "Hi, today is a sunny day!";
    }
...
}
----

There are some configurations, as part of `@Metered`, 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.

**boolean reusable**
Denotes if a metric with a certain name can be registered in more than one
place. Does not apply to gauges.

**String unit**
Unit of the metric. Default for `@Metered` is nanoseconds.

== Metric data

Check the Metered metric doing a _GET_ request:

== Prometheus format:

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

== Response:

[source,text]
----
# TYPE application:daily_status_seconds_count meter
application:daily_status_seconds_count 1.2E-7
# TYPE application:daily_status_rate_per_second meter
application:daily_status_rate_per_second 0.0
# TYPE application:daily_status_one_min_rate_per_second meter
application:daily_status_one_min_rate_per_second 1.3376002644204984E-19
# TYPE application:daily_status_five_min_rate_per_second meter
application:daily_status_five_min_rate_per_second 3.5942838529305413E-20
# TYPE application:daily_status_fifteen_min_rate_per_second meter
application:daily_status_fifteen_min_rate_per_second 3.4665766454142955E-21
----

== JSON Format:

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

[source,javascript]
----
{
	"dailyStatus": {
		"count": 2,
		"fifteenMinRate": 5.77762774235716e-14,
		"fiveMinRate": 5.990473088217569e-13,
		"meanRate": 0,
		"oneMinRate": 2.229333774034164e-12,
		"unit": "minutes"
	}
}
----

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

== Request

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

== Response:

[source,javascript]
----
{
	"dailyStatus": {
		"description": "Metrics to daily weather status method",
		"displayName": "",
		"name": "dailyStatus",
		"reusable": false,
		"tags": "",
		"type": "meter",
		"typeRaw": "METERED",
		"unit": "minutes"
	}
}
----


== Test the application:

[source,bash]
----
$ mvn test
----