includes.metrics.micrometer-shared.adoc Maven / Gradle / Ivy

Go to download
///////////////////////////////////////////////////////////////////////////////
    Copyright (c) 2021, 2023 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.

///////////////////////////////////////////////////////////////////////////////
// tag::intro[]
ifndef::rootdir[:rootdir: {docdir}/../..]
ifndef::flavor-lc[:flavor-lc: se]
ifeval::["{flavor-lc}" == "se"]
:se-flavor:
endif::[]
ifeval::["{flavor-lc}" == "mp"]
:mp-flavor:
endif::[]
:feature-name: Micrometer support

//Contains content that is shared between multiple Micrometer pages.
:keywords: helidon, java, micrometer, integration, se, mp

== Overview
Helidon {h1-prefix} simplifies how you can use Micrometer for application-specific metrics:

* The endpoint `/micrometer`: A configurable endpoint that exposes metrics according to which Micrometer meter registry
responds to the HTTP request.


ifdef::se-flavor[]
* The `MicrometerSupport` class: A convenience class for enrolling Micrometer meter registries your application
creates explicitly or for selecting which built-in Micrometer meter registries
to use.
endif::se-flavor[]
ifdef::mp-flavor[]
* The Micrometer annotations `@Timed` and `@Counted`.
endif::mp-flavor[]
* Configuration to tailor the Prometheus and other Micrometer meter registries.

In Helidon {helidon-version}, Micrometer support is separate from the Helidon {h1-prefix} metrics API and the built-in Helidon metrics.

// end::intro[]

// tag::prereq[]
include::{rootdir}/includes/dependencies.adoc[]

[source,xml,subs="verbatim,attributes"]
----

    io.helidon.integrations.micrometer
ifdef::se-flavor[]
    helidon-integrations-micrometer
endif::se-flavor[]
ifdef::mp-flavor[]
    helidon-integrations-micrometer-cdi
endif::mp-flavor[]

----

Micrometer supports different types of meter registries which have different output styles and formats.
Helidon provides built-in support for the Prometheus meter registry.
To use other meter registry types, you will need to add dependencies for them to your `pom.xml` and, optionally, add
ifdef::se-flavor[]
code to your application or add
endif::se-flavor[]
configuration to set them up as you wish.

// end::prereq[]

// tag::overriding-intro[]
==== Overriding Defaults for Built-in Meter Registry Types
Unless you specify otherwise, Helidon uses defaults for any built-in Micrometer meter registry.
For example, Helidon configures the built-in Prometheus registry using `PrometheusConfig.DEFAULT`.

// end::overriding-intro[]


// tag::overriding-using-config[]
To use configuration to control the selection and behavior of Helidon's built-in Micrometer meter registries,
include in your configuration (such as `application.yaml`) a `micrometer.builtin-registries` section.

.Enroll Prometheus built-in meter registry using default configuration
ifdef::se-flavor[]
[source,yaml]
----
micrometer:
  builtin-registries:
    - type: prometheus
----
endif::[]
ifdef::mp-flavor[]
[source,properties]
----
micrometer.builtin-registries.0.type=prometheus
----
endif::[]

.Enroll Prometheus built-in meter registry with non-default configuration
ifdef::se-flavor[]
[source,yaml]
----
micrometer:
  builtin-registries:
    - type: prometheus
      prefix: myPrefix
----
endif::[]
ifdef::mp-flavor[]
[source,properties]
----
micrometer.builtin-registries.0.type=prometheus
micrometer.builtin-registries.0.prefix=myPrefix
----
endif::[]
Note that the first config example is equivalent to the default Helidon Micrometer behavior; Helidon by default supports the Prometheus meter registry.

The configuration keys that are valid for the `builtin-registries` child entries depend on the type of Micrometer meter
registry.
For example, support in Helidon for the link:{micrometer-javadoc-registry-prometheus-base-url}/PrometheusConfig.html[Prometheus meter registry] respects the `prefix` configuration setting but other meter registries might not and might support other settings.
Refer to the documentation for the meter registry you want to configure to find out what items apply to that registry
type.

Helidon does not validate the configuration keys you specify for
meter registries.

// end::overriding-using-config[]

// tag::accessing-endpoint-intro[]
=== Accessing the Helidon Micrometer Endpoint

ifdef::mp-flavor[Helidon MP Micrometer integration automatically creates]
ifdef::se-flavor[Your application can easily have Helidon create]
a REST endpoint which clients can access to retrieve Micrometer metrics, by default at the `/micrometer` endpoint.

ifdef::se-flavor[]
Within Helidon, each type of meter registry is paired with some code that examines the incoming HTTP request to `/micrometer` and decides
whether the request matches up with the associated meter registry. The first pairing that accepts the request
returns the response. You will need to take advantage of this if your application uses additional meter registries beyond what Helidon automatically provides _and_ you want those meter registries reflected in the output from the `/micrometer` REST endpoint.
endif::[]
// end::accessing-endpoint-intro[]

// tag::configuring-endpoint[]
== Configuration
You can configure the Helidon Micrometer REST service as you can other built-in Helidon services by adding configuration settings under the `micrometer` top-level key.

include::{rootdir}/config/io_helidon_integrations_micrometer_MicrometerFeature.adoc[tag=config,leveloffset=+1]

By default, Helidon Micrometer integration exposes the `/micrometer` endpoint.
You can override the path using
ifdef::se-flavor[]
the link:{micrometer-javadoc-base-url}/MicrometerSupport.Builder.html[`Builder`] or
endif::se-flavor[]
the `micrometer.web-context` configuration key.

.Overriding the default Micrometer path
ifdef::se-flavor[]
[source,yaml]
----
micrometer:
  web-context: my-micrometer
----
endif::[]
ifdef::mp-flavor[]
[source,properties]
----
micrometer.web-context=my-micrometer
----
endif::[]

// end::configuring-endpoint[]

// tag::accessing-endpoint-end[]

// end::accessing-endpoint-end[]

// Following tag assumes the referring document is mid-sentence, with something like "Your code"
// tag::use-micrometer-api[]
can create, look up, and update metrics programmatically using the Micrometer `MeterRegistry` API. The link:{micrometer-api-url}[Micrometer concepts document] provides a good starting point for learning how to use Micrometer's interfaces and classes.
// end::use-micrometer-api[]

// tag::example-apps[]
Helidon {flavor-uc} includes an link:{helidon-github-tree-url}/examples/integrations/micrometer/{flavor-lc}[example application] which uses Micrometer support.
// end::example-apps[]

// end::all-micrometer[]