Add Micrometer Observability documentation

Closes gh-32833
Closes gh-32912

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[]

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 <<actuator#actuator.endpoints.exposing,exposing endpoints>> for more details.
+The endpoint is not available by default and must be exposed.
+See <<actuator#actuator.endpoints.exposing,exposing endpoints>> 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.

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.

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.