diff --git a/docs/includes/attributes.adoc b/docs/includes/attributes.adoc index e9ddff040cd..6ed47a21f4d 100644 --- a/docs/includes/attributes.adoc +++ b/docs/includes/attributes.adoc @@ -76,6 +76,7 @@ endif::[] :version-lib-oracle-ucp: {version-lib-oracle-jdbc} :version-plugin-jib: 0.10.1 :version-plugin-jandex: 1.0.6 +:version-lib-micrometer: 1.6.6 :jdk-version: 17 @@ -258,5 +259,7 @@ endif::[] :micrometer-url: https://micrometer.io :micrometer-api-url: https://micrometer.io/docs/concepts +:micrometer-javadoc-base-url: https://javadoc.io/doc/io.micrometer +:micrometer-javadoc-registry-prometheus-base-url: {micrometer-javadoc-base-url}/micrometer-registry-prometheus/{version-lib-micrometer}/io/micrometer/prometheus endif::attributes-included[] diff --git a/docs/includes/metrics/metrics-capable-components.adoc b/docs/includes/metrics/metrics-capable-components.adoc index 3e6874a59ac..509afc6ce2c 100644 --- a/docs/includes/metrics/metrics-capable-components.adoc +++ b/docs/includes/metrics/metrics-capable-components.adoc @@ -77,9 +77,10 @@ endif::[] As you plan and write Helidon components and applications, you make some choices about exactly how your code will use metrics. This document gives some background information, -describes the choices you face, explains their ramifications, and provides some code examples. +describes each option and its effect, and provides some code examples. == Usage +This section helps you decide how incorporate metrics into your software by describing the categories of metrics usage, explaining generally how Helidon implements metrics, and illustrating how to write the metrics-related code accordingly. === Categorizing Metrics Usage We can place each Helidon component and Helidon application into one of three categories based on how it relies on metrics. @@ -103,10 +104,10 @@ The type of module dictates the compile-time dependency you declare in the proje |metrics-dependent |=== -Whenever possible, if your component or app uses metrics write it as metrics-capable code. +Whenever possible, if your component or application uses metrics, then write it as metrics-capable code. === Understanding the Two Metrics Implementations -Helidon provides two metrics implementations. +Helidon provides two metrics implementations: * _Full-featured_ metrics allows registering, removing, and updating metrics and observing metrics' changing values. The `helidon-metrics` component contains full-featured metrics. @@ -292,8 +293,8 @@ Helidon returns either a full-featured `RegistryFactory` or a minimal one, depen // tag::writing-code-ending[] == Examples -=== An Example: Docker Images -Here is an example showing how useful metrics-capable code can be. + +The following example shows how useful metrics-capable code can be in the context of building Docker images. You (or others) could assemble a Docker image with your metrics-capable app as its top layer or your metrics-capable component in a middle layer, built on a lower layer containing several Helidon modules including the full metrics implementation. When that Docker image runs, your app will run with full-featured metrics support. diff --git a/docs/includes/metrics/metrics-config.adoc b/docs/includes/metrics/metrics-config.adoc index df7f0f2bd2a..003cc3a1913 100644 --- a/docs/includes/metrics/metrics-config.adoc +++ b/docs/includes/metrics/metrics-config.adoc @@ -81,7 +81,7 @@ Helidon updates and reports a metric only if two conditions hold: ** there is no `include` regex pattern, or ** the metric name matches the `include` pattern. -[CAUTION] +[NOTE] ==== Make sure any `include` regex pattern you specify matches _all_ the metric names you want to capture. ==== @@ -150,14 +150,14 @@ endif::[] [#config-rest-request] ifdef::mp-flavor[] -==== Enable `REST.request` metrics +==== Enable `REST.request` Metrics .Controlling REST request metrics [source,properties] ---- metrics.rest-request-enabled=true ---- -Helidon will automatically register and update `SimpleTimer` metrics for every REST endpoint in your service. +Helidon automatically registers and updates `SimpleTimer` metrics for every REST endpoint in your service. endif::[] // end::config-examples[] \ No newline at end of file diff --git a/docs/includes/metrics/metrics-shared.adoc b/docs/includes/metrics/metrics-shared.adoc index aeb5551c4ed..b2dbc81c439 100644 --- a/docs/includes/metrics/metrics-shared.adoc +++ b/docs/includes/metrics/metrics-shared.adoc @@ -57,7 +57,7 @@ ifdef::mp-flavor[each of these.] ifdef::se-flavor[this.] === Categorizing Types of Metrics -Helidon distinguishes among three general _types_, or scopes, of metrics, as described in the MP metrics specification. +Helidon distinguishes among three general _types_, or scopes, of metrics, as described in the link:{microprofile-metrics-spec-url}[MP metrics specification]. .Types (scopes) of metrics [%autowidth] @@ -128,7 +128,7 @@ curl -s -H 'Accept: application/json' -X GET http://localhost:8080/metrics/ } ---- -In addition to your application metrics the reports contain other +In addition to your application metrics, the reports contain other metrics of interest such as system and VM information. // end::usage-body[] diff --git a/docs/includes/metrics/micrometer-shared.adoc b/docs/includes/metrics/micrometer-shared.adoc index 97be0d2a64b..b95f7ffd680 100644 --- a/docs/includes/metrics/micrometer-shared.adoc +++ b/docs/includes/metrics/micrometer-shared.adoc @@ -124,7 +124,7 @@ Note that the first config example is equivalent to the default Helidon Micromet The configuration keys that are valid for the `builtin-registries` child entries depend on the type of Micrometer meter registry. -For example, the Prometheus meter registry supports the `prefix` configuration setting but other meter registries might not and might support other settings. +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. diff --git a/docs/includes/openapi.adoc b/docs/includes/openapi.adoc index 3fe63125925..e0a7952378f 100644 --- a/docs/includes/openapi.adoc +++ b/docs/includes/openapi.adoc @@ -29,7 +29,7 @@ ifdef::se-flavor[OpenAPI support in Helidon {flavor-uc} draws its inspiration fr The OpenAPI support in Helidon {flavor-uc} performs two main tasks: * Build an in-memory model of the REST API your service implements. -* Expose the model in text format (typically yaml) via the `/openapi` endpoint. +* Expose the model in text format (typically YAML) via the `/openapi` endpoint. To construct the model, Helidon gathers information about the service API from whichever of these sources are present in the application: diff --git a/docs/mp/metrics/micrometer.adoc b/docs/mp/metrics/micrometer.adoc index 41d3ebff084..d2ccf83da62 100644 --- a/docs/mp/metrics/micrometer.adoc +++ b/docs/mp/metrics/micrometer.adoc @@ -36,6 +36,9 @@ 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`. @@ -50,6 +53,7 @@ include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=accessing-endpoin == 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. diff --git a/docs/se/metrics/micrometer.adoc b/docs/se/metrics/micrometer.adoc index bd224aa3236..8755b3f9ebc 100644 --- a/docs/se/metrics/micrometer.adoc +++ b/docs/se/metrics/micrometer.adoc @@ -36,6 +36,9 @@ 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