Add MetricDescriptor class, tests

opencensus/metrics/export/metric_descriptor.py

@@ -0,0 +1,142 @@
+# 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.
+
+
+import six
+
+
+class _MetricDescriptorTypeMeta(type):
+    """Helper for `x in MetricDescriptorType`."""
+
+    def __contains__(cls, item):
+        return item in {MetricDescriptorType.GAUGE_INT64,
+                        MetricDescriptorType.GAUGE_DOUBLE,
+                        MetricDescriptorType.GAUGE_DISTRIBUTION,
+                        MetricDescriptorType.CUMULATIVE_INT64,
+                        MetricDescriptorType.CUMULATIVE_DOUBLE,
+                        MetricDescriptorType.CUMULATIVE_DISTRIBUTION}
+
+
+@six.add_metaclass(_MetricDescriptorTypeMeta)
+class MetricDescriptorType(object):
+    """The kind of metric. It describes how the data is reported.
+
+    MetricDescriptorType is an enum of valid MetricDescriptor type values. See
+    opencensus-proto for details:
+
+        https://github.com/census-instrumentation/opencensus-proto/blob/24333298e36590ea0716598caacc8959fc393c48/src/opencensus/proto/metrics/v1/metrics.proto#L73  # noqa
+
+    A gauge is an instantaneous measurement of a value.
+
+    A cumulative measurement is a value accumulated over a time interval. In a
+    time series, cumulative measurements should have the same start time and
+    increasing end times, until an event resets the cumulative value to zero
+    and sets a new start time for the following points.
+
+    """
+    # Integer gauge. The value can go both up and down.
+    GAUGE_INT64 = 1
+
+    # Floating point gauge. The value can go both up and down.
+    GAUGE_DOUBLE = 2
+
+    # Distribution gauge measurement. The count and sum can go both up and
+    # down. Recorded values are always >= 0.
+    # Used in scenarios like a snapshot of time the current items in a queue
+    # have spent there.
+    GAUGE_DISTRIBUTION = 3
+
+    # Integer cumulative measurement. The value cannot decrease, if resets then
+    # the start_time should also be reset.
+    CUMULATIVE_INT64 = 4
+
+    # Floating point cumulative measurement. The value cannot decrease, if
+    # resets then the start_time should also be reset. Recorded values are
+    # always >= 0.
+    CUMULATIVE_DOUBLE = 5
+
+    # Distribution cumulative measurement. The count and sum cannot decrease,
+    # if resets then the start_time should also be reset.
+    CUMULATIVE_DISTRIBUTION = 6
+
+    # Some frameworks implemented Histograms as a summary of observations
+    # (usually things like request durations and response sizes). While it also
+    # provides a total count of observations and a sum of all observed values,
+    # it calculates configurable percentiles over a sliding time window. This
+    # is not recommended, since it cannot be aggregated.
+    SUMMARY = 7
+
+
+class MetricDescriptor(object):
+    """Defines a metric type and its schema.
+
+    This class implements the spec for v1 MetricDescriptors, as of
+    opencensus-proto release v0.0.2. See opencensus-proto for details:
+
+        https://github.com/census-instrumentation/opencensus-proto/blob/24333298e36590ea0716598caacc8959fc393c48/src/opencensus/proto/metrics/v1/metrics.proto#L53  # noqa
+
+    :type name: str
+    :param name: The metric type, including its DNS name prefix. It must be
+    unique.
+
+    :type description: str
+    :param description: A detailed description of the metric, which can be used
+    in documentation.
+
+    :type unit: str
+    :param unit: The unit in which the metric value is reported. Follows the
+    format described by http://unitsofmeasure.org/ucum.html.
+
+    :type type_: int
+    :param unit: The unit in which the metric value is reported. The
+    MetricDescriptorType class enumerates valid options.
+
+    :type label_keys: list(:class: '~opencensus.metrics.label_key.LabelKey')
+    :param label_keys: The label keys associated with the metric descriptor.
+    """
+    def __init__(self, name, description, unit, type_, label_keys):
+        if type_ not in MetricDescriptorType:
+            raise ValueError("Invalid type")
+
+        if not label_keys:
+            raise ValueError("label_keys must not be empty or null")
+
+        if any(key is None for key in label_keys):
+            raise ValueError("label_keys must not contain null keys")
+
+        self._name = name
+        self._description = description
+        self._unit = unit
+        self._type = type_
+        self._label_keys = label_keys
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def description(self):
+        return self._description
+
+    @property
+    def unit(self):
+        return self._unit
+
+    @property
+    def type(self):
+        return self._type
+
+    @property
+    def label_keys(self):
+        return self._label_keys

tests/unit/metrics/export/test_metric_descriptor.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+
+import unittest
+
+from opencensus.metrics.export.metric_descriptor import MetricDescriptor
+from opencensus.metrics.export.metric_descriptor import MetricDescriptorType
+from opencensus.metrics.label_key import LabelKey
+
+
+NAME = 'metric'
+DESCRIPTION = 'Metric description'
+UNIT = '0.738.[ft_i].[lbf_av]/s'
+LABEL_KEY1 = LabelKey('key1', 'key description one')
+LABEL_KEY2 = LabelKey('值', '测试用键')
+LABEL_KEYS = (LABEL_KEY1, LABEL_KEY2)
+
+
+class TestMetricDescriptor(unittest.TestCase):
+
+    def test_init(self):
+        metric_descriptor = MetricDescriptor(NAME, DESCRIPTION, UNIT,
+                                             MetricDescriptorType.GAUGE_DOUBLE,
+                                             (LABEL_KEY1, LABEL_KEY2))
+
+        self.assertEqual(metric_descriptor.name, NAME)
+        self.assertEqual(metric_descriptor.description, DESCRIPTION)
+        self.assertEqual(metric_descriptor.unit, UNIT)
+        self.assertEqual(metric_descriptor.type,
+                         MetricDescriptorType.GAUGE_DOUBLE)
+        self.assertEqual(metric_descriptor.label_keys, LABEL_KEYS)
+
+    def test_bogus_type(self):
+        with self.assertRaises(ValueError):
+            MetricDescriptor(NAME, DESCRIPTION, UNIT, 0, (LABEL_KEY1,))
+
+    def test_null_label_keys(self):
+        with self.assertRaises(ValueError):
+            MetricDescriptor(NAME, DESCRIPTION, UNIT,
+                             MetricDescriptorType.GAUGE_DOUBLE, None)
+
+    def test_null_label_key_values(self):
+        with self.assertRaises(ValueError):
+            MetricDescriptor(NAME, DESCRIPTION, UNIT,
+                             MetricDescriptorType.GAUGE_DOUBLE, (None,))