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