From 55f90e21b6d506394ec0cf02cfbb8e71533a9892 Mon Sep 17 00:00:00 2001 From: Johnny Lim Date: Mon, 18 Nov 2024 12:54:21 +0900 Subject: [PATCH] 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 Co-authored-by: Tommy Ludwig <8924140+shakuzen@users.noreply.github.com> --- .../pages/contextpropagation/installing.adoc | 21 ++++++--- .../ROOT/pages/implementations/_install.adoc | 17 +++++-- .../ROOT/pages/implementations/datadog.adoc | 36 ++++++++++----- .../ROOT/pages/implementations/influx.adoc | 34 ++++++++++---- docs/modules/ROOT/pages/installing.adoc | 45 ++++++++++++++++--- .../ROOT/pages/observation/installing.adoc | 41 +++++++---------- .../ROOT/pages/observation/testing.adoc | 18 ++++++-- 7 files changed, 150 insertions(+), 62 deletions(-) diff --git a/docs/modules/ROOT/pages/contextpropagation/installing.adoc b/docs/modules/ROOT/pages/contextpropagation/installing.adoc index f07a24c1bf..be9bb6883c 100644 --- 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] ---- io.micrometer context-propagation - ${micrometer-context-propagation.version} ---- + +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 index 6f6820fe34..2f5084e4cc 100644 --- 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] ---- io.micrometer micrometer-registry-{system} - ${micrometer.version} ---- + +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 index bf53fa412b..f7c1811c45 100644 --- 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] ---- io.micrometer micrometer-registry-datadog - ${micrometer.version} ---- +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] ---- io.micrometer micrometer-registry-statsd - ${micrometer.version} ---- +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 index 84248002fc..d47267e939 100644 --- 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] ---- io.micrometer micrometer-registry-influx - ${micrometer.version} ---- +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] ---- io.micrometer micrometer-registry-statsd - ${micrometer.version} ---- +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 index 1c180843bb..a14aec350e 100644 --- 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] +---- + + + + io.micrometer + micrometer-bom + {micrometer-version} + pom + import + + + ---- -The following example adds Prometheus in Maven: +After the BOM is configured, the following example adds Prometheus in Maven: [source,xml] ---- io.micrometer micrometer-registry-prometheus - ${micrometer.version} ---- +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 index 787fc85294..6f3769bcf8 100644 --- 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] ---- - - - - io.micrometer - micrometer-bom - ${micrometer.version} - pom - import - - - - - - - io.micrometer - micrometer-observation - - + + io.micrometer + micrometer-observation + ---- + +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 index 760d275bb4..6485c2643e 100644 --- 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] ----- io.micrometer @@ -24,6 +32,8 @@ The following example shows the required dependency in Maven (assuming that the ----- +NOTE: The version is not needed for this dependency since it is defined by the BOM. + [[micrometer-observation-runnning]] == Running Observation Unit Tests