///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2018, 2019 Oracle and/or its affiliates. All rights reserved.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= Metrics
:description: Helidon metrics
:keywords: helidon, metrics

Helidon SE provides the following to support metrics:

1. The endpoint `/metrics`: A configurable endpoint that exposes metrics information in JSON format (as specified by the
    MicroProfile Metrics specification) or in plain text (for Prometheus metrics).
2. A base set of metrics, available at `/metrics/base`, as specified by the MicroProfile Metrics specification.
3. A set of Helidon-specific metrics, available at `/metrics/vendor`


== Prerequisites

Declare the following dependency in your project:

[source,xml,subs="verbatim,attributes"]
----
    <dependency>
        <groupId>io.helidon.metrics</groupId>
        <artifactId>helidon-metrics</artifactId>
    </dependency>
----

== Using Metrics in Your Application
To enable Metrics, register it with the WebServer.

[source,java]
----
import io.helidon.metrics.MetricsSupport;
//...

Routing.builder()
                .register(MetricsSupport.create())
                .register("/myapp", new MyService())
                .build();
----

Then you can use metrics in your service.

[source,java]
.Define and use a Metrics Counter
----
import io.helidon.metrics.RegistryFactory;
import org.eclipse.microprofile.metrics.Counter;
import org.eclipse.microprofile.metrics.MetricRegistry;
//...

public class MyService implements Service {

    private final MetricRegistry registry = RegistryFactory.getRegistryFactory().get()
        .getRegistry(MetricRegistry.Type.APPLICATION); <1>
    private final Counter accessCtr = registry.counter("accessctr"); <2>

    @Override
    public void update(Routing.Rules rules) {
        rules
             .any(this::countAccess)
             .get("/", this::myGet);
    }

    private void countAccess(ServerRequest request, ServerResponse response) {
            accessCtr.inc(); //<3>
            request.next();
    }
}
----

<1> Get the application metrics registry
<2> Create a counter in that registry
<3> Increment the counter for every request

== Accessing Metrics Endpoint

Access metrics data via the `/metrics` endpoint. Two reporting formats
are supported. The HTTP Accept header sent by the client determines
the reporting format:

1. JSON format - used when the HTTP Accept header matches `application/json`
2. Prometheus text format - used when the HTTP Accept header is `text/plain`
   or otherwise does not match `application/json`

[source,bash]
.Example Reporting: Prometheus format
----
curl -s -H 'Accept: text/plain' -X GET http://localhost:8080/metrics/
# TYPE base:classloader_total_loaded_class_count counter
# HELP base:classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the Java virtual machine has started execution.
base:classloader_total_loaded_class_count 3157
#...
----

[source,bash]
.Example Reporting: JSON format
----
curl -s -H 'Accept: application/json' -X GET http://localhost:8080/metrics/ | json_pp
{
   "base" : {
      "memory.maxHeap" : 3817865216,
      "memory.committedHeap" : 335544320,
#...
----

In addition to your application metrics the reports contain other
metrics of interest such as system and VM information.

For full details see the
https://github.com/eclipse/microprofile-metrics/releases[MicroProfile Metrics]
specification.

The Metrics component in Helidon SE is the core for the Helidon MP implementation of the MicroProfile Metrics specification.
