Add Micrometer Observation generated documentation

References #379

Author: acogoluegnes

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

@@ -2,8 +2,13 @@
 
 . $(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/stream/observation/micrometer .* target/micrometer-observation-docs'
+
 MESSAGE=$(git log -1 --pretty=%B)
-./mvnw clean buildnumber:create pre-site --no-transfer-progress
+./mvnw buildnumber:create pre-site --no-transfer-progress
 
 ./mvnw javadoc:javadoc -Dmaven.javadoc.skip=false --no-transfer-progress
 

pom.xml

@@ -75,6 +75,7 @@
     <vavr.version>0.10.4</vavr.version>
     <paho.version>1.2.5</paho.version>
     <micrometer-tracing-test.version>1.1.3</micrometer-tracing-test.version>
+    <micrometer-docs-generator.version>1.0.2</micrometer-docs-generator.version>
     <maven.compiler.plugin.version>3.11.0</maven.compiler.plugin.version>
     <maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
     <spring-boot-maven-plugin.version>2.7.6</spring-boot-maven-plugin.version>
@@ -320,6 +321,13 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>io.micrometer</groupId>
+      <artifactId>micrometer-docs-generator</artifactId>
+      <version>${micrometer-docs-generator.version}</version>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>org.openjdk.jmh</groupId>
       <artifactId>jmh-core</artifactId>
@@ -468,6 +476,7 @@
             <idseparator>-</idseparator>
             <source-highlighter>coderay</source-highlighter>
             <test-examples>../../test/java/com/rabbitmq/stream/docs</test-examples>
+            <build-directory>${project.build.directory}</build-directory>
           </attributes>
 
         </configuration>

src/docs/asciidoc/appendixes.adoc

@@ -0,0 +1,24 @@
+ifndef::build-directory[:build-directory: ../../../target]
+:test-examples: ../../test/java/com/rabbitmq/stream/docs
+
+[appendix]
+== Micrometer Observation
+
+It is possible to use https://micrometer.io/docs/observation[Micrometer Observation] to instrument publishing and consuming in the stream 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 following snippet shows how to create and set up the Micrometer `ObservationCollector` from an existing `ObservationRegistry`:
+
+.Configuring Micrometer Observation
+[source,java,indent=0]
+--------
+include::{test-examples}/EnvironmentUsage.java[tag=micrometer-observation]
+--------
+<1> Create the Micrometer `ObservationCollector`
+
+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

@@ -1,6 +1,7 @@
 = RabbitMQ Stream Java Client
 :revnumber: {project-version}
 :revremark: ({build-number})
+:appendix-caption: Appendix
 ifndef::imagesdir[:imagesdir: images]
 ifndef::sourcedir[:sourcedir: ../../main/java]
 :source-highlighter: prettify
@@ -28,4 +29,6 @@ include::advanced-topics.adoc[]
 
 include::building.adoc[]
 
-include::performance-tool.adoc[]
+include::performance-tool.adoc[]
+
+include::appendixes.adoc[]

src/main/java/com/rabbitmq/stream/observation/micrometer/StreamObservationDocumentation.java

@@ -76,7 +76,7 @@ public String asString() {
       }
     },
 
-    /** A string identifying the protocol (AMQP). */
+    /** A string identifying the protocol (RabbitMQ Stream). */
     NET_PROTOCOL_NAME {
 
       @Override
@@ -85,7 +85,7 @@ public String asString() {
       }
     },
 
-    /** A string identifying the protocol version (0.9.1). */
+    /** A string identifying the protocol version (1.0). */
     NET_PROTOCOL_VERSION {
 
       @Override

src/test/java/com/rabbitmq/stream/docs/EnvironmentUsage.java

@@ -14,12 +14,10 @@
 
 package com.rabbitmq.stream.docs;
 
-import com.rabbitmq.stream.Address;
-import com.rabbitmq.stream.ByteCapacity;
-import com.rabbitmq.stream.Environment;
+import com.rabbitmq.stream.*;
 
-import com.rabbitmq.stream.EnvironmentBuilder;
-import io.netty.channel.Channel;
+import com.rabbitmq.stream.observation.micrometer.MicrometerObservationCollectorBuilder;
+import io.micrometer.observation.ObservationRegistry;
 import io.netty.channel.EventLoopGroup;
 import io.netty.channel.epoll.EpollEventLoopGroup;
 import io.netty.channel.epoll.EpollSocketChannel;
@@ -30,8 +28,6 @@
 import java.security.cert.X509Certificate;
 import java.time.Duration;
 import java.util.Arrays;
-import java.util.Set;
-import java.util.concurrent.ConcurrentHashMap;
 
 public class EnvironmentUsage {
 
@@ -153,4 +149,14 @@ void nativeEpoll() {
         // end::native-epoll[]
     }
 
+    void micrometerObservation() {
+        ObservationRegistry observationRegistry = ObservationRegistry.NOOP;
+        // tag::micrometer-observation[]
+        Environment environment = Environment.builder()
+            .observationCollector(new MicrometerObservationCollectorBuilder()  // <1>
+                .registry(observationRegistry).build())  // <1>
+            .build();
+        // end::micrometer-observation[]
+    }
+
 }