Generate documentation with Micrometer observation

Author: acogoluegnes

ci/publish-documentation-to-github-pages.sh

@@ -2,6 +2,11 @@
 
 . $(pwd)/release-versions.txt
 
+./mvnw clean test-compile exec:java \
+  -Dexec.mainClass=io.micrometer.docs.DocsGeneratorCommand \
+  -Dexec.classpathScope="test" \
+  -Dexec.args='src/main/java/com/rabbitmq/model/observation/micrometer .* target/micrometer-observation-docs'
+
 MESSAGE=$(git log -1 --pretty=%B)
 ./mvnw buildnumber:create pre-site --no-transfer-progress
 

pom.xml

@@ -51,6 +51,7 @@
         <mockito.version>5.12.0</mockito.version>
         <amqp-client.version>5.20.0</amqp-client.version>
         <micrometer-tracing-test.version>1.3.0</micrometer-tracing-test.version>
+        <micrometer-docs-generator.version>1.0.2</micrometer-docs-generator.version>
         <maven.compiler.plugin.version>3.13.0</maven.compiler.plugin.version>
         <maven-surefire-plugin.version>3.2.5</maven-surefire-plugin.version>
         <maven-resources-plugin.version>3.3.1</maven-resources-plugin.version>
@@ -175,6 +176,13 @@
             <optional>true</optional>
         </dependency>
 
+        <dependency>
+            <groupId>io.micrometer</groupId>
+            <artifactId>micrometer-docs-generator</artifactId>
+            <version>${micrometer-docs-generator.version}</version>
+            <scope>test</scope>
+        </dependency>
+
         <dependency>
             <groupId>com.github.spotbugs</groupId>
             <artifactId>spotbugs-annotations</artifactId>

src/docs/asciidoc/appendixes.adoc

@@ -0,0 +1,26 @@
+ifndef::build-directory[:build-directory: ../../../target]
+:test-examples: ../../test/java/com/rabbitmq/model/docs
+
+[appendix]
+== Micrometer Observation
+
+It is possible to use https://micrometer.io/docs/observation[Micrometer Observation] to instrument publishing and consuming in the AMQP Java client.
+Micrometer Observation provides https://spring.io/blog/2022/10/12/observability-with-spring-boot-3[metrics, tracing, and log correlation with one single API].
+
+The AMQP Java client provides an `ObservationCollector` abstraction and an implementation for Micrometer Observation.
+The following snippet shows how to create and set up the Micrometer `ObservationCollector` implementation with an existing `ObservationRegistry`:
+
+.Configuring Micrometer Observation
+[source,java,indent=0]
+--------
+include::{test-examples}/Api.java[tag=micrometer-observation]
+--------
+<1> Configure Micrometer `ObservationCollector` with builder
+<2> Set Micrometer `ObservationRegistry`
+
+The next sections document the conventions, spans, and metrics made available by the instrumentation.
+They are automatically generated from the source code with the https://github.com/micrometer-metrics/micrometer-docs-generator[Micrometer documentation generator].
+
+include::{build-directory}/micrometer-observation-docs/_conventions.adoc[]
+include::{build-directory}/micrometer-observation-docs/_spans.adoc[]
+include::{build-directory}/micrometer-observation-docs/_metrics.adoc[]

src/docs/asciidoc/index.adoc

@@ -12,3 +12,5 @@ ifndef::sourcedir[:sourcedir: ../../main/java]
 The library is open source, developed https://github.com/rabbitmq-pro/rabbitmq-java-model/[on GitHub], and is licensed under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache Public License 2.0]
 
 include::usage.adoc[]
+
+include::appendixes.adoc[]

src/main/java/com/rabbitmq/model/observation/micrometer/AmqpObservationDocumentation.java

@@ -23,6 +23,7 @@
 import io.micrometer.observation.docs.ObservationDocumentation;
 
 public enum AmqpObservationDocumentation implements ObservationDocumentation {
+  /** Observation for publishing a message. */
   PUBLISH_OBSERVATION {
 
     @Override
@@ -36,6 +37,8 @@ public KeyName[] getLowCardinalityKeyNames() {
       return LowCardinalityTags.values();
     }
   },
+
+  /** Observation for processing a message. */
   PROCESS_OBSERVATION {
 
     @Override

src/test/java/com/rabbitmq/model/docs/Api.java

@@ -21,6 +21,8 @@
 import com.rabbitmq.model.amqp.AmqpEnvironmentBuilder;
 import com.rabbitmq.model.metrics.MetricsCollector;
 import com.rabbitmq.model.metrics.MicrometerMetricsCollector;
+import com.rabbitmq.model.observation.micrometer.MicrometerObservationCollectorBuilder;
+import io.micrometer.observation.ObservationRegistry;
 import io.micrometer.prometheusmetrics.PrometheusConfig;
 import io.micrometer.prometheusmetrics.PrometheusMeterRegistry;
 
@@ -321,5 +323,14 @@ void metricsCollectorMicrometerPrometheus() {
     // end::metrics-micrometer-prometheus[]
   }
 
+  void micrometerObservation() {
+    ObservationRegistry observationRegistry = ObservationRegistry.NOOP;
+    // tag::micrometer-observation[]
+    Environment environment = new AmqpEnvironmentBuilder()
+        .observationCollector(new MicrometerObservationCollectorBuilder()  // <1>
+            .registry(observationRegistry).build())  // <2>
+        .build();
+    // end::micrometer-observation[]
+  }
 
 }