From af1358b7e29d15257cff835c25ee3b38382c3c9b Mon Sep 17 00:00:00 2001
From: Mayur Kale <mayurkale@google.com>
Date: Thu, 18 Oct 2018 16:36:55 -0700
Subject: Gauge API : Add support for DerivedDoubleGauge (#1504)

* Add support for DerivedDoubleGauge

* Fix review comments

* Fix reviews
---
 .../io/opencensus/common/ToDoubleFunction.java     |   8 +-
 .../io/opencensus/metrics/DerivedDoubleGauge.java  | 153 +++++++++++++++++++++
 .../io/opencensus/metrics/DerivedLongGauge.java    |   6 +-
 3 files changed, 162 insertions(+), 5 deletions(-)
 create mode 100644 api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java

(limited to 'api/src/main/java/io/opencensus')

diff --git a/api/src/main/java/io/opencensus/common/ToDoubleFunction.java b/api/src/main/java/io/opencensus/common/ToDoubleFunction.java
index eac85793..6ace2f7c 100644
--- a/api/src/main/java/io/opencensus/common/ToDoubleFunction.java
+++ b/api/src/main/java/io/opencensus/common/ToDoubleFunction.java
@@ -16,6 +16,10 @@
 
 package io.opencensus.common;
 
+/*>>>
+import org.checkerframework.checker.nullness.qual.Nullable;
+*/
+
 /**
  * Represents a function that produces a double-valued result. See {@link
  * io.opencensus.metrics.MetricRegistry} for an example of its use.
@@ -25,7 +29,7 @@ package io.opencensus.common;
  *
  * @since 0.16
  */
-public interface ToDoubleFunction<T> {
+public interface ToDoubleFunction</*@Nullable*/ T> {
 
   /**
    * Applies this function to the given argument.
@@ -33,5 +37,5 @@ public interface ToDoubleFunction<T> {
    * @param value the function argument.
    * @return the function result.
    */
-  double applyAsDouble(T value);
+  double applyAsDouble(/*@Nullable*/ T value);
 }
diff --git a/api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java b/api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java
new file mode 100644
index 00000000..10119eef
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java
@@ -0,0 +1,153 @@
+/*
+ * Copyright 2018, OpenCensus Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.opencensus.metrics;
+
+import io.opencensus.common.ToDoubleFunction;
+import io.opencensus.internal.Utils;
+import java.lang.ref.WeakReference;
+import java.util.List;
+import javax.annotation.concurrent.ThreadSafe;
+
+/*>>>
+import org.checkerframework.checker.nullness.qual.Nullable;
+*/
+
+/**
+ * Derived Double Gauge metric, to report instantaneous measurement of a double value. Gauges can go
+ * both up and down. The gauges values can be negative.
+ *
+ * <p>Example: Create a Gauge with an object and a callback function.
+ *
+ * <pre>{@code
+ * class YourClass {
+ *
+ *   private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ *   List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ *   List<LabelValue> labelValues = Arrays.asList(LabelValue.create("Inbound"));
+ *
+ *   // TODO(mayurkale): Plugs-in the DerivedDoubleGauge into the registry.
+ *   DerivedDoubleGauge gauge = metricRegistry.addDerivedDoubleGauge(
+ *       "queue_size", "Pending jobs in a queue", "1", labelKeys);
+ *
+ *   QueueManager queueManager = new QueueManager();
+ *   gauge.createTimeSeries(labelValues, queueManager,
+ *         new ToDoubleFunction<QueueManager>() {
+ *           {@literal @}Override
+ *           public double applyAsDouble(QueueManager queue) {
+ *             return queue.size();
+ *           }
+ *         });
+ *
+ *   void doWork() {
+ *      // Your code here.
+ *   }
+ * }
+ *
+ * }</pre>
+ *
+ * @since 0.17
+ */
+@ThreadSafe
+public abstract class DerivedDoubleGauge {
+  /**
+   * Creates a {@code TimeSeries}. The value of a single point in the TimeSeries is observed from a
+   * callback function. This function is invoked whenever metrics are collected, meaning the
+   * reported value is up-to-date. It keeps a {@link WeakReference} to the object and it is the
+   * user's responsibility to manage the lifetime of the object.
+   *
+   * @param labelValues the list of label values.
+   * @param obj the state object from which the function derives a measurement.
+   * @param function the function to be called.
+   * @param <T> the type of the object upon which the function derives a measurement.
+   * @throws NullPointerException if {@code labelValues} is null OR any element of {@code
+   *     labelValues} is null OR {@code function} is null.
+   * @throws IllegalArgumentException if different time series with the same labels already exists
+   *     OR if number of {@code labelValues}s are not equal to the label keys.
+   * @since 0.17
+   */
+  public abstract <T> void createTimeSeries(
+      List<LabelValue> labelValues,
+      /*@Nullable*/ T obj,
+      ToDoubleFunction</*@Nullable*/ T> function);
+
+  /**
+   * Removes the {@code TimeSeries} from the gauge metric, if it is present.
+   *
+   * @param labelValues the list of label values.
+   * @throws NullPointerException if {@code labelValues} is null.
+   * @since 0.17
+   */
+  public abstract void removeTimeSeries(List<LabelValue> labelValues);
+
+  /**
+   * Removes all {@code TimeSeries} from the gauge metric.
+   *
+   * @since 0.17
+   */
+  public abstract void clear();
+
+  /**
+   * Returns the no-op implementation of the {@code DerivedDoubleGauge}.
+   *
+   * @return the no-op implementation of the {@code DerivedDoubleGauge}.
+   * @since 0.17
+   */
+  static DerivedDoubleGauge newNoopDerivedDoubleGauge(
+      String name, String description, String unit, List<LabelKey> labelKeys) {
+    return NoopDerivedDoubleGauge.create(name, description, unit, labelKeys);
+  }
+
+  /** No-op implementations of DerivedDoubleGauge class. */
+  private static final class NoopDerivedDoubleGauge extends DerivedDoubleGauge {
+    private final int labelKeysSize;
+
+    static NoopDerivedDoubleGauge create(
+        String name, String description, String unit, List<LabelKey> labelKeys) {
+      return new NoopDerivedDoubleGauge(name, description, unit, labelKeys);
+    }
+
+    /** Creates a new {@code NoopDerivedDoubleGauge}. */
+    NoopDerivedDoubleGauge(String name, String description, String unit, List<LabelKey> labelKeys) {
+      Utils.checkNotNull(name, "name");
+      Utils.checkNotNull(description, "description");
+      Utils.checkNotNull(unit, "unit");
+      Utils.checkListElementNotNull(
+          Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null.");
+      labelKeysSize = labelKeys.size();
+    }
+
+    @Override
+    public <T> void createTimeSeries(
+        List<LabelValue> labelValues,
+        /*@Nullable*/ T obj,
+        ToDoubleFunction</*@Nullable*/ T> function) {
+      Utils.checkListElementNotNull(
+          Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null.");
+      Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels.");
+      Utils.checkNotNull(function, "function");
+    }
+
+    @Override
+    public void removeTimeSeries(List<LabelValue> labelValues) {
+      Utils.checkNotNull(labelValues, "labelValues");
+    }
+
+    @Override
+    public void clear() {}
+  }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java b/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java
index 8fdd800d..43943fa6 100644
--- a/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java
+++ b/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java
@@ -30,7 +30,7 @@ import org.checkerframework.checker.nullness.qual.Nullable;
  * Derived Long Gauge metric, to report instantaneous measurement of an int64 value. Gauges can go
  * both up and down. The gauges values can be negative.
  *
- * <p>Example: Create a Gauge with object and function.
+ * <p>Example: Create a Gauge with an object and a callback function.
  *
  * <pre>{@code
  * class YourClass {
@@ -131,8 +131,8 @@ public abstract class DerivedLongGauge {
 
     @Override
     public <T> void createTimeSeries(
-        List<LabelValue> labelValues, /*@Nullable*/
-        T obj,
+        List<LabelValue> labelValues,
+        /*@Nullable*/ T obj,
         ToLongFunction</*@Nullable*/ T> function) {
       Utils.checkListElementNotNull(
           Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null.");
-- 
cgit v1.2.3