examples/mp-metrics-gauge/README_pt.adoc

= Métricas com MicroProfile `@Gauge` (Medida)
:index-group: MicroProfile
:jbake-type: page
:jbake-status: published

Este é um exemplo sobre como utilizar as métricas de MicroProfile em TomEE.

== Executando a aplicação:

[source,bash]
----
$ mvn clean install tomee:run
----

Dentro da aplicação, tem um endpoint que vai fornecer a temperatura em celsius para o dia.

== Obter a temperatura para o dia:

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

== Resposta:
 30

== Usando `@Gauge`

As métricas do MicroProfile têm uma função para medir. 
O valor e o tipo da medida são iguais ao valor e ao tipo do método anotado.

Para usar esta função, você deve anotar os métodos dos recursos JAX-RS com `@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;
    }
}
----

Existem algumas configurações, como parte do `@Gauge`, que você precisa saber:

*String name*
Opcional. Define o nome da métrica. Se não for fornecido
explicitamente, o nome do objeto anotado é usado.

*boolean absolute*
Se verdadeiro, use o nome fornecido como o nome absoluto da métrica. Se falso, coloque o nome do pacote e o nome da classe antes do nome fornecido. O valor padrão é falso.

*String displayName*
Opcional. Um nome de exibição legível para metadados.

*String description*
Opcional. Uma descrição da métrica.

*String[] tags*
Opcional. Matriz de cadeia no formato = para fornecer etiquetas especiais a uma métrica.

*String unit*
Unidade da métrica. Veja a classe MetricUnits para obter uma lista de unidades padrão.

== Dados Métricos

Verifique a medida fazendo uma requisição _GET_:

=== Formato Prometheus:

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

=== Resposta Prometheus:

[source]
----
 # TYPE application:weather_day_temperature_celsius gauge
 application:weather_day_temperature_celsius{weather="temperature"} 30.0
----

=== Formato JSON:

Para o formato json, adicione o cabeçalho Accept=application/json à requisição.

=== Resposta JSON

[source,javascript]
----
 {
     "weather_day_temperature": 30
 }
----

== Metadatos Métrica

Uma métrica terá metadados para que você possa aprender mais sobre ela, como `displayName`,`descrição`, `tags` etc.

Verifique os metadados da métrica fazendo uma solicitação HTTP _OPTIONS_:

=== Solicitação HTTP _OPTIONS_

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

=== Resposta:

[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"
     }
 }
----

Você também pode testá-lo usando WeatherServiceTest.java disponível no projeto.