From baf596d10ed79a0beca95da5cc35420099eb45d9 Mon Sep 17 00:00:00 2001 From: Moritz Halbritter Date: Thu, 6 Feb 2025 12:21:31 +0100 Subject: [PATCH] Document double observations when using @Timed etc. Closes gh-44037 --- .../build/antora/antora-asciidoc-attributes.properties | 1 + .../src/docs/antora/modules/ROOT/pages/redirect.adoc | 4 ++-- .../antora/modules/reference/pages/actuator/metrics.adoc | 8 -------- .../modules/reference/pages/actuator/observability.adoc | 8 ++++++-- 4 files changed, 9 insertions(+), 12 deletions(-) diff --git a/buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-asciidoc-attributes.properties b/buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-asciidoc-attributes.properties index 232e2f271b6..82eba8024b6 100644 --- a/buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-asciidoc-attributes.properties +++ b/buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-asciidoc-attributes.properties @@ -27,6 +27,7 @@ url-gradle-dsl=https://docs.gradle.org/current/dsl url-gradle-javadoc=https://docs.gradle.org/current/javadoc url-kotlin-docs-kotlin-plugin={url-kotlin-docs}/using-gradle.html url-micrometer-docs-concepts={url-micrometer-docs}/concepts +url-micrometer-docs-observation={url-micrometer-docs}/observation url-micrometer-docs-implementations={url-micrometer-docs}/implementations url-native-build-tools-docs=https://graalvm.github.io/native-build-tools/{version-native-build-tools} url-native-build-tools-docs-gradle-plugin={url-native-build-tools-docs}/gradle-plugin.html diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc index f13b183055c..c895003a8de 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc @@ -1192,8 +1192,8 @@ * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.system[#actuator.metrics.supported.system] * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.system[#production-ready-metrics-system] * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.tasks[#actuator.metrics.supported.tasks] -* xref:reference:actuator/metrics.adoc#actuator.metrics.supported.timed-annotation[#actuator.metrics.supported.timed-annotation] -* xref:reference:actuator/metrics.adoc#actuator.metrics.supported.timed-annotation[#production-ready-metrics-timed-annotation] +* xref:reference:actuator/observability.adoc#actuator.observability.annotations[#actuator.metrics.supported.timed-annotation] +* xref:reference:actuator/observability.adoc#actuator.observability.annotations[#production-ready-metrics-timed-annotation] * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.tomcat[#actuator.metrics.supported.tomcat] * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.tomcat[#production-ready-metrics-tomcat] * xref:reference:actuator/metrics.adoc#actuator.metrics.supported[#actuator.metrics.supported] diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/metrics.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/metrics.adoc index b2b1044c0c2..f3e1d0d4f6b 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/metrics.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/metrics.adoc @@ -1124,14 +1124,6 @@ Metrics for Jetty's javadoc:org.eclipse.jetty.server.Connector[] instances are b -[[actuator.metrics.supported.timed-annotation]] -=== @Timed Annotation Support - -To enable scanning of javadoc:io.micrometer.core.annotation.Timed[format=annotation] annotations, you will need to set the configprop:management.observations.annotations.enabled[] property to `true`. -Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer documentation]. - - - [[actuator.metrics.supported.redis]] === Redis Metrics diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/observability.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/observability.adoc index 1e0af36b432..ac4c260c8cf 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/observability.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/observability.adoc @@ -104,5 +104,9 @@ The next sections will provide more details about logging, metrics and traces. [[actuator.observability.annotations]] == Micrometer Observation Annotations support -To enable scanning of metrics and tracing annotations like javadoc:io.micrometer.core.annotation.Timed[format=annotation], javadoc:io.micrometer.core.annotation.Counted[format=annotation], javadoc:io.micrometer.core.aop.MeterTag[format=annotation] and javadoc:io.micrometer.tracing.annotation.NewSpan[format=annotation] annotations, you will need to set the configprop:management.observations.annotations.enabled[] property to `true`. -This feature is supported Micrometer directly. Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer] and {url-micrometer-tracing-docs}/api.html#_aspect_oriented_programming[Micrometer Tracing] reference docs. +To enable scanning of observability annotations like javadoc:io.micrometer.observation.annotation.Observed[format=annotation], javadoc:io.micrometer.core.annotation.Timed[format=annotation], javadoc:io.micrometer.core.annotation.Counted[format=annotation], javadoc:io.micrometer.core.aop.MeterTag[format=annotation] and javadoc:io.micrometer.tracing.annotation.NewSpan[format=annotation] annotations, you need to set the configprop:management.observations.annotations.enabled[] property to `true`. +This feature is supported by Micrometer directly. +Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer], {url-micrometer-docs-observation}/components.html#micrometer-observation-annotations[Micrometer Observation] and {url-micrometer-tracing-docs}/api.html#_aspect_oriented_programming[Micrometer Tracing] reference docs. + +NOTE: When you annotate methods or classes which are already instrumented (for example xref:reference:actuator/metrics.adoc#actuator.metrics.supported.spring-data-repository[Spring Data repositories] or xref:reference:actuator/metrics.adoc#actuator.metrics.supported.spring-mvc[Spring MVC controllers]), you will get duplicate observations. +In that case you can either disable the automatic instrumentation using xref:reference:actuator/observability.adoc#actuator.observability.preventing-observations[properties] or an javadoc:io.micrometer.observation.ObservationPredicate[] and rely on your annotations, or you can remove your annotation.