Merge branch '1.13.x' into 1.14.x

docs/modules/ROOT/pages/implementations/_install.adoc

@@ -1,20 +1,29 @@
 [id=installing-micrometer-registry-{system}]
 == Installing micrometer-registry-{system}
 
-For Gradle, add the following implementation:
+It is recommended to use the BOM provided by Micrometer (or your framework if any), you can see how to configure it xref:../installing.adoc[here]. The examples below assume you are using a BOM.
+
+=== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,groovy,subs=+attributes]
 ----
-implementation 'io.micrometer:micrometer-registry-{system}:latest.release'
+implementation 'io.micrometer:micrometer-registry-{system}'
 ----
 
-For Maven, add the following dependency:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+=== Maven
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,xml,subs=+attributes]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-registry-{system}</artifactId>
-  <version>${micrometer.version}</version>
 </dependency>
 ----
+
+NOTE: The version is not needed for this dependency since it is defined by the BOM.

docs/modules/ROOT/pages/implementations/datadog.adoc

@@ -11,26 +11,35 @@ If you can choose between the two, the API approach is far more efficient.
 
 NOTE: If you encounter a rate limit problem with the Datadog API approach, try the DogStatsD approach or one of https://docs.datadoghq.com/metrics/guide/micrometer/[alternatives that are described in the Datadog documentation].
 
+It is recommended to use the BOM provided by Micrometer (or your framework if any), you can see how to configure it xref:../installing.adoc[here]. The examples below assume you are using a BOM.
+
 === Direct to Datadog API Approach
 
-For Gradle, add the following implementation:
+==== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,groovy]
 ----
-implementation 'io.micrometer:micrometer-registry-datadog:latest.release'
+implementation 'io.micrometer:micrometer-registry-datadog'
 ----
 
-For Maven, add the following dependency:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+==== Maven
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,xml]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-registry-datadog</artifactId>
-  <version>${micrometer.version}</version>
 </dependency>
 ----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
 Metrics are rate-aggregated and pushed to `datadoghq` on a periodic interval. Rate aggregation performed by the registry yields datasets that are similar to those produced by `dogstatsd`.
 
 [source, java]
@@ -76,24 +85,31 @@ For example, for the `US5` site, the correct API endpoint is `https://api.us5.da
 
 === Through DogStatsD Approach
 
-For Gradle, add the following implementation:
+==== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
-[source,groovy,subs=+attributes]
+[source,groovy]
 ----
-implementation 'io.micrometer:micrometer-registry-statsd:latest.release'
+implementation 'io.micrometer:micrometer-registry-statsd'
 ----
 
-For Maven, add the following dependency:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+==== Maven
+
+After the BOM is xref:../installing.adoc[configured]d, add the following dependency:
 
-[source,xml,subs=+attributes]
+[source,xml]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-registry-statsd</artifactId>
-  <version>${micrometer.version}</version>
 </dependency>
 ----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
 Metrics are immediately shipped to DogStatsD using Datadog's flavor of the StatsD line protocol. `java-dogstatsd-client` is _not_ needed on the classpath for this to work, as Micrometer uses its own implementation.
 
 [source,java]

docs/modules/ROOT/pages/implementations/influx.adoc

@@ -6,30 +6,39 @@ The InfluxData suite of tools supports real-time stream processing and storage o
 
 The InfluxMeterRegistry supports the 1.x InfluxDB API as well as the v2 API.
 
-== Configuring
+== Installation and Configuration
 
 Micrometer supports shipping metrics to InfluxDB directly or through Telegraf through the StatsD registry.
 
+It is recommended to use the BOM provided by Micrometer (or your framework if any), you can see how to configure it xref:../installing.adoc[here]. The examples below assume you are using a BOM.
+
 === Direct to InfluxDB
 
-The following example adds the required library in Gradle:
+==== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,groovy]
 ----
-implementation 'io.micrometer:micrometer-registry-influx:latest.release'
+implementation 'io.micrometer:micrometer-registry-influx'
 ----
 
-The following example adds the required library in Maven:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+==== Maven
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,xml]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-registry-influx</artifactId>
-  <version>${micrometer.version}</version>
 </dependency>
 ----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
 Metrics are rate-aggregated and pushed to InfluxDB on a periodic interval. Rate aggregation performed by the registry yields datasets that are quite similar to those produced by Telegraf. The following example configures a meter registry for InfluxDB:
 
 .InfluxDB 1.x configuration example
@@ -113,24 +122,31 @@ management.metrics.export.influx:
 
 Telegraf is a StatsD agent that expects a modified flavor of the StatsD line protocol.
 
-The following listing adds the relevant library in Gradle:
+==== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,groovy]
 ----
-implementation 'io.micrometer:micrometer-registry-statsd:latest.release'
+implementation 'io.micrometer:micrometer-registry-statsd'
 ----
 
-The following listing adds the relevant library in Maven:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+==== Maven
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
 
 [source,xml]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-registry-statsd</artifactId>
-  <version>${micrometer.version}</version>
 </dependency>
 ----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
 Metrics are shipped immediately over UDP to Telegraf by using Telegraf's flavor of the StatsD line protocol:
 
 [source,java]

docs/modules/ROOT/pages/installing.adoc

@@ -4,26 +4,61 @@
 
 Micrometer contains a core library with the instrumentation SPI and an in-memory implementation that does not export data anywhere, a series of modules with implementations for various monitoring systems, and a test module.
 
-To use Micrometer, add the dependency for your monitoring system.
+To use Micrometer, add the dependency for your monitoring system. It is recommended to use the BOM provided by Micrometer, you can configure it as follows (you only need to declare it once in your project).
 
-The following example adds Prometheus in Gradle:
+NOTE: If you use a framework, it might have dependency management that defines Micrometer versions or imports the Micrometer BOM. You can defer to the framework's dependency management instead of declaring the Micrometer BOM directly in that case.
+
+== Gradle
+
+The following example configures the Micrometer BOM in Gradle:
+
+[source,groovy,subs=+attributes]
+----
+implementation platform('io.micrometer:micrometer-bom:{micrometer-version}')
+----
+
+After the BOM is configured, the following example adds Prometheus in Gradle:
 
 [source,groovy]
 ----
-implementation 'io.micrometer:micrometer-registry-prometheus:latest.release'
+implementation 'io.micrometer:micrometer-registry-prometheus'
+----
+
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+== Maven
+
+The following example configures the Micrometer BOM in Maven:
+
+[source,xml,subs=+attributes]
+----
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.micrometer</groupId>
+            <artifactId>micrometer-bom</artifactId>
+            <version>{micrometer-version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
 ----
 
-The following example adds Prometheus in Maven:
+After the BOM is configured, the following example adds Prometheus in Maven:
 
 [source,xml]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-registry-prometheus</artifactId>
-  <version>${micrometer.version}</version>
 </dependency>
 ----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+== Multiple Monitoring Systems
+
 Through Micrometer's composite meter registry (described in greater detail in xref:/concepts/registry.adoc#_composite_registries["Concepts"]), you can configure more than one registry implementation if you intend to publish metrics to more than one monitoring system.
 
 If you have not decided on a monitoring system yet and want only to try out the instrumentation SPI, you can add a dependency on `micrometer-core` instead and configure the `SimpleMeterRegistry`.

docs/modules/ROOT/pages/observation/installing.adoc

@@ -1,36 +1,29 @@
 [[micrometer-observation-install]]
 = Installing
 
-Micrometer comes with a Bill of Materials (BOM), which is a project that manages all the project versions for consistency.
+It is recommended to use the BOM provided by Micrometer (or your framework if any), you can see how to configure it xref:../installing.adoc[here]. The examples below assume you are using a BOM.
 
-The following example shows the required dependency for Micrometer Observation in Gradle:
+== Gradle
 
-[source,groovy,subs=+attributes]
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
+
+[source,groovy]
 ----
-implementation platform('io.micrometer:micrometer-bom:latest.release')
 implementation 'io.micrometer:micrometer-observation'
 ----
 
-The following example shows the required dependency in Maven:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+== Maven
 
-[source,xml,subs=+attributes]
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
+
+[source,xml]
 ----
-<dependencyManagement>
-    <dependencies>
-        <dependency>
-            <groupId>io.micrometer</groupId>
-            <artifactId>micrometer-bom</artifactId>
-            <version>${micrometer.version}</version>
-            <type>pom</type>
-            <scope>import</scope>
-        </dependency>
-    </dependencies>
-</dependencyManagement>
-
-<dependencies>
-    <dependency>
-      <groupId>io.micrometer</groupId>
-      <artifactId>micrometer-observation</artifactId>
-    </dependency>
-</dependencies>
+<dependency>
+  <groupId>io.micrometer</groupId>
+  <artifactId>micrometer-observation</artifactId>
+</dependency>
 ----
+
+NOTE: The version is not needed for this dependency since it is defined by the BOM.

docs/modules/ROOT/pages/observation/testing.adoc

@@ -6,16 +6,24 @@ Micrometer Observation comes with the `micrometer-observation-test` module, whic
 [[micrometer-observation-installing]]
 == Installing
 
-The following example shows the required dependency in Gradle (assuming that the Micrometer BOM has been added):
+It is recommended to use the BOM provided by Micrometer (or your framework if any), you can see how to configure it xref:../installing.adoc[here]. The examples below assume you are using a BOM.
 
-[source,groovy,subs=+attributes]
+=== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
+
+[source,groovy]
 -----
 testImplementation 'io.micrometer:micrometer-observation-test'
 -----
 
-The following example shows the required dependency in Maven (assuming that the Micrometer BOM has been added):
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+=== Maven
 
-[source,xml,subs=+attributes]
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
+
+[source,xml]
 -----
 <dependency>
     <groupId>io.micrometer</groupId>
@@ -24,6 +32,8 @@ The following example shows the required dependency in Maven (assuming that the
 </dependency>
 -----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
 [[micrometer-observation-runnning]]
 == Running Observation Unit Tests
 

docs/modules/ROOT/pages/reference/java-httpclient.adoc

@@ -2,23 +2,37 @@
 
 Since Java 11, an `HttpClient` is provided as part of the JDK. See https://openjdk.org/groups/net/httpclient/intro.html[this introduction] to it. Micrometer provides instrumentation of this via a `micrometer-java11` module. This module requires Java 11 or later.
 
-For Gradle, add the following implementation:
+== Installing
 
-[source,groovy,subs=+attributes]
+It is recommended to use the BOM provided by Micrometer (or your framework if any), you can see how to configure it xref:../installing.adoc[here]. The examples below assume you are using a BOM.
+
+=== Gradle
+
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
+
+[source,groovy]
 ----
 implementation 'io.micrometer:micrometer-java11'
 ----
 
-For Maven, add the following dependency:
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+=== Maven
 
-[source,xml,subs=+attributes]
+After the BOM is xref:../installing.adoc[configured], add the following dependency:
+
+[source,xml]
 ----
 <dependency>
   <groupId>io.micrometer</groupId>
   <artifactId>micrometer-java11</artifactId>
 </dependency>
 ----
 
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
+
+== Usage
+
 Create an `HttpClient` as you normally would. For example:
 
 [source,java,subs=+attributes]