Add documentation for Observability (#3896)

* Add documentation for Observability

* Adapt Observation code to the latest dependencies
* Add doc generation tasks for meters and spans
* Document new Observation API features
* Include generated meters and spans docs to a general `metrics.adoc` chapter

* * Adapt `ObservationPropagationChannelInterceptorTests` for the latest `SpansAssert` API

* * Adjust to the latest Micrometer SNAPSHOT
* Make Observation doc generation tasks only as local.
We don't need ambiguous changes to source code on CI

* * Automate metrics/spans docs generation as a part of `reference` build phase
* Replace 'org.springframework.integration' content in the generated files with a 'o.s.i'
to make it easier to read, especially in the tables
* Break `DefaultMessageReceiverObservationConvention <=> IntegrationObservation` classes tangle
using literal for `KeyValues` in the `DefaultMessageReceiverObservationConvention`
instead of nested enums from the `IntegrationObservation`
* Some other minor build script clean up

* Fix indent in `build.gradle` for `micrometerVersion` property code line

* Add new line after observation section in whats-new.adoc

* * Adapt to the latest Micrometer changes

* * Use Reactor `2022.0.0-SNAPSHOT` version

src/reference/asciidoc/metrics.adoc

@@ -145,6 +145,32 @@ registry.config().meterFilter(MeterFilter.deny(id ->
 ----
 ====
 
+[[micrometer-observation]]
+==== Micrometer Observation
+
+Starting with version 6.0, Spring Integration utilizes a Micrometer Observation abstraction which can handle metrics as well as https://micrometer.io/docs/tracing[tracing] via appropriate `ObservationHandler` configuration.
+
+The observation handling is enabled on the `IntegrationManagement` components whenever an `ObservationRegistry` bean is present in the application context.
+The meters are not gathered in this case independently, but delegated to an appropriate `ObservationHandler` configured on the provided `ObservationRegistry`.
+
+An observation production on the `IntegrationManagement` components can be customized via `ObservationConvention` configuration.
+For example an `AbstractMessageHandler` expects a `MessageReceiverObservationConvention` via its `setObservationConvention()` API.
+
+The following are supported metrics, spans and conventions for Observation API:
+
+include::./generated/metrics.adoc[leveloffset=+2]
+
+include::./generated/spans.adoc[leveloffset=+2]
+
+include::./generated/conventions.adoc[leveloffset=+2]
+
+==== Observation Propagation
+
+To supply a connected chain of spans in one trace, independently of the nature of the messaging flow, Spring Integration provides an `ObservationPropagationChannelInterceptor` implementation.
+This can be configured on `MessageChannnel` beans individually or as a `@GlobalChannelInterceptor` with respective `MessageChannnel` bean names pattern matching.
+The goal of this interceptor is to propagate an `Observation` from the producer thread to the consumer one independently of the `MessageChannnel` implementation and nature.
+A `DirectChannel`, though, is ignored since its consumer is executed directly on the producer thread.
+
 ==== Spring Integration JMX Support
 
 Also see <<./jmx.adoc#jmx,JMX Support>>.

src/reference/asciidoc/whats-new.adoc

@@ -56,6 +56,13 @@ See <<./amqp.adoc#rmq-streams,RabbitMQ Stream Queue Support>> for more informati
 The SFTP modules has been fully reworked from outdated JCraft JSch library to more robust and modern `org.apache.sshd:sshd-sftp` module of the Apache MINA project.
 
 See <<./sftp.adoc#sftp,SFTP Adapters>> for more information.
+
+[[x6.0-micrometer-observation]]
+==== Micrometer Observation
+
+Enabling observation for timers and tracing using Micrometer is now supported.
+See <<./metrics.adoc#micrometer-observation,Micrometer Observation>> for more information.
+
 [[x6.0-general]]
 === General Changes