[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
@@ -56,7 +57,7 @@ def usage(argv):
 # over the process lifetime. If false, metrics are reset at the beginning of
 # each collection interval.
 metrics.set_meter_provider(MeterProvider())
-meter = metrics.get_meter(__name__, batcher_mode == "stateful")
+meter = metrics.get_meter(__name__, stateful)
 
 # Exporter to export metrics to the console
 exporter = ConsoleMetricsExporter()
@@ -72,7 +73,6 @@ def usage(argv):
     unit="1",
     value_type=int,
     metric_type=Counter,
-    label_keys=("environment",),
 )
 
 requests_size = meter.create_metric(
@@ -81,7 +81,6 @@ def usage(argv):
     unit="1",
     value_type=int,
     metric_type=Measure,
-    label_keys=("environment",),
 )
 
 # Labels are used to identify key-values that are associated with a specific
@@ -101,4 +100,5 @@ def usage(argv):
 
 requests_counter.add(35, testing_labels)
 requests_size.record(2, testing_labels)
-time.sleep(5)
+
+input("...\n")

docs/examples/basic_meter/calling_conventions.py

@@ -19,7 +19,7 @@
 import time
 
 from opentelemetry import metrics
-from opentelemetry.sdk.metrics import Counter, Measure, MeterProvider
+from opentelemetry.sdk.metrics import Counter, MeterProvider
 from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
 from opentelemetry.sdk.metrics.export.controller import PushController
 
@@ -35,16 +35,6 @@
     unit="1",
     value_type=int,
     metric_type=Counter,
-    label_keys=("environment",),
-)
-
-requests_size = meter.create_metric(
-    name="requests_size",
-    description="size of requests",
-    unit="1",
-    value_type=int,
-    metric_type=Measure,
-    label_keys=("environment",),
 )
 
 clicks_counter = meter.create_metric(
@@ -53,7 +43,6 @@
     unit="1",
     value_type=int,
     metric_type=Counter,
-    label_keys=("environment",),
 )
 
 labels = {"environment": "staging"}
@@ -80,3 +69,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

@@ -21,11 +21,8 @@
 from opentelemetry import metrics
 from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
-from opentelemetry.sdk.metrics.export.batcher import UngroupedBatcher
 from opentelemetry.sdk.metrics.export.controller import PushController
 
-# Configure a stateful batcher
-batcher = UngroupedBatcher(stateful=True)
 metrics.set_meter_provider(MeterProvider())
 meter = metrics.get_meter(__name__)
 exporter = ConsoleMetricsExporter()
@@ -45,7 +42,6 @@ def get_cpu_usage_callback(observer):
     description="per-cpu usage",
     unit="1",
     value_type=float,
-    label_keys=("cpu_number",),
 )
 
 
@@ -61,7 +57,6 @@ def get_ram_usage_callback(observer):
     description="RAM memory usage",
     unit="1",
     value_type=float,
-    label_keys=(),
 )
 
 input("Metrics will be printed soon. Press a key to finish...\n")

docs/examples/basic_meter/view.py

@@ -0,0 +1,95 @@
+# 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.
+"""
+import time
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import Counter, Measure, MeterProvider
+from opentelemetry.sdk.metrics.export.aggregate import CountAggregation
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.controller import PushController
+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__)
+exporter = ConsoleMetricsExporter()
+controller = PushController(meter=meter, exporter=exporter, interval=5)
+
+requests_counter = meter.create_metric(
+    name="requests",
+    description="number of requests",
+    unit="1",
+    value_type=int,
+    metric_type=Counter,
+)
+
+requests_size = meter.create_metric(
+    name="requests_size",
+    description="size of requests",
+    unit="1",
+    value_type=int,
+    metric_type=Measure,
+)
+
+# 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,
+    CountAggregation(),
+    label_keys=["environment"],
+    config=ViewConfig.LABEL_KEYS
+)
+counter_view2 = View(
+    requests_counter,
+    CountAggregation(),
+    label_keys=["os_type"],
+    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,
+    CountAggregation(),
+    label_keys=["environment"], # is not used due to ViewConfig.UNGROUPED
+    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)
+
+# 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"})
+
+# Notice we did not create a view for requests_size, this will use the default
+# SummaryAggregation for Measure metrics with UNGROUPED keys
+requests_size.record(25, {"test": "value"})
+
+input("...\n")

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

@@ -291,7 +291,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``.
@@ -303,7 +302,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``.
         """