feat: also add metadata to receivedEvent, javadoc

metacosm · metacosm · commit cb35f81062da · 2022-07-11T12:08:23.000+02:00
diff --git a/micrometer-support/src/main/java/io/javaoperatorsdk/operator/monitoring/micrometer/MicrometerMetrics.java b/micrometer-support/src/main/java/io/javaoperatorsdk/operator/monitoring/micrometer/MicrometerMetrics.java
@@ -30,16 +30,18 @@ public <T> T timeControllerExecution(ControllerExecution<T> execution) {
     final var execName = PREFIX + "controllers.execution." + execution.name();
     final var resourceID = execution.resourceID();
     final var metadata = execution.metadata();
+    final var tags = new ArrayList<String>(metadata.size() + 4);
+    tags.addAll(List.of(
+        "controller", name,
+        "resource.name", resourceID.getName(),
+        "resource.namespace", resourceID.getNamespace().orElse(""),
+        "resource.scope", resourceID.getNamespace().isPresent() ? "namespace" : "cluster"));
+    addReservedMetadataToTags(metadata, tags, "resource.group", Constants.RESOURCE_GROUP_KEY);
+    addReservedMetadataToTags(metadata, tags, "resource.version", Constants.RESOURCE_VERSION_KEY);
+    addReservedMetadataToTags(metadata, tags, "resource.kind", Constants.RESOURCE_KIND_KEY);
     final var timer =
         Timer.builder(execName)
-            .tags(
-                "controller", name,
-                "resource.name", resourceID.getName(),
-                "resource.namespace", resourceID.getNamespace().orElse(""),
-                "resource.scope", resourceID.getNamespace().isPresent() ? "namespace" : "cluster",
-                "resource.group", metadata.get(Constants.RESOURCE_GROUP_KEY).toString(),
-                "resource.version", metadata.get(Constants.RESOURCE_VERSION_KEY).toString(),
-                "resource.kind", metadata.get(Constants.RESOURCE_KIND_KEY).toString())
+            .tags(tags.toArray(new String[0]))
             .publishPercentiles(0.3, 0.5, 0.95)
             .publishPercentileHistogram()
             .register(registry);
@@ -65,9 +67,9 @@ public <T> T timeControllerExecution(ControllerExecution<T> execution) {
     }
   }
 
-  public void receivedEvent(Event event) {
+  public void receivedEvent(Event event, Map<String, Object> metadata) {
     incrementCounter(event.getRelatedCustomResourceID(), "events.received",
-        Collections.emptyMap(),
+        metadata,
         "event", event.getClass().getSimpleName());
   }
 
diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/monitoring/Metrics.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/monitoring/Metrics.java
@@ -3,14 +3,41 @@
 import java.util.Collections;
 import java.util.Map;
 
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.api.reconciler.Context;
 import io.javaoperatorsdk.operator.api.reconciler.RetryInfo;
 import io.javaoperatorsdk.operator.processing.event.Event;
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
 
+/**
+ * An interface that metrics providers can implement and that the SDK will call at different times
+ * of its execution cycle.
+ */
 public interface Metrics {
+
+  /**
+   * The default Metrics provider: a no-operation implementation.
+   */
   Metrics NOOP = new Metrics() {};
 
-  default void receivedEvent(Event event) {}
+  /**
+   * Called when an event has been accepted by the SDK from an event source, which would result in
+   * potentially triggering the associated Reconciler.
+   *
+   * @param event the event
+   * @param metadata metadata associated with the resource being processed
+   * @see io.javaoperatorsdk.operator.api.reconciler.Context#metadataFor(HasMetadata)
+   */
+  default void receivedEvent(Event event, Map<String, Object> metadata) {}
+
+  /**
+   *
+   * @deprecated Use (and implement) {@link #receivedEvent(Event, Map)} instead
+   */
+  @Deprecated
+  default void receivedEvent(Event event) {
+    receivedEvent(event, Collections.emptyMap());
+  }
 
   /**
    *
@@ -22,6 +49,14 @@ default void reconcileCustomResource(ResourceID resourceID, RetryInfo retryInfo)
     reconcileCustomResource(resourceID, retryInfo, Collections.emptyMap());
   }
 
+  /**
+   * Called right before a resource is dispatched to the ExecutorService for reconciliation.
+   *
+   * @param resourceID the {@link ResourceID} associated with the resource
+   * @param retryInfo the current retry state information for the reconciliation request
+   * @param metadata metadata associated with the resource being processed
+   * @see io.javaoperatorsdk.operator.api.reconciler.Context#metadataFor(HasMetadata)
+   */
   default void reconcileCustomResource(ResourceID resourceID, RetryInfo retryInfo,
       Map<String, Object> metadata) {}
 
@@ -35,6 +70,16 @@ default void failedReconciliation(ResourceID resourceID, Exception exception) {
     failedReconciliation(resourceID, exception, Collections.emptyMap());
   }
 
+  /**
+   * Called when a precedent reconciliation for the resource associated with the specified
+   * {@link ResourceID} resulted in the provided exception, resulting in a retry of the
+   * reconciliation.
+   *
+   * @param resourceID the {@link ResourceID} associated with the resource being processed
+   * @param exception the exception that caused the failed reconciliation resulting in a retry
+   * @param metadata metadata associated with the resource being processed
+   * @see io.javaoperatorsdk.operator.api.reconciler.Context#metadataFor(HasMetadata)
+   */
   default void failedReconciliation(ResourceID resourceID, Exception exception,
       Map<String, Object> metadata) {}
 
@@ -47,6 +92,14 @@ default void cleanupDoneFor(ResourceID resourceID) {
     cleanupDoneFor(resourceID, Collections.emptyMap());
   }
 
+  /**
+   * Called when the resource associated with the specified {@link ResourceID} has been successfully
+   * deleted and the clean-up performed by the associated reconciler is finished.
+   *
+   * @param resourceID the {@link ResourceID} associated with the resource being processed
+   * @param metadata metadata associated with the resource being processed
+   * @see io.javaoperatorsdk.operator.api.reconciler.Context#metadataFor(HasMetadata)
+   */
   default void cleanupDoneFor(ResourceID resourceID, Map<String, Object> metadata) {}
 
   /**
@@ -58,27 +111,108 @@ default void finishedReconciliation(ResourceID resourceID) {
     finishedReconciliation(resourceID, Collections.emptyMap());
   }
 
+  /**
+   * Called when the
+   * {@link io.javaoperatorsdk.operator.api.reconciler.Reconciler#reconcile(HasMetadata, Context)}
+   * method of the Reconciler associated with the resource associated with the specified
+   * {@link ResourceID} has sucessfully finished.
+   *
+   * @param resourceID the {@link ResourceID} associated with the resource being processed
+   * @param metadata metadata associated with the resource being processed
+   * @see io.javaoperatorsdk.operator.api.reconciler.Context#metadataFor(HasMetadata)
+   */
   default void finishedReconciliation(ResourceID resourceID, Map<String, Object> metadata) {}
 
-
+  /**
+   * Encapsulates the information about a controller execution i.e. a call to either
+   * {@link io.javaoperatorsdk.operator.api.reconciler.Reconciler#reconcile(HasMetadata, Context)}
+   * or {@link io.javaoperatorsdk.operator.api.reconciler.Cleaner#cleanup(HasMetadata, Context)}.
+   * Note that instances are automatically created for you by the SDK and passed to your Metrics
+   * implementation at the appropriate time to the
+   * {@link #timeControllerExecution(ControllerExecution)} method.
+   *
+   * @param <T> the outcome type associated with the controller execution. Currently, one of
+   *        {@link io.javaoperatorsdk.operator.api.reconciler.UpdateControl} or
+   *        {@link io.javaoperatorsdk.operator.api.reconciler.DeleteControl}
+   */
   interface ControllerExecution<T> {
+
+    /**
+     * Retrieves the name of type of reconciliation being performed: either {@code reconcile} or
+     * {@code cleanup}.
+     *
+     * @return the name of type of reconciliation being performed
+     */
     String name();
 
+    /**
+     * Retrieves the name of the controller executing the reconciliation.
+     *
+     * @return the associated controller name
+     */
     String controllerName();
 
+    /**
+     * Retrieves the name of the successful result when the reconciliation ended positively.
+     * Possible values comes from the different outcomes provided by
+     * {@link io.javaoperatorsdk.operator.api.reconciler.UpdateControl} or
+     * {@link io.javaoperatorsdk.operator.api.reconciler.DeleteControl}.
+     *
+     * @param result the reconciliation result
+     * @return a name associated with the specified outcome
+     */
     String successTypeName(T result);
 
+    /**
+     * Retrieves the {@link ResourceID} of the resource associated with the controller execution
+     * being considered
+     *
+     * @return the {@link ResourceID} of the resource being reconciled
+     */
     ResourceID resourceID();
 
+    /**
+     * Retrieves metadata associated with the current reconciliation, typically additional
+     * information (such as kind) about the resource being reconciled
+     *
+     * @return metadata associated with the current reconciliation
+     */
     Map<String, Object> metadata();
 
+    /**
+     * Performs the controller execution.
+     *
+     * @return the result of the controller execution
+     * @throws Exception if an error occurred during the controller's execution
+     */
     T execute() throws Exception;
   }
 
+  /**
+   * Times the execution of the controller operation encapsulated by the provided
+   * {@link ControllerExecution}.
+   *
+   * @param execution the controller operation to be timed
+   * @return the result of the controller's execution if successful
+   * @param <T> the type of the outcome/result of the controller's execution
+   * @throws Exception if an error occurred during the controller's execution, usually this should
+   *         just be a pass-through of whatever the controller returned
+   */
   default <T> T timeControllerExecution(ControllerExecution<T> execution) throws Exception {
     return execution.execute();
   }
 
+  /**
+   * Monitors the size of the specified map. This currently isn't used directly by the SDK but could
+   * be used by operators to monitor some of their structures, such as cache size.
+   *
+   * @param map the Map which size is to be monitored
+   * @param name the name of the provided Map to be used in metrics data
+   * @return the Map that was passed in so the registration can be done as part of an assignment
+   *         statement.
+   * @param <T> the type of the Map being monitored
+   */
+  @SuppressWarnings("unused")
   default <T extends Map<?, ?>> T monitorSizeOf(T map, String name) {
     return map;
   }
diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DefaultContext.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DefaultContext.java
@@ -1,5 +1,6 @@
 package io.javaoperatorsdk.operator.api.reconciler;
 
+import java.util.Collections;
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
@@ -28,7 +29,7 @@ public DefaultContext(RetryInfo retryInfo, Controller<P> controller, P primaryRe
     this.primaryResource = primaryResource;
     this.controllerConfiguration = controller.getConfiguration();
     this.defaultManagedDependentResourceContext = new DefaultManagedDependentResourceContext();
-    this.metadata = metadata;
+    this.metadata = metadata != null ? metadata : Collections.emptyMap();
   }
 
   @Override
diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventProcessor.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventProcessor.java
@@ -108,7 +108,7 @@ public synchronized void handleEvent(Event event) {
       final var resourceID = event.getRelatedCustomResourceID();
       final var state = resourceStateManager.getOrCreate(event.getRelatedCustomResourceID());
       MDCUtils.addResourceIDInfo(resourceID);
-      metrics.receivedEvent(event);
+      metrics.receivedEvent(event, state.immutableMetadata());
       handleEventMarking(event, state);
       if (!this.running) {
         // events are received and marked, but will be processed when started, see start() method.
