[WIP] Views API Prototype

docs/examples/basic_meter/basic_metrics.py

@@ -19,6 +19,7 @@
 - How to configure a meter passing a sateful or stateless.
 - How to configure an exporter and how to create a controller.
 - How to create some metrics intruments and how to capture data with them.
+- How to use views to specify aggregation types for each metric instrument.
 """
 import sys
 import time
@@ -57,7 +58,6 @@
     unit="1",
     value_type=int,
     metric_type=Counter,
-    label_keys=("environment",),
 )
 
 requests_size = meter.create_metric(
@@ -66,7 +66,6 @@
     unit="1",
     value_type=int,
     metric_type=ValueRecorder,
-    label_keys=("environment",),
 )
 
 # Labels are used to identify key-values that are associated with a specific
@@ -86,4 +85,5 @@
 
 requests_counter.add(35, testing_labels)
 requests_size.record(2, testing_labels)
-time.sleep(5)
+
+input("...\n")

docs/examples/basic_meter/calling_conventions.py

@@ -33,7 +33,6 @@
     unit="1",
     value_type=int,
     metric_type=Counter,
-    label_keys=("environment",),
 )
 
 requests_size = meter.create_metric(
@@ -42,7 +41,6 @@
     unit="1",
     value_type=int,
     metric_type=ValueRecorder,
-    label_keys=("environment",),
 )
 
 clicks_counter = meter.create_metric(
@@ -51,7 +49,6 @@
     unit="1",
     value_type=int,
     metric_type=Counter,
-    label_keys=("environment",),
 )
 
 labels = {"environment": "staging"}
@@ -78,3 +75,5 @@
 # specified labels for each.
 meter.record_batch(labels, ((requests_counter, 50), (clicks_counter, 70)))
 time.sleep(5)
+
+input("...\n")

docs/examples/basic_meter/observer.py

@@ -41,7 +41,6 @@ def get_cpu_usage_callback(observer):
     unit="1",
     value_type=float,
     observer_type=ValueObserver,
-    label_keys=("cpu_number",),
 )
 
 
@@ -58,7 +57,6 @@ def get_ram_usage_callback(observer):
     unit="1",
     value_type=float,
     observer_type=ValueObserver,
-    label_keys=(),
 )
 
 input("Metrics will be printed soon. Press a key to finish...\n")

docs/examples/basic_meter/view.py

@@ -0,0 +1,112 @@
+# Copyright The OpenTelemetry 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.
+#
+"""
+This example shows how to use the different modes to capture metrics.
+It shows the usage of the direct, bound and batch calling conventions.
+"""
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import (
+    MeterProvider,
+    UpDownCounter,
+    ValueRecorder,
+)
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.aggregate import (
+    HistogramAggregator,
+    LastValueAggregator,
+    MinMaxSumCountAggregator,
+    SumAggregator,
+)
+from opentelemetry.sdk.metrics.view import View, ViewConfig
+
+# Use the meter type provided by the SDK package
+metrics.set_meter_provider(MeterProvider())
+meter = metrics.get_meter(__name__)
+metrics.get_meter_provider().start_pipeline(meter, ConsoleMetricsExporter(), 5)
+
+requests_counter = meter.create_metric(
+    name="requests",
+    description="number of requests",
+    unit="1",
+    value_type=int,
+    metric_type=UpDownCounter,
+)
+
+requests_size = meter.create_metric(
+    name="requests_size",
+    description="size of requests",
+    unit="1",
+    value_type=int,
+    metric_type=ValueRecorder,
+)
+
+# Views are used to define an aggregation type and label keys to aggregate by
+# for a given metric
+
+# Two views with the same metric and aggregation type but different label keys
+# With ViewConfig.LABEL_KEYS, all labels but the ones defined in label_keys are
+# dropped from the aggregation
+counter_view1 = View(
+    requests_counter,
+    SumAggregator,
+    label_keys=["environment"],
+    view_config=ViewConfig.LABEL_KEYS,
+)
+counter_view2 = View(
+    requests_counter,
+    MinMaxSumCountAggregator,
+    label_keys=["os_type"],
+    view_config=ViewConfig.LABEL_KEYS,
+)
+# This view has ViewConfig set to UNGROUPED, meaning all recorded metrics take
+# the labels directly without and consideration for label_keys
+counter_view3 = View(
+    requests_counter,
+    LastValueAggregator,
+    label_keys=["environment"],  # is not used due to ViewConfig.UNGROUPED
+    view_config=ViewConfig.UNGROUPED,
+)
+# This view uses the HistogramAggregator which accepts an option config
+# parameter to specify the bucket ranges
+size_view = View(
+    requests_size,
+    HistogramAggregator,
+    label_keys=["environment"],  # is not used due to ViewConfig.UNGROUPED
+    aggregator_config={"bounds": [20, 40, 60, 80, 100]},
+    view_config=ViewConfig.UNGROUPED,
+)
+
+# Register the views to the view manager to use the views. Views MUST be
+# registered before recording metrics. Metrics that are recorded without
+# views defined for them will use a default for that type of metric
+meter.register_view(counter_view1)
+meter.register_view(counter_view2)
+meter.register_view(counter_view3)
+meter.register_view(size_view)
+
+# The views will evaluate the labels passed into the record and aggregate upon
+# the unique labels that are generated
+# view1 labels will evaluate to {"environment": "staging"}
+# view2 labels will evaluate to {"os_type": linux}
+# view3 labels will evaluate to {"environment": "staging", "os_type": "linux"}
+requests_counter.add(100, {"environment": "staging", "os_type": "linux"})
+
+# Since this is using the HistogramAggregator, the bucket counts will be reflected
+# with each record
+requests_size.record(25, {"test": "value"})
+requests_size.record(-3, {"test": "value"})
+requests_size.record(200, {"test": "value"})
+
+input("...\n")

ext/opentelemetry-ext-opencensusexporter/tests/test_otcollector_metrics_exporter.py

@@ -25,7 +25,7 @@
     Counter,
     MeterProvider,
     ValueRecorder,
-    get_labels_as_key,
+    get_dict_as_key,
 )
 from opentelemetry.sdk.metrics.export import (
     MetricRecord,
@@ -42,7 +42,7 @@ def setUpClass(cls):
         metrics.set_meter_provider(MeterProvider())
         cls._meter = metrics.get_meter(__name__)
         cls._labels = {"environment": "staging"}
-        cls._key_labels = get_labels_as_key(cls._labels)
+        cls._key_labels = get_dict_as_key(cls._labels)
 
     def test_constructor(self):
         mock_get_node = mock.Mock()
@@ -119,7 +119,7 @@ def test_export(self):
             client=mock_client, host_name=host_name
         )
         test_metric = self._meter.create_metric(
-            "testname", "testdesc", "unit", int, Counter, ["environment"]
+            "testname", "testdesc", "unit", int, Counter,
         )
         record = MetricRecord(
             test_metric, self._key_labels, aggregate.SumAggregator(),
@@ -142,7 +142,7 @@ def test_export(self):
 
     def test_translate_to_collector(self):
         test_metric = self._meter.create_metric(
-            "testname", "testdesc", "unit", int, Counter, ["environment"]
+            "testname", "testdesc", "unit", int, Counter,
         )
         aggregator = aggregate.SumAggregator()
         aggregator.update(123)

ext/opentelemetry-ext-prometheus/tests/test_prometheus_exporter.py

@@ -32,15 +32,10 @@ def setUp(self):
         set_meter_provider(metrics.MeterProvider())
         self._meter = get_meter_provider().get_meter(__name__)
         self._test_metric = self._meter.create_metric(
-            "testname",
-            "testdesc",
-            "unit",
-            int,
-            metrics.Counter,
-            ["environment"],
+            "testname", "testdesc", "unit", int, metrics.Counter,
         )
         labels = {"environment": "staging"}
-        self._labels_key = metrics.get_labels_as_key(labels)
+        self._labels_key = metrics.get_dict_as_key(labels)
 
         self._mock_registry_register = mock.Mock()
         self._registry_register_patch = mock.patch(
@@ -78,15 +73,10 @@ def test_export(self):
     def test_counter_to_prometheus(self):
         meter = get_meter_provider().get_meter(__name__)
         metric = meter.create_metric(
-            "test@name",
-            "testdesc",
-            "unit",
-            int,
-            metrics.Counter,
-            ["environment@", "os"],
+            "test@name", "testdesc", "unit", int, metrics.Counter,
         )
         labels = {"environment@": "staging", "os": "Windows"}
-        key_labels = metrics.get_labels_as_key(labels)
+        key_labels = metrics.get_dict_as_key(labels)
         aggregator = SumAggregator()
         aggregator.update(123)
         aggregator.take_checkpoint()
@@ -117,7 +107,7 @@ def test_invalid_metric(self):
             "tesname", "testdesc", "unit", int, StubMetric
         )
         labels = {"environment": "staging"}
-        key_labels = metrics.get_labels_as_key(labels)
+        key_labels = metrics.get_dict_as_key(labels)
         record = MetricRecord(metric, key_labels, None)
         collector = CustomCollector("testprefix")
         collector.add_metrics_data([record])
@@ -143,15 +133,8 @@ def __init__(
         unit: str,
         value_type,
         meter,
-        label_keys,
         enabled: bool = True,
     ):
         super().__init__(
-            name,
-            description,
-            unit,
-            value_type,
-            meter,
-            label_keys=label_keys,
-            enabled=enabled,
+            name, description, unit, value_type, meter, enabled=enabled,
         )

opentelemetry-api/src/opentelemetry/metrics/__init__.py

@@ -342,7 +342,6 @@ def create_metric(
         unit: str,
         value_type: Type[ValueT],
         metric_type: Type[MetricT],
-        label_keys: Sequence[str] = (),
         enabled: bool = True,
     ) -> "Metric":
         """Creates a ``metric_kind`` metric with type ``value_type``.
@@ -354,7 +353,6 @@ def create_metric(
                 (https://unitsofmeasure.org/ucum.html).
             value_type: The type of values being recorded by the metric.
             metric_type: The type of metric being created.
-            label_keys: The keys for the labels with dynamic values.
             enabled: Whether to report the metric by default.
         Returns: A new ``metric_type`` metric with values of ``value_type``.
         """
@@ -413,7 +411,6 @@ def create_metric(
         unit: str,
         value_type: Type[ValueT],
         metric_type: Type[MetricT],
-        label_keys: Sequence[str] = (),
         enabled: bool = True,
     ) -> "Metric":
         # pylint: disable=no-self-use

opentelemetry-sdk/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - Add support for resources and resource detector
   ([#853](https://github.com/open-telemetry/opentelemetry-python/pull/853))
+- Implement Views in metrics SDK
+  ([#596](https://github.com/open-telemetry/opentelemetry-python/pull/596))
 
 ## Version 0.10b0