se.metrics.micrometer.adoc Maven / Gradle / Ivy

Go to download
///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2021, 2024 Oracle and/or its affiliates.

    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.

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

= Micrometer Metrics
:description: Helidon Micrometer integration
:keywords: micrometer, helidon, metrics, integration
:rootdir: {docdir}/../..

include::{rootdir}/includes/se.adoc[]

== Contents
- <>
- <>
- <>
** <>
** <>
 - <>
** <>
 - <>
- <>
** <>
** <>
 - <>
`
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tags=intro]
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tags=prereq]

== Usage
Your application registers and updates Micrometer meters using annotations or direct use of the Micrometer API.

Your users retrieve Micrometer meters using an endpoint which Helidon creates automatically.

=== Registering and Updating Meters
Your code
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=use-micrometer-api]

include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=accessing-endpoint-intro]

== API

=== The Helidon Micrometer API

Helidon provides no special API for dealing with Micrometer meters and meter registries beyond what Micrometer offers itself.

Helidon _does_ give you an easy way to expose a REST endpoint to report the meters stored in the Micrometer meter registry. The link:{micrometer-javadoc-base-url}/io/helidon/integrations/micrometer/MicrometerSupport.html[`MicrometerSupport`] interface
exposes static methods to directly create an instance of `MicrometerSupport` and to return a link:{micrometer-javadoc-base-url}/io/helidon/integrations/micrometer/MicrometerSupport.Builder.html[`Builder`] instance so your
code can fine-tune how the REST service behaves.

// Configuration
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=configuring-endpoint]

== Examples

include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=example-apps]

The rest of this section takes you through the process of changing your application to use Helidon SE integration with Micrometer:

. Register an instance of link:{micrometer-javadoc-base-url}/io/helidon/integrations/micrometer/MicrometerSupport.html[`MicrometerSupport`] with the web server.
. Create meters using the meter registry managed by Helidon's `MicrometerSupport` and then update and query those meters.

=== Register an Instance of MicrometerSupport with the Web Server

[source,java]
.Initialize Micrometer support
----
include::{sourcedir}/se/metrics/MicrometerSnippets.java[tag=snippet_1, indent=0]
----
<1> Create the `MicrometerSupport` instance, using the default built-in Prometheus meter registry.
<2> Register the `MicrometerSupport` instance as a service; by default, `MicrometerSupport` exposes the endpoint as `/micrometer`.
<3> Pass the `MicrometerSupport` object's meter registry to your service for use in creating and updating meters.

=== Create and Update Meters in Your Application Service


[source,java]
.Define and use a `Counter`
----
include::{sourcedir}/se/metrics/MicrometerSnippets.java[tag=snippet_2, indent=0]
----
<1> Use the Micrometer meter registry to create the request counter.
<2> Add routing for any request to invoke the method which counts requests by updating the counter.
<3> Update the counter and then delegate the rest of the request processing to the next handler in the chain.

The example above enrolls the built-in Prometheus meter registry with the default Prometheus registry configuration.
You can change the default setup for built-in registries, and you can enroll other meter registries your application
creates itself.

include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=overriding-intro]

You can override these defaults in either of two ways:

* Using the link:{micrometer-javadoc-base-url}/io/helidon/integrations/micrometer/MicrometerSupport.Builder.html[`MicrometerSupport.Builder`] class
* Using configuration

==== Using MicrometerSupport.Builder
Use the `MicrometerSupport.Builder` class to set up Micrometer support however your application needs.

The builder lets you:

* Provide your own Micrometer meter registry configuration that `MicrometerSupport` uses to create a built-in meter
registry, or
* Instantiate a Micrometer meter registry yourself, configured however you want, and add it to the `MicrometerSupport`
object's collection of meter registries

[source,java]
.Overriding defaults for built-in meter registries using `MicrometerSupport.Builder`
----
include::{sourcedir}/se/metrics/MicrometerSnippets.java[tag=snippet_3, indent=0]
----
<1> Enroll the `PROMETHEUS` built-in registry type with your meter registry configuration.


==== Using Configuration

include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=overriding-using-config]


=== Enrolling Other Micrometer Meter Registries
To create additional types of registries and enroll them with `MicrometerSupport`, you need to:

. Write a `Handler` +
+
Each meter registry has its own way of producing output.
Write your handler so that it has a reference to the meter registry it should use and so that
its `accept` method sets the payload in the HTTP response using the registry's mechanism for creating output.

. Write a `Function` which accepts a `ServerRequest` and returns an `Optional` +
+
Typically, the function examines the request--the `Content-Type`, query parameters, etc.--to
decide whether the corresponding handler should respond to the request.
If so, your function should instantiate your `Handler` and return an `Optional.of(theHandlerInstance)`;
otherwise, your function should return `Optional.empty()`. +
+
When `MicrometerSupport` receives a request, it invokes the functions of all the enrolled registries,
stopping as soon as one function provides a handler.
`MicrometerSupport` then delegates to that handler to create and send the response.

. Pass the `Handler` and `Function` to the `MicrometerSupport.enrollRegistry` method to enroll them +
+
[source,java]
.Creating and enrolling your own Micrometer meter registry
----
include::{sourcedir}/se/metrics/MicrometerSnippets.java[tag=snippet_4, indent=0]
----
<1> Create the meter registry. This example uses a Prometheus registry, but it can be any extension of `MeterRegistry`.
<2> Provide the function that checks if the link:{webserver-javadoc-base-url}/io/helidon/webserver/http/ServerRequest.html[`ServerRequest`]
<3> A very simple in-line `Handler` that sets the response entity from the Prometheus registry's `scrape()` method.

include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=accessing-endpoint-intro]

When `MicrometerSupport` receives a request at the endpoint, it looks for the first enrolled meter registry for which
the corresponding `Function>` returns a non-empty `Handler`.
Helidon invokes that `Handler` which must retrieve the metrics output from its meter registry and set
and send the response.
Note that the `Handler` which your function returns typically has a reference to the meter registry it will use
in preparing the response.


== Additional Information

The link:https://micrometer.io[Micrometer website] describes the project as a whole and has links to more information.