mp.metrics.micrometer.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
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 Support
:description: Helidon Micrometer integration
:keywords: micrometer, helidon, metrics, integration, microprofile
:rootdir: {docdir}/../..
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
- <>
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=intro]
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=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
To use Micrometer support, you can simply add the Micrometer `@Timed` and `@Counted` annotations to methods in your application. Helidon automatically registers those meters with the Micrometer composite `MeterRegistry`.
In addition to annotating your methods, 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
To incorporate Micrometer metrics into your code, you will work with two APIs: a small one specific to Helidon, and the Micrometer API itself.
=== The Helidon Micrometer API
Helidon automatically registers and updates meters associated with methods in your service where you add the Micrometer annotations.
If you want to use the Micrometer `MeterRegistry` directly from your own code, simply `@Inject` the `MeterRegistry` into one of your REST resource classes or any other bean which CDI recognizes. Helidon injects the same Micrometer `MeterRegistry` that it uses for handling Micrometer annotations you add to your code.
=== The Micrometer API
Your code
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=use-micrometer-api]
// Configuration
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=configuring-endpoint]
== Examples
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=example-apps]
The examples below take you step-by-step through the process of enhancing the Helidon MP QuickStart application to track (by time and invocation count) all `GET` methods and to count all requests for a personalized greeting.
=== Add Micrometer annotations
[source,java]
.Adding Micrometer annotations to JAX-RS resource `GET` methods
----
include::{sourcedir}/mp/metrics/MicrometerSnippets.java[tag=snippet_1, indent=0]
----
<1> Use `@Timed` to time and count both `GET` methods.
<2> Use `@Counted` to count the accesses to the `GET` method that returns a personalized greeting.
=== Using the Helidon-provided Micrometer `MeterRegistry` from Code
In addition to annotating your methods, you can create, look up, and update metrics explicitly in your code.
Add the following injection to a bean:
[source,java]
.Inject the `MeterRegistry`
----
include::{sourcedir}/mp/metrics/MicrometerSnippets.java[tag=snippet_2, indent=0]
----
Helidon automatically injects a reference to the `MeterRegistry` it manages into your code. Your code can use the
normal Micrometer API with this registry to create, find, update, and even delete meters.
include::{rootdir}/includes/metrics/micrometer-shared.adoc[tags=overriding-intro;overriding-using-config]
== Additional Information
The link:https://micrometer.io[Micrometer website] describes the project as a whole and has links to more information.