From 5d1ff17a0a681b1d0677981f4dba297a31969a8c Mon Sep 17 00:00:00 2001 From: Moritz Halbritter Date: Fri, 28 Oct 2022 15:08:35 +0200 Subject: [PATCH] Add Micrometer Observability documentation Closes gh-32833 Closes gh-32912 --- .../src/docs/asciidoc/actuator.adoc | 4 +- .../src/docs/asciidoc/actuator/metrics.adoc | 7 ++- .../docs/asciidoc/actuator/observability.adoc | 23 ++++++++++ .../src/docs/asciidoc/actuator/tracing.adoc | 9 ++-- .../observability/MyCustomObservation.java | 44 +++++++++++++++++++ 5 files changed, 78 insertions(+), 9 deletions(-) create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/observability.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/observability/MyCustomObservation.java diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc index d32bb57246..9bef63c8b6 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator.adoc @@ -9,8 +9,6 @@ Spring Boot includes a number of additional features to help you monitor and man You can choose to manage and monitor your application by using HTTP endpoints or with JMX. Auditing, health, and metrics gathering can also be automatically applied to your application. - - include::actuator/enabling.adoc[] include::actuator/endpoints.adoc[] @@ -19,6 +17,8 @@ include::actuator/monitoring.adoc[] include::actuator/jmx.adoc[] +include::actuator/observability.adoc[] + include::actuator/loggers.adoc[] include::actuator/metrics.adoc[] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/metrics.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/metrics.adoc index 7109bdd2c7..9ee4fb6de7 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/metrics.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/metrics.adoc @@ -1272,7 +1272,8 @@ For more details on the concepts behind `percentiles-histogram`, `percentiles`, [[actuator.metrics.endpoint]] === Metrics Endpoint Spring Boot provides a `metrics` endpoint that you can use diagnostically to examine the metrics collected by an application. -The endpoint is not available by default and must be exposed. See <> for more details. +The endpoint is not available by default and must be exposed. +See <> for more details. Navigating to `/actuator/metrics` displays a list of available meter names. You can drill down to view information about a particular meter by providing its name as a selector -- for example, `/actuator/metrics/jvm.memory.max`. @@ -1291,3 +1292,7 @@ The reported measurements are the _sum_ of the statistics of all meters that mat In the preceding example, the returned `Value` statistic is the sum of the maximum memory footprints of the "`Code Cache`", "`Compressed Class Space`", and "`Metaspace`" areas of the heap. If you wanted to see only the maximum size for the "`Metaspace`", you could add an additional `tag=id:Metaspace` -- that is, `/actuator/metrics/jvm.memory.max?tag=area:nonheap&tag=id:Metaspace`. ==== + +[[actuator.metrics.micrometer-observation]] +=== Integration with Micrometer Observation +A `DefaultMeterObservationHandler` is automatically registered on the `ObservationRegistry`, which creates metrics for every completed observation. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/observability.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/observability.adoc new file mode 100644 index 0000000000..d29197ee9d --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/observability.adoc @@ -0,0 +1,23 @@ +[[actuator.observability]] +== Observability + +Observability is the ability to observe the internal state of a running system from the outside. +It consists of the three pillars logging, metrics and traces. + +For metrics and traces, Spring Boot uses https://micrometer.io/docs/observation[Micrometer Observation]. +To create your own observations (which will lead to metrics and traces), you can inject an `ObservationRegistry`. + +include::code:MyCustomObservation[] + +NOTE: Low cardinality tags will be added to metrics and traces, while high cardinality tags will only be added to traces. + +Beans of type `ObservationPredicate`, `GlobalObservationConvention` and `ObservationHandler` will be automatically registered on the `ObservationRegistry`. +You can additionally register any number of `ObservationRegistryCustomizer` beans to further configure the registry. + +For more details please see the https://micrometer.io/docs/observation[Micrometer Observation documentation]. + +TIP: Observability for JDBC can be configured using the https://github.com/jdbc-observations/datasource-micrometer[Datasource Micrometer project]. +It provides a Spring Boot starter which automatically creates observations when JDBC operations are invoked. +Read more about it https://jdbc-observations.github.io/datasource-micrometer/docs/current/docs/html/[in the reference documentation]. + +The next sections will provide more details about logging, metrics and traces. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc index 7f4509da1f..0ad7801b35 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc @@ -1,7 +1,6 @@ [[actuator.micrometer-tracing]] == Tracing Spring Boot Actuator provides dependency management and auto-configuration for https://micrometer.io/docs/tracing[Micrometer Tracing], a facade for popular tracer libraries. -Micrometer Tracing hooks into Micrometer's `ObservationHandler`, which means a https://micrometer.io/docs/tracing#_glossary[span] is reported for every completed observation. TIP: To learn more about Micrometer Tracing capabilities, see its https://micrometer.io/docs/tracing[reference documentation]. @@ -99,15 +98,16 @@ All tracer implementations need the `org.springframework.boot:spring-boot-starte NOTE: If your project doesn't use Spring MVC or Spring WebFlux, the `io.zipkin.reporter2:zipkin-sender-urlconnection` dependency is needed, too. - - [[actuator.micrometer-tracing.tracer-implementations.brave-wavefront]] ==== OpenZipkin Brave With Wavefront * `io.micrometer:micrometer-tracing-bridge-brave` - which is needed to bridge the Micrometer Observation API to Brave. * `io.micrometer:micrometer-tracing-reporter-wavefront` - which is needed to report traces to Wavefront. +[[actuator.micrometer-tracing.micrometer-observation]] +=== Integration with Micrometer Observation +A `TracingAwareMeterObservationHandler` is automatically registered on the `ObservationRegistry`, which creates spans for every completed observation. [[actuator.micrometer-tracing.creating-spans]] === Creating Custom Spans @@ -117,8 +117,5 @@ For this, inject `ObservationRegistry` into your component: include::code:CustomObservation[] This will create an observation named "some-operation" with the tag "some-tag=some-value". -Completing an observation will create a metric and a span. - -NOTE: Low cardinality tags will be added to metrics and traces, while high cardinality tags will only be added to traces. TIP: If you want to create a span without creating a metric, you need to use the https://micrometer.io/docs/tracing#_using_micrometer_tracing_directly[lower-level `Tracer` API] from Micrometer. diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/observability/MyCustomObservation.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/observability/MyCustomObservation.java new file mode 100644 index 0000000000..fe84dc4c5d --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/observability/MyCustomObservation.java @@ -0,0 +1,44 @@ +/* + * Copyright 2012-2022 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.actuator.observability; + +import io.micrometer.observation.Observation; +import io.micrometer.observation.ObservationRegistry; + +import org.springframework.stereotype.Component; + +@Component +public class MyCustomObservation { + + private final ObservationRegistry observationRegistry; + + public MyCustomObservation(ObservationRegistry observationRegistry) { + this.observationRegistry = observationRegistry; + } + + public void doSomething() { + // @formatter:off + Observation.createNotStarted("doSomething", this.observationRegistry) + .lowCardinalityKeyValue("locale", "en-US") + .highCardinalityKeyValue("userId", "42") + .observe(() -> { + // Execute business logic here + }); + // @formatter:on + } + +}