Cumulative metrics API (#626)

Author: c24t

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Add cumulative API
+  ([#626](https://github.com/census-instrumentation/opencensus-python/pull/626))
+
 ## 0.4.0
 Released 2019-04-08
 

opencensus/metrics/export/cumulative.py

@@ -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.
+
+import six
+
+from opencensus.metrics.export import metric_descriptor
+from opencensus.metrics.export import gauge
+
+
+class CumulativePointLong(gauge.GaugePointLong):
+    """A `GaugePointLong` that cannot decrease."""
+
+    def _set(self, val):
+        if not isinstance(val, six.integer_types):
+            raise ValueError("CumulativePointLong only supports integer types")
+        if val > self.get_value():
+            super(CumulativePointLong, self)._set(val)
+
+    def add(self, val):
+        """Add `val` to the current value if it's positive.
+
+        Return without adding if `val` is not positive.
+
+        :type val: int
+        :param val: Value to add.
+        """
+        if not isinstance(val, six.integer_types):
+            raise ValueError("CumulativePointLong only supports integer types")
+        if val > 0:
+            super(CumulativePointLong, self).add(val)
+
+
+class CumulativePointDouble(gauge.GaugePointDouble):
+    """A `GaugePointDouble` that cannot decrease."""
+
+    def _set(self, val):
+        if val > self.get_value():
+            super(CumulativePointDouble, self)._set(val)
+
+    def add(self, val):
+        """Add `val` to the current value if it's positive.
+
+        Return without adding if `val` is not positive.
+
+        :type val: float
+        :param val: Value to add.
+        """
+        if val > 0:
+            super(CumulativePointDouble, self).add(val)
+
+
+class LongCumulativeMixin(object):
+    """Type mixin for long-valued cumulative measures."""
+    descriptor_type = metric_descriptor.MetricDescriptorType.CUMULATIVE_INT64
+    point_type = CumulativePointLong
+
+
+class DoubleCumulativeMixin(object):
+    """Type mixin for float-valued cumulative measures."""
+    descriptor_type = metric_descriptor.MetricDescriptorType.CUMULATIVE_DOUBLE
+    point_type = CumulativePointDouble
+
+
+class LongCumulative(LongCumulativeMixin, gauge.Gauge):
+    """Records cumulative int-valued measurements."""
+
+
+class DoubleCumulative(DoubleCumulativeMixin, gauge.Gauge):
+    """Records cumulative float-valued measurements."""
+
+
+class DerivedLongCumulative(LongCumulativeMixin, gauge.DerivedGauge):
+    """Records derived cumulative int-valued measurements."""
+
+
+class DerivedDoubleCumulative(DoubleCumulativeMixin, gauge.DerivedGauge):
+    """Records derived cumulative float-valued measurements."""

opencensus/metrics/export/gauge.py

@@ -88,16 +88,19 @@ def add(self, val):
         with self._value_lock:
             self.value += val
 
+    def _set(self, val):
+        if not isinstance(val, six.integer_types):
+            raise ValueError("GaugePointLong only supports integer types")
+        with self._value_lock:
+            self.value = val
+
     def set(self, val):
         """Set the current value to `val`.
 
         :type val: int
         :param val: Value to set.
         """
-        if not isinstance(val, six.integer_types):
-            raise ValueError("GaugePointLong only supports integer types")
-        with self._value_lock:
-            self.value = val
+        self._set(val)
 
     def get_value(self):
         """Get the current value.
@@ -143,14 +146,17 @@ def add(self, val):
         with self._value_lock:
             self.value += val
 
+    def _set(self, val):
+        with self._value_lock:
+            self.value = float(val)
+
     def set(self, val):
         """Set the current value to `val`.
 
         :type val: float
         :param val: Value to set.
         """
-        with self._value_lock:
-            self.value = float(val)
+        self._set(val)
 
     def get_value(self):
         """Get the current value.
@@ -180,7 +186,9 @@ class DerivedGaugePoint(GaugePoint):
     :type func: function
     :param func: The function to track.
 
-    :type gauge_point: :class:`GaugePointLong` or :class:`GaugePointDouble`
+    :type gauge_point: :class:`GaugePointLong`, :class:`GaugePointDouble`,
+        :class:`opencensus.metrics.export.cumulative.CumulativePointLong`, or
+        :class:`opencensus.metrics.export.cumulative.CumulativePointDouble`
     :param gauge_point: The underlying `GaugePoint`.
     """
     def __init__(self, func, gauge_point):
@@ -202,13 +210,14 @@ def get_value(self):
 
         :rtype: int, float, or None
         :return: The current value of the wrapped function, or `None` if it no
-        longer exists.
+            longer exists.
         """
         try:
-            self.gauge_point.set(self.func()())
-        # The underlying function has been GC'd
-        except TypeError:
+            val = self.func()()
+        except TypeError:  # The underlying function has been GC'd
             return None
+
+        self.gauge_point._set(val)
         return self.gauge_point.get_value()
 
     def to_point_value(self):
@@ -218,9 +227,9 @@ def to_point_value(self):
         measurement as a side-effect.
 
         :rtype: :class:`opencensus.metrics.export.value.ValueLong`,
-        :class:`opencensus.metrics.export.value.ValueDouble`, or None
+            :class:`opencensus.metrics.export.value.ValueDouble`, or None
         :return: The point value conversion of the underlying `GaugePoint`, or
-        None if the tracked function no longer exists.
+            None if the tracked function no longer exists.
         """
         if self.get_value() is None:
             return None
@@ -309,7 +318,9 @@ def point_type(self):  # pragma: NO COVER
 class Gauge(BaseGauge):
     """A set of mutable, instantaneous measurements of the same type.
 
-    End users should use :class:`LongGauge` or :class:`DoubleGauge` instead of
+    End users should use :class:`LongGauge`, :class:`DoubleGauge`,
+    :class:`opencensus.metrics.export.cumulative.LongCumulative`, or
+    :class:`opencensus.metrics.export.cumulative.DoubleCumulative` instead of
     using this class directly.
 
     The constructor arguments are used to create a
@@ -328,9 +339,12 @@ def get_or_create_time_series(self, label_values):
         :type label_values: list(:class:`LabelValue`)
         :param label_values: The measurement's label values.
 
-        :rtype: :class:`GaugePointLong` or :class:`GaugePointDouble`
+        :rtype: :class:`GaugePointLong`, :class:`GaugePointDouble`
+            :class:`opencensus.metrics.export.cumulative.CumulativePointLong`,
+            or
+            :class:`opencensus.metrics.export.cumulative.CumulativePointDouble`
         :return: A mutable point that represents the last value of the
-        measurement.
+            measurement.
         """
         if label_values is None:
             raise ValueError
@@ -347,9 +361,12 @@ def get_or_create_default_time_series(self):
         values. When this gauge is exported as a metric via `get_metric` the
         time series associated with this point will have null label values.
 
-        :rtype: :class:`GaugePointLong` or :class:`GaugePointDouble`
+        :rtype: :class:`GaugePointLong`, :class:`GaugePointDouble`
+            :class:`opencensus.metrics.export.cumulative.CumulativePointLong`,
+            or
+            :class:`opencensus.metrics.export.cumulative.CumulativePointDouble`
         :return: A mutable point that represents the last value of the
-        measurement.
+            measurement.
         """
         return self._get_or_create_time_series(self.default_label_values)
 
@@ -380,8 +397,10 @@ class DerivedGauge(BaseGauge):
     Each of a `DerivedGauge`'s measurements are associated with a function
     which is called when the gauge is exported.
 
-    End users should use :class:`DerivedLongGauge` or
-    :class:`DerivedDoubleGauge` instead of using this class directly.
+    End users should use :class:`DerivedLongGauge`, :class:`DerivedDoubleGauge`
+    :class:`opencensus.metrics.export.cumulative.DerivedLongCumulative`, or
+    :class:`opencensus.metrics.export.cumulative.DerivedDoubleCumulative`
+    instead of using this class directly.
     """
 
     def _create_time_series(self, label_values, func):
@@ -452,18 +471,19 @@ def __repr__(self):
                 ))
 
     def add_gauge(self, gauge):
-        """Add `gauge` to the registry and return it.
+        """Add `gauge` to the registry.
 
         Raises a `ValueError` if another gauge with the same name already
         exists in the registry.
 
         :type gauge: class:`LongGauge`, class:`DoubleGauge`,
-        :class:`DerivedLongGauge`, or :class:`DerivedDoubleGauge`
+            :class:`opencensus.metrics.export.cumulative.LongCumulative`,
+            :class:`opencensus.metrics.export.cumulative.DoubleCumulative`,
+            :class:`DerivedLongGauge`, :class:`DerivedDoubleGauge`
+            :class:`opencensus.metrics.export.cumulative.DerivedLongCumulative`,
+            or
+            :class:`opencensus.metrics.export.cumulative.DerivedDoubleCumulative`
         :param gauge: The gauge to add to the registry.
-
-        :type gauge: class:`LongGauge`, class:`DoubleGauge`,
-        :class:`DerivedLongGauge`, or :class:`DerivedDoubleGauge`
-        :return: The gauge that was added to the registry.
         """
         if gauge is None:
             raise ValueError