Add observation documentation generation

Author: acogoluegnes

generate-observation-documentation.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+./mvnw -q -P '!setup-test-cluster' test-compile exec:java \
+  -Dexec.mainClass=io.micrometer.docs.DocsGeneratorCommand \
+  -Dexec.classpathScope="test" \
+  -Dexec.args='src/main/java/com/rabbitmq/client/observation/micrometer .* target/micrometer-observation-docs'

src/main/java/com/rabbitmq/client/observation/micrometer/DefaultDeliverObservationConvention.java

@@ -25,22 +25,14 @@
  * @since 5.19.0
  * @see DeliverObservationConvention
  */
-public class DefaultDeliverObservationConvention implements DeliverObservationConvention {
+abstract class DefaultDeliverObservationConvention implements DeliverObservationConvention {
 
-  private final String name;
   private final String operation;
 
-  public DefaultDeliverObservationConvention(String name, String operation) {
-    this.name = name;
+  public DefaultDeliverObservationConvention(String operation) {
     this.operation = operation;
   }
 
-  // TODO: If the name is not fixed we won't be able to parse it to automatically document the name
-  @Override
-  public String getName() {
-    return name;
-  }
-
   @Override
   public String getContextualName(DeliverContext context) {
     return source(context.getQueue()) + " " + operation;

src/main/java/com/rabbitmq/client/observation/micrometer/DefaultProcessObservationConvention.java

@@ -0,0 +1,27 @@
+// Copyright (c) 2023 VMware, Inc. or its affiliates.  All rights reserved.
+//
+// This software, the RabbitMQ Java client library, is triple-licensed under the
+// Mozilla Public License 2.0 ("MPL"), the GNU General Public License version 2
+// ("GPL") and the Apache License version 2 ("ASL"). For the MPL, please see
+// LICENSE-MPL-RabbitMQ. For the GPL, please see LICENSE-GPL2.  For the ASL,
+// please see LICENSE-APACHE2.
+//
+// This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND,
+// either express or implied. See the LICENSE file for specific language governing
+// rights and limitations of this software.
+//
+// If you have any questions regarding licensing, please contact us at
+// [email protected].
+package com.rabbitmq.client.observation.micrometer;
+
+public class DefaultProcessObservationConvention extends DefaultDeliverObservationConvention {
+
+  public DefaultProcessObservationConvention(String operation) {
+    super(operation);
+  }
+
+  @Override
+  public String getName() {
+    return "rabbitmq.process";
+  }
+}

src/main/java/com/rabbitmq/client/observation/micrometer/DefaultReceiveObservationConvention.java

@@ -0,0 +1,27 @@
+// Copyright (c) 2023 VMware, Inc. or its affiliates.  All rights reserved.
+//
+// This software, the RabbitMQ Java client library, is triple-licensed under the
+// Mozilla Public License 2.0 ("MPL"), the GNU General Public License version 2
+// ("GPL") and the Apache License version 2 ("ASL"). For the MPL, please see
+// LICENSE-MPL-RabbitMQ. For the GPL, please see LICENSE-GPL2.  For the ASL,
+// please see LICENSE-APACHE2.
+//
+// This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND,
+// either express or implied. See the LICENSE file for specific language governing
+// rights and limitations of this software.
+//
+// If you have any questions regarding licensing, please contact us at
+// [email protected].
+package com.rabbitmq.client.observation.micrometer;
+
+public class DefaultReceiveObservationConvention extends DefaultDeliverObservationConvention {
+
+  public DefaultReceiveObservationConvention(String operation) {
+    super(operation);
+  }
+
+  @Override
+  public String getName() {
+    return "rabbitmq.receive";
+  }
+}

src/main/java/com/rabbitmq/client/observation/micrometer/MicrometerObservationCollectorBuilder.java

@@ -31,10 +31,10 @@ public class MicrometerObservationCollectorBuilder {
       new DefaultPublishObservationConvention();
   private DeliverObservationConvention customProcessObservationConvention;
   private DeliverObservationConvention defaultProcessObservationConvention =
-      new DefaultDeliverObservationConvention("rabbitmq.process", "process");
+      new DefaultProcessObservationConvention("process");
   private DeliverObservationConvention customReceiveObservationConvention;
   private DeliverObservationConvention defaultReceiveObservationConvention =
-      new DefaultDeliverObservationConvention("rabbitmq.receive", "receive");
+      new DefaultReceiveObservationConvention("receive");
 
   public MicrometerObservationCollectorBuilder registry(ObservationRegistry registry) {
     this.registry = registry;

src/main/java/com/rabbitmq/client/observation/micrometer/RabbitMqObservationDocumentation.java

@@ -25,6 +25,7 @@
  * @since 5.19.0
  */
 public enum RabbitMqObservationDocumentation implements ObservationDocumentation {
+  /** Observation for publishing a message. */
   PUBLISH_OBSERVATION {
 
     @Override
@@ -39,12 +40,13 @@ public KeyName[] getLowCardinalityKeyNames() {
     }
   },
 
+  /** Observation for processing a message. */
   PROCESS_OBSERVATION {
 
     @Override
     public Class<? extends ObservationConvention<? extends Observation.Context>>
         getDefaultConvention() {
-      return DefaultDeliverObservationConvention.class;
+      return DefaultProcessObservationConvention.class;
     }
 
     @Override
@@ -53,12 +55,13 @@ public KeyName[] getLowCardinalityKeyNames() {
     }
   },
 
+  /** Observation for polling for a message with <code>basic.get</code>. */
   RECEIVE_OBSERVATION {
 
     @Override
     public Class<? extends ObservationConvention<? extends Observation.Context>>
         getDefaultConvention() {
-      return DefaultDeliverObservationConvention.class;
+      return DefaultReceiveObservationConvention.class;
     }
 
     @Override
@@ -67,37 +70,6 @@ public KeyName[] getLowCardinalityKeyNames() {
     }
   };
 
-  // SPAN NAME
-  // <destination name> <operation name>
-  // topic with spaces process
-  // (anonymous) publish ((anonymous) being a stable identifier for an unnamed destination)
-  // (anonymous) receive ((anonymous) being a stable identifier for an unnamed destination)
-
-  // LOW CARDINALITY
-  // messaging.system = rabbitmq
-  // messaging.operation = publish
-
-  // HIGH CARDINALITY
-
-  // messaging.rabbitmq.destination.routing_key
-  // messaging.destination.anonymous
-  // messaging.destination.name
-  // messaging.destination.template
-  // messaging.destination.temporary
-  // messaging.batch.message_count
-  // messaging.message.conversation_id
-  // messaging.message.id
-  // messaging.message.payload_compressed_size_bytes
-  // messaging.message.payload_size_bytes
-
-  // net.peer.name
-  // net.protocol.name
-  // net.protocol.version
-  // net.sock.family
-  // net.sock.peer.addr
-  // net.sock.peer.name
-  // net.sock.peer.port
-
   /** Low cardinality tags. */
   public enum LowCardinalityTags implements KeyName {
 
@@ -119,6 +91,7 @@ public String asString() {
       }
     },
 
+    /** A string identifying the protocol (AMQP). */
     NET_PROTOCOL_NAME {
 
       @Override
@@ -127,6 +100,7 @@ public String asString() {
       }
     },
 
+    /** A string identifying the protocol version (0.9.1). */
     NET_PROTOCOL_VERSION {
 
       @Override