diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0163e3d678..4dd9961515 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
- Support constant labels in Gauge APIs.
- Add an option to allow users to override the default "opencensus_task" metric label in Stackdriver Stats Exporter.
- Allow setting custom namespace in Prometheus exporter.
+- Add Cumulative (`DoubleCumulative`, `LongCumulative`, `DerivedDoubleCumulative`, `DerivedLongCumulative`) APIs.
## 0.20.0 - 2019-03-28
- Add OpenCensus Java OC-Agent Trace Exporter.
diff --git a/api/src/main/java/io/opencensus/metrics/DerivedDoubleCumulative.java b/api/src/main/java/io/opencensus/metrics/DerivedDoubleCumulative.java
new file mode 100644
index 0000000000..68c240eb33
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/DerivedDoubleCumulative.java
@@ -0,0 +1,152 @@
+/*
+ * Copyright 2019, 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 Cumulative metric, to report cumulative measurement of a double value. Cumulative
+ * values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
+ *
+ *
Example: Create a Cumulative with an object and a callback function.
+ *
+ *
+ *
+ * @since 0.21
+ */
+@ThreadSafe
+public abstract class DerivedDoubleCumulative {
+ /**
+ * 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 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.21
+ */
+ public abstract void createTimeSeries(
+ List labelValues,
+ /*@Nullable*/ T obj,
+ ToDoubleFunction function);
+
+ /**
+ * Removes the {@code TimeSeries} from the cumulative metric, if it is present.
+ *
+ * @param labelValues the list of label values.
+ * @throws NullPointerException if {@code labelValues} is null.
+ * @since 0.21
+ */
+ public abstract void removeTimeSeries(List labelValues);
+
+ /**
+ * Removes all {@code TimeSeries} from the cumulative metric.
+ *
+ * @since 0.21
+ */
+ public abstract void clear();
+
+ /**
+ * Returns the no-op implementation of the {@code DerivedDoubleCumulative}.
+ *
+ * @return the no-op implementation of the {@code DerivedDoubleCumulative}.
+ * @since 0.21
+ */
+ static DerivedDoubleCumulative newNoopDerivedDoubleCumulative(
+ String name, String description, String unit, List labelKeys) {
+ return NoopDerivedDoubleCumulative.create(name, description, unit, labelKeys);
+ }
+
+ /** No-op implementations of DerivedDoubleCumulative class. */
+ private static final class NoopDerivedDoubleCumulative extends DerivedDoubleCumulative {
+ private final int labelKeysSize;
+
+ static NoopDerivedDoubleCumulative create(
+ String name, String description, String unit, List labelKeys) {
+ return new NoopDerivedDoubleCumulative(name, description, unit, labelKeys);
+ }
+
+ /** Creates a new {@code NoopDerivedDoubleCumulative}. */
+ NoopDerivedDoubleCumulative(
+ String name, String description, String unit, List labelKeys) {
+ Utils.checkNotNull(name, "name");
+ Utils.checkNotNull(description, "description");
+ Utils.checkNotNull(unit, "unit");
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey");
+ labelKeysSize = labelKeys.size();
+ }
+
+ @Override
+ public void createTimeSeries(
+ List labelValues,
+ /*@Nullable*/ T obj,
+ ToDoubleFunction function) {
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
+ Utils.checkArgument(
+ labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
+ Utils.checkNotNull(function, "function");
+ }
+
+ @Override
+ public void removeTimeSeries(List labelValues) {
+ Utils.checkNotNull(labelValues, "labelValues");
+ }
+
+ @Override
+ public void clear() {}
+ }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/DerivedLongCumulative.java b/api/src/main/java/io/opencensus/metrics/DerivedLongCumulative.java
new file mode 100644
index 0000000000..b1f192f4fc
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/DerivedLongCumulative.java
@@ -0,0 +1,150 @@
+/*
+ * Copyright 2019, 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.ToLongFunction;
+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 Long Cumulative metric, to report cumulative measurement of an int64 value. Cumulative
+ * values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
+ *
+ *
Example: Create a Cumulative with an object and a callback function.
+ *
+ *
{@code
+ * class YourClass {
+ *
+ * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ * List labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ * List labelValues = Arrays.asList(LabelValue.create("Inbound"));
+ *
+ * DerivedLongCumulative cumulative = metricRegistry.addDerivedLongCumulative(
+ * "processed_jobs", "Total processed jobs in a queue", "1", labelKeys);
+ *
+ * QueueManager queueManager = new QueueManager();
+ * cumulative.createTimeSeries(labelValues, queueManager,
+ * new ToLongFunction() {
+ * {@literal @}Override
+ * public long applyAsLong(QueueManager queue) {
+ * return queue.size();
+ * }
+ * });
+ *
+ * void doWork() {
+ * // Your code here.
+ * }
+ * }
+ *
+ * }
+ *
+ * @since 0.21
+ */
+@ThreadSafe
+public abstract class DerivedLongCumulative {
+ /**
+ * 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 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.21
+ */
+ public abstract void createTimeSeries(
+ List labelValues, /*@Nullable*/ T obj, ToLongFunction function);
+
+ /**
+ * Removes the {@code TimeSeries} from the cumulative metric, if it is present.
+ *
+ * @param labelValues the list of label values.
+ * @throws NullPointerException if {@code labelValues} is null.
+ * @since 0.21
+ */
+ public abstract void removeTimeSeries(List labelValues);
+
+ /**
+ * Removes all {@code TimeSeries} from the cumulative metric.
+ *
+ * @since 0.21
+ */
+ public abstract void clear();
+
+ /**
+ * Returns the no-op implementation of the {@code DerivedLongCumulative}.
+ *
+ * @return the no-op implementation of the {@code DerivedLongCumulative}.
+ * @since 0.21
+ */
+ static DerivedLongCumulative newNoopDerivedLongCumulative(
+ String name, String description, String unit, List labelKeys) {
+ return NoopDerivedLongCumulative.create(name, description, unit, labelKeys);
+ }
+
+ /** No-op implementations of DerivedLongCumulative class. */
+ private static final class NoopDerivedLongCumulative extends DerivedLongCumulative {
+ private final int labelKeysSize;
+
+ static NoopDerivedLongCumulative create(
+ String name, String description, String unit, List labelKeys) {
+ return new NoopDerivedLongCumulative(name, description, unit, labelKeys);
+ }
+
+ /** Creates a new {@code NoopDerivedLongCumulative}. */
+ NoopDerivedLongCumulative(
+ String name, String description, String unit, List labelKeys) {
+ Utils.checkNotNull(name, "name");
+ Utils.checkNotNull(description, "description");
+ Utils.checkNotNull(unit, "unit");
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey");
+ labelKeysSize = labelKeys.size();
+ }
+
+ @Override
+ public void createTimeSeries(
+ List labelValues,
+ /*@Nullable*/ T obj,
+ ToLongFunction function) {
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
+ Utils.checkArgument(
+ labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
+ Utils.checkNotNull(function, "function");
+ }
+
+ @Override
+ public void removeTimeSeries(List labelValues) {
+ Utils.checkNotNull(labelValues, "labelValues");
+ }
+
+ @Override
+ public void clear() {}
+ }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/DoubleCumulative.java b/api/src/main/java/io/opencensus/metrics/DoubleCumulative.java
new file mode 100644
index 0000000000..88fe957000
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/DoubleCumulative.java
@@ -0,0 +1,212 @@
+/*
+ * Copyright 2019, 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.internal.Utils;
+import java.util.List;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * Double Cumulative metric, to report instantaneous measurement of a double value. Cumulative
+ * values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
+ *
+ *
Example 1: Create a Cumulative with default labels.
+ *
+ *
{@code
+ * class YourClass {
+ *
+ * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ * List labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ *
+ * DoubleCumulative cumulative = metricRegistry.addDoubleCumulative("processed_jobs",
+ * "Processed jobs", "1", labelKeys);
+ *
+ * // It is recommended to keep a reference of a point for manual operations.
+ * DoublePoint defaultPoint = cumulative.getDefaultTimeSeries();
+ *
+ * void doWork() {
+ * // Your code here.
+ * defaultPoint.add(10);
+ * }
+ *
+ * }
+ * }
+ *
+ *
Example 2: You can also use labels(keys and values) to track different types of metric.
+ *
+ *
{@code
+ * class YourClass {
+ *
+ * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ * List labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ * List labelValues = Arrays.asList(LabelValue.create("Inbound"));
+ *
+ * DoubleCumulative cumulative = metricRegistry.addDoubleCumulative("processed_jobs",
+ * "Processed jobs", "1", labelKeys);
+ *
+ * // It is recommended to keep a reference of a point for manual operations.
+ * DoublePoint inboundPoint = cumulative.getOrCreateTimeSeries(labelValues);
+ *
+ * void doSomeWork() {
+ * // Your code here.
+ * inboundPoint.set(15);
+ * }
+ *
+ * }
+ * }
+ *
+ * @since 0.21
+ */
+@ThreadSafe
+public abstract class DoubleCumulative {
+
+ /**
+ * Creates a {@code TimeSeries} and returns a {@code DoublePoint} if the specified {@code
+ * labelValues} is not already associated with this cumulative, else returns an existing {@code
+ * DoublePoint}.
+ *
+ *
It is recommended to keep a reference to the DoublePoint instead of always calling this
+ * method for manual operations.
+ *
+ * @param labelValues the list of label values. The number of label values must be the same to
+ * that of the label keys passed to {@link MetricRegistry#addDoubleCumulative}.
+ * @return a {@code DoublePoint} the value of single cumulative.
+ * @throws NullPointerException if {@code labelValues} is null OR any element of {@code
+ * labelValues} is null.
+ * @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label
+ * keys.
+ * @since 0.21
+ */
+ public abstract DoublePoint getOrCreateTimeSeries(List labelValues);
+
+ /**
+ * Returns a {@code DoublePoint} for a cumulative with all labels not set, or default labels.
+ *
+ * @return a {@code DoublePoint} for a cumulative with all labels not set, or default labels.
+ * @since 0.21
+ */
+ public abstract DoublePoint getDefaultTimeSeries();
+
+ /**
+ * Removes the {@code TimeSeries} from the cumulative metric, if it is present. i.e. references to
+ * previous {@code DoublePoint} objects are invalid (not part of the metric).
+ *
+ * @param labelValues the list of label values.
+ * @throws NullPointerException if {@code labelValues} is null or any element of {@code
+ * labelValues} is null.
+ * @since 0.21
+ */
+ public abstract void removeTimeSeries(List labelValues);
+
+ /**
+ * Removes all {@code TimeSeries} from the cumulative metric. i.e. references to all previous
+ * {@code DoublePoint} objects are invalid (not part of the metric).
+ *
+ * @since 0.21
+ */
+ public abstract void clear();
+
+ /**
+ * Returns the no-op implementation of the {@code DoubleCumulative}.
+ *
+ * @return the no-op implementation of the {@code DoubleCumulative}.
+ * @since 0.21
+ */
+ static DoubleCumulative newNoopDoubleCumulative(
+ String name, String description, String unit, List labelKeys) {
+ return NoopDoubleCumulative.create(name, description, unit, labelKeys);
+ }
+
+ /**
+ * The value of a single point in the Cumulative.TimeSeries.
+ *
+ * @since 0.21
+ */
+ public abstract static class DoublePoint {
+
+ /**
+ * Adds the given value to the current value. The values cannot be negative.
+ *
+ * @param delta the value to add
+ * @since 0.21
+ */
+ public abstract void add(double delta);
+
+ /**
+ * Sets the given value.
+ *
+ * @param val the new value.
+ * @since 0.21
+ */
+ public abstract void set(double val);
+ }
+
+ /** No-op implementations of DoubleCumulative class. */
+ private static final class NoopDoubleCumulative extends DoubleCumulative {
+ private final int labelKeysSize;
+
+ static NoopDoubleCumulative create(
+ String name, String description, String unit, List labelKeys) {
+ return new NoopDoubleCumulative(name, description, unit, labelKeys);
+ }
+
+ /** Creates a new {@code NoopDoublePoint}. */
+ NoopDoubleCumulative(String name, String description, String unit, List labelKeys) {
+ Utils.checkNotNull(name, "name");
+ Utils.checkNotNull(description, "description");
+ Utils.checkNotNull(unit, "unit");
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey");
+ labelKeysSize = labelKeys.size();
+ }
+
+ @Override
+ public NoopDoublePoint getOrCreateTimeSeries(List labelValues) {
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
+ Utils.checkArgument(
+ labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
+ return NoopDoublePoint.INSTANCE;
+ }
+
+ @Override
+ public NoopDoublePoint getDefaultTimeSeries() {
+ return NoopDoublePoint.INSTANCE;
+ }
+
+ @Override
+ public void removeTimeSeries(List labelValues) {
+ Utils.checkNotNull(labelValues, "labelValues");
+ }
+
+ @Override
+ public void clear() {}
+
+ /** No-op implementations of DoublePoint class. */
+ private static final class NoopDoublePoint extends DoublePoint {
+ private static final NoopDoublePoint INSTANCE = new NoopDoublePoint();
+
+ private NoopDoublePoint() {}
+
+ @Override
+ public void add(double delta) {}
+
+ @Override
+ public void set(double val) {}
+ }
+ }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/LongCumulative.java b/api/src/main/java/io/opencensus/metrics/LongCumulative.java
new file mode 100644
index 0000000000..00402c2d47
--- /dev/null
+++ b/api/src/main/java/io/opencensus/metrics/LongCumulative.java
@@ -0,0 +1,207 @@
+/*
+ * Copyright 2019, 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.internal.Utils;
+import java.util.List;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * Long Cumulative metric, to report instantaneous measurement of an int64 value. Cumulative values
+ * can go up or stay the same, but can never go down. Cumulative values cannot be negative.
+ *
+ *
Example 1: Create a Cumulative with default labels.
+ *
+ *
{@code
+ * class YourClass {
+ *
+ * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ * List labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ *
+ * LongCumulative cumulative = metricRegistry.addLongCumulative(
+ * "processed_jobs", "Processed jobs", "1", labelKeys);
+ *
+ * // It is recommended to keep a reference of a point for manual operations.
+ * LongPoint defaultPoint = cumulative.getDefaultTimeSeries();
+ *
+ * void doWork() {
+ * // Your code here.
+ * defaultPoint.add(10);
+ * }
+ *
+ * }
+ * }
+ *
+ *
Example 2: You can also use labels(keys and values) to track different types of metric.
+ *
+ *
{@code
+ * class YourClass {
+ *
+ * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
+ *
+ * List labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
+ * List labelValues = Arrays.asList(LabelValue.create("Inbound"));
+ *
+ * LongCumulative cumulative = metricRegistry.addLongCumulative(
+ * "processed_jobs", "Processed jobs", "1", labelKeys);
+ *
+ * // It is recommended to keep a reference of a point for manual operations.
+ * LongPoint inboundPoint = cumulative.getOrCreateTimeSeries(labelValues);
+ *
+ * void doSomeWork() {
+ * // Your code here.
+ * inboundPoint.set(15);
+ * }
+ *
+ * }
+ * }
+ *
+ * @since 0.21
+ */
+@ThreadSafe
+public abstract class LongCumulative {
+
+ /**
+ * Creates a {@code TimeSeries} and returns a {@code LongPoint} if the specified {@code
+ * labelValues} is not already associated with this cumulative, else returns an existing {@code
+ * LongPoint}.
+ *
+ *
It is recommended to keep a reference to the LongPoint instead of always calling this method
+ * for manual operations.
+ *
+ * @param labelValues the list of label values. The number of label values must be the same to
+ * that of the label keys passed to {@link MetricRegistry#addLongCumulative}.
+ * @return a {@code LongPoint} the value of single cumulative.
+ * @throws NullPointerException if {@code labelValues} is null OR any element of {@code
+ * labelValues} is null.
+ * @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label
+ * keys passed to {@link MetricRegistry#addLongCumulative}.
+ * @since 0.21
+ */
+ public abstract LongPoint getOrCreateTimeSeries(List labelValues);
+
+ /**
+ * Returns a {@code LongPoint} for a cumulative with all labels not set, or default labels.
+ *
+ * @return a {@code LongPoint} for a cumulative with all labels not set, or default labels.
+ * @since 0.21
+ */
+ public abstract LongPoint getDefaultTimeSeries();
+
+ /**
+ * Removes the {@code TimeSeries} from the cumulative metric, if it is present. i.e. references to
+ * previous {@code LongPoint} objects are invalid (not part of the metric).
+ *
+ * @param labelValues the list of label values.
+ * @throws NullPointerException if {@code labelValues} is null.
+ * @since 0.21
+ */
+ public abstract void removeTimeSeries(List labelValues);
+
+ /**
+ * Removes all {@code TimeSeries} from the cumulative metric. i.e. references to all previous
+ * {@code LongPoint} objects are invalid (not part of the metric).
+ *
+ * @since 0.21
+ */
+ public abstract void clear();
+
+ /**
+ * Returns the no-op implementation of the {@code LongCumulative}.
+ *
+ * @return the no-op implementation of the {@code LongCumulative}.
+ * @since 0.21
+ */
+ static LongCumulative newNoopLongCumulative(
+ String name, String description, String unit, List labelKeys) {
+ return NoopLongCumulative.create(name, description, unit, labelKeys);
+ }
+
+ /**
+ * The value of a single point in the Cumulative.TimeSeries.
+ *
+ * @since 0.21
+ */
+ public abstract static class LongPoint {
+
+ /**
+ * Adds the given value to the current value. The values cannot be negative.
+ *
+ * @param delta the value to add
+ * @since 0.21
+ */
+ public abstract void add(long delta);
+
+ /**
+ * Sets the given value.
+ *
+ * @param val the new value.
+ * @since 0.21
+ */
+ public abstract void set(long val);
+ }
+
+ /** No-op implementations of LongCumulative class. */
+ private static final class NoopLongCumulative extends LongCumulative {
+ private final int labelKeysSize;
+
+ static NoopLongCumulative create(
+ String name, String description, String unit, List labelKeys) {
+ return new NoopLongCumulative(name, description, unit, labelKeys);
+ }
+
+ /** Creates a new {@code NoopLongPoint}. */
+ NoopLongCumulative(String name, String description, String unit, List labelKeys) {
+ labelKeysSize = labelKeys.size();
+ }
+
+ @Override
+ public NoopLongPoint getOrCreateTimeSeries(List labelValues) {
+ Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
+ Utils.checkArgument(
+ labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
+ return NoopLongPoint.INSTANCE;
+ }
+
+ @Override
+ public NoopLongPoint getDefaultTimeSeries() {
+ return NoopLongPoint.INSTANCE;
+ }
+
+ @Override
+ public void removeTimeSeries(List labelValues) {
+ Utils.checkNotNull(labelValues, "labelValues");
+ }
+
+ @Override
+ public void clear() {}
+
+ /** No-op implementations of LongPoint class. */
+ private static final class NoopLongPoint extends LongPoint {
+ private static final NoopLongPoint INSTANCE = new NoopLongPoint();
+
+ private NoopLongPoint() {}
+
+ @Override
+ public void add(long delta) {}
+
+ @Override
+ public void set(long val) {}
+ }
+ }
+}
diff --git a/api/src/main/java/io/opencensus/metrics/MetricRegistry.java b/api/src/main/java/io/opencensus/metrics/MetricRegistry.java
index ad01b5a14a..a0be194c88 100644
--- a/api/src/main/java/io/opencensus/metrics/MetricRegistry.java
+++ b/api/src/main/java/io/opencensus/metrics/MetricRegistry.java
@@ -50,8 +50,8 @@ public LongGauge addLongGauge(
}
/**
- * Builds a new long gauge to be added to the registry. This is more convenient form when you want
- * to manually increase and decrease values as per your service requirements.
+ * Builds a new long gauge to be added to the registry. This is a more convenient form when you
+ * want to manually increase and decrease values as per your service requirements.
*
* @param name the name of the metric.
* @param options the options for the metric.
@@ -82,7 +82,7 @@ public DoubleGauge addDoubleGauge(
}
/**
- * Builds a new double gauge to be added to the registry. This is more convenient form when you
+ * Builds a new double gauge to be added to the registry. This is a more convenient form when you
* want to manually increase and decrease values as per your service requirements.
*
* @param name the name of the metric.
@@ -114,8 +114,8 @@ public DerivedLongGauge addDerivedLongGauge(
}
/**
- * Builds a new derived long gauge to be added to the registry. This is more convenient form when
- * you want to define a gauge by executing a {@link ToLongFunction} on an object.
+ * Builds a new derived long gauge to be added to the registry. This is a more convenient form
+ * when you want to define a gauge by executing a {@link ToLongFunction} on an object.
*
* @param name the name of the metric.
* @param options the options for the metric.
@@ -146,7 +146,7 @@ public DerivedDoubleGauge addDerivedDoubleGauge(
}
/**
- * Builds a new derived double gauge to be added to the registry. This is more convenient form
+ * Builds a new derived double gauge to be added to the registry. This is a more convenient form
* when you want to define a gauge by executing a {@link ToDoubleFunction} on an object.
*
* @param name the name of the metric.
@@ -159,6 +159,64 @@ public DerivedDoubleGauge addDerivedDoubleGauge(
@ExperimentalApi
public abstract DerivedDoubleGauge addDerivedDoubleGauge(String name, MetricOptions options);
+ /**
+ * Builds a new long cumulative to be added to the registry. This is a more convenient form when
+ * you want to manually increase values as per your service requirements.
+ *
+ * @param name the name of the metric.
+ * @param options the options for the metric.
+ * @return a {@code LongCumulative}.
+ * @throws NullPointerException if {@code name} is null.
+ * @throws IllegalArgumentException if different metric with the same name already registered.
+ * @since 0.21
+ */
+ @ExperimentalApi
+ public abstract LongCumulative addLongCumulative(String name, MetricOptions options);
+
+ /**
+ * Builds a new double cumulative to be added to the registry. This is a more convenient form when
+ * you want to manually increase values as per your service requirements.
+ *
+ * @param name the name of the metric.
+ * @param options the options for the metric.
+ * @return a {@code DoubleCumulative}.
+ * @throws NullPointerException if {@code name} is null.
+ * @throws IllegalArgumentException if different metric with the same name already registered.
+ * @since 0.21
+ */
+ @ExperimentalApi
+ public abstract DoubleCumulative addDoubleCumulative(String name, MetricOptions options);
+
+ /**
+ * Builds a new derived long cumulative to be added to the registry. This is a more convenient
+ * form when you want to define a cumulative by executing a {@link ToLongFunction} on an object.
+ *
+ * @param name the name of the metric.
+ * @param options the options for the metric.
+ * @return a {@code DerivedLongCumulative}.
+ * @throws NullPointerException if {@code name} is null.
+ * @throws IllegalArgumentException if different metric with the same name already registered.
+ * @since 0.21
+ */
+ @ExperimentalApi
+ public abstract DerivedLongCumulative addDerivedLongCumulative(
+ String name, MetricOptions options);
+
+ /**
+ * Builds a new derived double cumulative to be added to the registry. This is a more convenient
+ * form when you want to define a cumulative by executing a {@link ToDoubleFunction} on an object.
+ *
+ * @param name the name of the metric.
+ * @param options the options for the metric.
+ * @return a {@code DerivedDoubleCumulative}.
+ * @throws NullPointerException if {@code name} is null.
+ * @throws IllegalArgumentException if different metric with the same name already registered.
+ * @since 0.21
+ */
+ @ExperimentalApi
+ public abstract DerivedDoubleCumulative addDerivedDoubleCumulative(
+ String name, MetricOptions options);
+
static MetricRegistry newNoopMetricRegistry() {
return new NoopMetricRegistry();
}
@@ -200,5 +258,41 @@ public DerivedDoubleGauge addDerivedDoubleGauge(String name, MetricOptions optio
options.getUnit(),
options.getLabelKeys());
}
+
+ @Override
+ public LongCumulative addLongCumulative(String name, MetricOptions options) {
+ return LongCumulative.newNoopLongCumulative(
+ Utils.checkNotNull(name, "name"),
+ options.getDescription(),
+ options.getUnit(),
+ options.getLabelKeys());
+ }
+
+ @Override
+ public DoubleCumulative addDoubleCumulative(String name, MetricOptions options) {
+ return DoubleCumulative.newNoopDoubleCumulative(
+ Utils.checkNotNull(name, "name"),
+ options.getDescription(),
+ options.getUnit(),
+ options.getLabelKeys());
+ }
+
+ @Override
+ public DerivedLongCumulative addDerivedLongCumulative(String name, MetricOptions options) {
+ return DerivedLongCumulative.newNoopDerivedLongCumulative(
+ Utils.checkNotNull(name, "name"),
+ options.getDescription(),
+ options.getUnit(),
+ options.getLabelKeys());
+ }
+
+ @Override
+ public DerivedDoubleCumulative addDerivedDoubleCumulative(String name, MetricOptions options) {
+ return DerivedDoubleCumulative.newNoopDerivedDoubleCumulative(
+ Utils.checkNotNull(name, "name"),
+ options.getDescription(),
+ options.getUnit(),
+ options.getLabelKeys());
+ }
}
}
diff --git a/api/src/test/java/io/opencensus/metrics/DerivedDoubleCumulativeTest.java b/api/src/test/java/io/opencensus/metrics/DerivedDoubleCumulativeTest.java
new file mode 100644
index 0000000000..5a3f119d36
--- /dev/null
+++ b/api/src/test/java/io/opencensus/metrics/DerivedDoubleCumulativeTest.java
@@ -0,0 +1,88 @@
+/*
+ * Copyright 2019, 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 java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.ExpectedException;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link DerivedDoubleCumulative}. */
+@RunWith(JUnit4.class)
+public class DerivedDoubleCumulativeTest {
+ @Rule public ExpectedException thrown = ExpectedException.none();
+
+ private static final String NAME = "name";
+ private static final String DESCRIPTION = "description";
+ private static final String UNIT = "1";
+ private static final List LABEL_KEY =
+ Collections.singletonList(LabelKey.create("key", "key description"));
+ private static final List LABEL_VALUES =
+ Collections.singletonList(LabelValue.create("value"));
+ private static final List EMPTY_LABEL_VALUES = new ArrayList();
+
+ private final DerivedDoubleCumulative derivedDoubleCumulative =
+ DerivedDoubleCumulative.newNoopDerivedDoubleCumulative(NAME, DESCRIPTION, UNIT, LABEL_KEY);
+ private static final ToDoubleFunction