Add observation Javadoc

Author: acogoluegnes

pom.xml

@@ -401,6 +401,9 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-resources-plugin</artifactId>
         <version>${maven-resources-plugin.version}</version>
+        <configuration>
+          <propertiesEncoding>${project.build.sourceEncoding}</propertiesEncoding>
+        </configuration>
       </plugin>
 
       <plugin>

src/main/java/com/rabbitmq/stream/ObservationCollector.java

@@ -13,6 +13,19 @@
 // [email protected].
 package com.rabbitmq.stream;
 
+/**
+ * API to instrument operations in the stream client. The supported operations are publishing, and
+ * asynchronous delivery.
+ *
+ * <p>Implementations can gather information and send it to tracing backends. This allows e.g.
+ * following the processing steps of a given message through different systems.
+ *
+ * <p>This is considered an SPI and is susceptible to change at any time.
+ *
+ * @since 0.12.0
+ * @see EnvironmentBuilder#observationCollector(ObservationCollector)
+ * @see com.rabbitmq.stream.observation.micrometer.MicrometerObservationCollectorBuilder
+ */
 public interface ObservationCollector<T> {
 
   ObservationCollector<Void> NO_OP =
@@ -31,12 +44,39 @@ public MessageHandler subscribe(MessageHandler handler) {
         }
       };
 
-  void published(T context, Message message);
-
+  /**
+   * Start observation.
+   *
+   * <p>Implementations are expecting to return an observation context that will be passed in to the
+   * {@link #published(Object, Message)} callback.
+   *
+   * @param stream the stream to publish to
+   * @param message the message to publish
+   * @return observation context
+   */
   T prePublish(String stream, Message message);
 
+  /**
+   * Callback when the message is about to be published.
+   *
+   * @param context the observation context
+   * @param message the message to publish
+   */
+  void published(T context, Message message);
+
+  /**
+   * Decorate consumer registration.
+   *
+   * @param handler the original handler
+   * @return a decorated handler
+   */
   MessageHandler subscribe(MessageHandler handler);
 
+  /**
+   * Says whether the implementation does nothing or not.
+   *
+   * @return true if the implementation is a no-op
+   */
   default boolean isNoop() {
     return this == NO_OP;
   }

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

@@ -18,6 +18,11 @@
 import com.rabbitmq.stream.observation.micrometer.StreamObservationDocumentation.LowCardinalityTags;
 import io.micrometer.common.KeyValues;
 
+/**
+ * Default {@link ProcessObservationConvention}.
+ *
+ * @since 0.12.0
+ */
 public class DefaultProcessObservationConvention implements ProcessObservationConvention {
 
   private static final String OPERATION = "process";

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

@@ -18,6 +18,11 @@
 import com.rabbitmq.stream.observation.micrometer.StreamObservationDocumentation.LowCardinalityTags;
 import io.micrometer.common.KeyValues;
 
+/**
+ * Default {@link PublishObservationConvention}.
+ *
+ * @since 0.12.0
+ */
 public class DefaultPublishObservationConvention implements PublishObservationConvention {
 
   private static final String OPERATION = "publish";

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

@@ -16,14 +16,24 @@
 import com.rabbitmq.stream.*;
 import io.micrometer.observation.Observation;
 import io.micrometer.observation.ObservationRegistry;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
+/**
+ * Micrometer's {@link ObservationCollector}.
+ *
+ * @since 0.12.0
+ */
 class MicrometerObservationCollector implements ObservationCollector<Observation> {
 
+  private static final Logger LOGGER =
+      LoggerFactory.getLogger(MicrometerObservationCollector.class);
+
   private final ObservationRegistry registry;
   private final PublishObservationConvention customPublishConvention, defaultPublishConvention;
   private final ProcessObservationConvention customProcessConvention, defaultProcessConvention;
 
-  public MicrometerObservationCollector(
+  MicrometerObservationCollector(
       ObservationRegistry registry,
       PublishObservationConvention customPublishConvention,
       PublishObservationConvention defaultPublishConvention,
@@ -41,7 +51,7 @@ public void published(Observation observation, Message message) {
     try {
       observation.stop();
     } catch (Exception e) {
-      // TODO log error
+      LOGGER.warn("Error while stopping Micrometer observation: {}", e.getMessage());
     }
   }
 

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

@@ -14,53 +14,126 @@
 package com.rabbitmq.stream.observation.micrometer;
 
 import com.rabbitmq.stream.ObservationCollector;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
 import io.micrometer.observation.ObservationRegistry;
+import java.util.function.Supplier;
 
+/**
+ * Builder to configure and create <a href="https://micrometer.io/docs/observation">Micrometer
+ * Observation</a> implementation of {@link ObservationCollector}.
+ *
+ * @since 0.12.0
+ */
 public class MicrometerObservationCollectorBuilder {
 
   private ObservationRegistry registry = ObservationRegistry.NOOP;
-  private PublishObservationConvention customPublishConvention;
-  private PublishObservationConvention defaultPublishConvention =
+  private PublishObservationConvention customPublishObservationConvention;
+  private PublishObservationConvention defaultPublishObservationConvention =
       new DefaultPublishObservationConvention();
-  private ProcessObservationConvention customProcessConvention;
-  private ProcessObservationConvention defaultProcessConvention =
+  private ProcessObservationConvention customProcessObservationConvention;
+  private ProcessObservationConvention defaultProcessObservationConvention =
       new DefaultProcessObservationConvention();
 
+  /**
+   * Set the {@link ObservationRegistry} to use.
+   *
+   * <p>Default is {@link ObservationRegistry#NOOP}.
+   *
+   * @param registry the registry
+   * @return this builder instance
+   */
   public MicrometerObservationCollectorBuilder registry(ObservationRegistry registry) {
     this.registry = registry;
     return this;
   }
 
-  public MicrometerObservationCollectorBuilder customPublishConvention(
-      PublishObservationConvention customPublishConvention) {
-    this.customPublishConvention = customPublishConvention;
+  /**
+   * Custom convention for publishing.
+   *
+   * <p>If not null, it will override any pre-configured conventions.
+   *
+   * <p>Default is <code>null</code>.
+   *
+   * @param customPublishObservationConvention the convention
+   * @return this builder instance
+   * @see io.micrometer.observation.docs.ObservationDocumentation#observation(ObservationConvention,
+   *     ObservationConvention, Supplier, ObservationRegistry)
+   */
+  public MicrometerObservationCollectorBuilder customPublishObservationConvention(
+      PublishObservationConvention customPublishObservationConvention) {
+    this.customPublishObservationConvention = customPublishObservationConvention;
     return this;
   }
 
-  public MicrometerObservationCollectorBuilder defaultPublishConvention(
-      PublishObservationConvention defaultPublishConvention) {
-    this.defaultPublishConvention = defaultPublishConvention;
+  /**
+   * Default convention for publishing.
+   *
+   * <p>It will be picked if there was neither custom convention nor a pre-configured one via {@link
+   * ObservationRegistry}.
+   *
+   * <p>Default is {@link DefaultPublishObservationConvention}.
+   *
+   * @param defaultPublishObservationConvention the convention
+   * @return this builder instance
+   * @see io.micrometer.observation.docs.ObservationDocumentation#observation(ObservationConvention,
+   *     ObservationConvention, Supplier, ObservationRegistry)
+   */
+  public MicrometerObservationCollectorBuilder defaultPublishObservationConvention(
+      PublishObservationConvention defaultPublishObservationConvention) {
+    this.defaultPublishObservationConvention = defaultPublishObservationConvention;
     return this;
   }
 
-  public MicrometerObservationCollectorBuilder customProcessConvention(
-      ProcessObservationConvention customProcessConvention) {
-    this.customProcessConvention = customProcessConvention;
+  /**
+   * Custom convention for consuming.
+   *
+   * <p>If not null, it will override any pre-configured conventions.
+   *
+   * <p>Default is <code>null</code>.
+   *
+   * @param customProcessObservationConvention the convention
+   * @return this builder instance
+   * @see io.micrometer.observation.docs.ObservationDocumentation#observation(ObservationConvention,
+   *     ObservationConvention, Supplier, ObservationRegistry)
+   */
+  public MicrometerObservationCollectorBuilder customProcessObservationConvention(
+      ProcessObservationConvention customProcessObservationConvention) {
+    this.customProcessObservationConvention = customProcessObservationConvention;
     return this;
   }
 
-  public MicrometerObservationCollectorBuilder defaultProcessConvention(
-      ProcessObservationConvention defaultProcessConvention) {
-    this.defaultProcessConvention = defaultProcessConvention;
+  /**
+   * Default convention for consuming.
+   *
+   * <p>It will be picked if there was neither custom convention nor a pre-configured one via {@link
+   * ObservationRegistry}.
+   *
+   * <p>Default is {@link DefaultProcessObservationConvention}.
+   *
+   * @param defaultProcessObservationConvention the convention
+   * @return this builder instance
+   * @see io.micrometer.observation.docs.ObservationDocumentation#observation(ObservationConvention,
+   *     ObservationConvention, Supplier, ObservationRegistry)
+   * @since 0.12.0
+   */
+  public MicrometerObservationCollectorBuilder defaultProcessObservationConvention(
+      ProcessObservationConvention defaultProcessObservationConvention) {
+    this.defaultProcessObservationConvention = defaultProcessObservationConvention;
     return this;
   }
 
-  public ObservationCollector build() {
+  /**
+   * Create the Micrometer {@link ObservationCollector}.
+   *
+   * @return the Micrometer observation collector
+   */
+  public ObservationCollector<Observation> build() {
     return new MicrometerObservationCollector(
         this.registry,
-        this.customPublishConvention,
-        this.defaultPublishConvention,
-        this.customProcessConvention,
-        this.defaultProcessConvention);
+        this.customPublishObservationConvention,
+        this.defaultPublishObservationConvention,
+        this.customProcessObservationConvention,
+        this.defaultProcessObservationConvention);
   }
 }

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

@@ -17,6 +17,11 @@
 import io.micrometer.observation.transport.ReceiverContext;
 import java.util.Map;
 
+/**
+ * {@link io.micrometer.observation.Observation.Context} for RabbitMQ Stream consuming.
+ *
+ * @since 0.12.0
+ */
 public class ProcessContext extends ReceiverContext<Message> {
 
   private final String stream;

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

@@ -16,6 +16,11 @@
 import io.micrometer.observation.Observation;
 import io.micrometer.observation.ObservationConvention;
 
+/**
+ * {@link ObservationConvention} for RabbitMQ Stream consuming.
+ *
+ * @since 0.12.0
+ */
 public interface ProcessObservationConvention extends ObservationConvention<ProcessContext> {
 
   @Override

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

@@ -16,9 +16,13 @@
 import com.rabbitmq.stream.Message;
 import io.micrometer.observation.transport.SenderContext;
 
+/**
+ * {@link io.micrometer.observation.Observation.Context} for RabbitMQ Stream publishing.
+ *
+ * @since 0.12.0
+ */
 public class PublishContext extends SenderContext<Message> {
 
-  // TODO need payload size
   private final String stream;
   private final int payloadSizeBytes;
 

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

@@ -16,6 +16,11 @@
 import io.micrometer.observation.Observation;
 import io.micrometer.observation.ObservationConvention;
 
+/**
+ * {@link ObservationConvention} for RabbitMQ Stream consuming.
+ *
+ * @since 0.12.0
+ */
 public interface PublishObservationConvention extends ObservationConvention<PublishContext> {
 
   @Override