Use BOM for Micrometer dependency examples in reference docs (#5652)

This avoids dynamic versions in dependency declaration examples, and it encourages use of dependency management for consistent, static versions. Also uses the specific version of the docs being built, so it matches the documentation's version. See gh-5093 Co-authored-by: Jonatan Ivanov <[email protected]> Co-authored-by: Tommy Ludwig <[email protected]>
micrometer-metrics · Nov 18, 2024 · 55f90e2 · 55f90e2
1 parent a0f4911
commit 55f90e2
Show file tree

Hide file tree

Showing 7 changed files with 150 additions and 62 deletions.
diff --git a/docs/modules/ROOT/pages/contextpropagation/installing.adoc b/docs/modules/ROOT/pages/contextpropagation/installing.adoc
@@ -7,22 +7,31 @@ Milestone releases are published to https://repo.spring.io/milestone. Include th
 configuration to use milestone releases. Note that milestone releases are for testing purposes and are not intended for
 production use.
 
-The following example shows the required dependency in Gradle:
+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], the following example adds Context Propagation in Gradle:
+
+[source,groovy]
 ----
-implementation 'io.micrometer:context-propagation:latest.integration'
+implementation 'io.micrometer:context-propagation'
 ----
 
-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], the following example adds Context Propagation in Maven:
+
+[source,xml]
 ----
 <dependencies>
     <dependency>
         <groupId>io.micrometer</groupId>
         <artifactId>context-propagation</artifactId>
-        <version>${micrometer-context-propagation.version}</version>
     </dependency>
 </dependencies>
 ----
+
+NOTE: The version is not needed for this dependency since it is defined by the BOM.
diff --git a/docs/modules/ROOT/pages/implementations/_install.adoc b/docs/modules/ROOT/pages/implementations/_install.adoc
@@ -1,20 +1,29 @@
 [[implementations-installing]]
 == Installing
 
-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.
diff --git a/docs/modules/ROOT/pages/implementations/datadog.adoc b/docs/modules/ROOT/pages/implementations/datadog.adoc
@@ -9,26 +9,35 @@ Datadog is a dimensional time-series SaaS with built-in dashboarding and alertin
 Micrometer supports shipping metrics to Datadog directly by using its HTTP API or by using DogStatsD through the xref:/implementations/statsD.adoc[StatsD registry].
 If you can choose between the two, the API approach is far more efficient.
 
+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]
@@ -74,24 +83,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]

diff --git a/docs/modules/ROOT/pages/implementations/influx.adoc b/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]

diff --git a/docs/modules/ROOT/pages/installing.adoc b/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`.

diff --git a/docs/modules/ROOT/pages/observation/installing.adoc b/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.
diff --git a/docs/modules/ROOT/pages/observation/testing.adoc b/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