Metrics export pipeline + metrics stdout exporter

docs/opentelemetry.sdk.metrics.export.aggregate.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk.metrics.export.aggregate
+==========================================
+
+.. automodule:: opentelemetry.sdk.metrics.export.aggregate
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.metrics.export.batcher.rst

@@ -0,0 +1,11 @@
+opentelemetry.sdk.metrics.export.batcher
+==========================================
+
+.. toctree::
+
+   opentelemetry.sdk.metrics.export
+
+.. automodule:: opentelemetry.sdk.metrics.export.batcher
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.metrics.export.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk.metrics.export
+==========================================
+
+.. automodule:: opentelemetry.sdk.metrics.export
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.metrics.rst

@@ -1,6 +1,14 @@
 opentelemetry.sdk.metrics package
 ==========================================
 
+Submodules
+----------
+
+.. toctree::
+
+   opentelemetry.sdk.metrics.export.aggregate
+   opentelemetry.sdk.metrics.export.batcher
+
 .. automodule:: opentelemetry.sdk.metrics
     :members:
     :undoc-members:

examples/metrics/non_stateful.py

@@ -0,0 +1,59 @@
+# Copyright 2019, 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 module serves as an example for a simple application using metrics
+Examples show how to recording affects the collection of metrics to be exported
+"""
+import time
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.batcher import UngroupedBatcher
+from opentelemetry.sdk.metrics.export.controller import PushController
+
+# Batcher used to collect all created metrics from meter ready for exporting
+# Pass in false for non-stateful batcher. Indicates the batcher computes
+# checkpoints which describe the updates of a single collection period (deltas)
+batcher = UngroupedBatcher(False)
+# Meter is responsible for creating and recording metrics
+meter = Meter(batcher)
+metrics.set_preferred_meter_implementation(meter)
+# exporter to export metrics to the console
+exporter = ConsoleMetricsExporter()
+# controller collects metrics created from meter and exports it via the
+# exporter every interval
+controller = PushController(meter, exporter, 5)
+
+counter = meter.create_metric(
+    "available memory",
+    "available memory",
+    "bytes",
+    int,
+    Counter,
+    ("environment",),
+)
+
+label_set = meter.get_label_set({"environment": "staging"})
+
+counter.add(25, label_set)
+# We sleep for 5 seconds, exported value should be 25
+time.sleep(5)
+
+counter.add(50, label_set)
+# exported value should be 50 due to non-stateful batcher
+time.sleep(5)
+
+# Following exported values would be 0

examples/metrics/record.py

@@ -0,0 +1,68 @@
+# Copyright 2019, 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 module serves as an example for a simple application using metrics.
+It demonstrates the different ways you can record metrics via the meter.
+"""
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.controller import PushController
+
+# Meter is responsible for creating and recording metrics
+meter = Meter()
+metrics.set_preferred_meter_implementation(meter)
+# exporter to export metrics to the console
+exporter = ConsoleMetricsExporter()
+# controller collects metrics created from meter and exports it via the
+# exporter every interval
+controller = PushController(meter, exporter, 5)
+
+# Example to show how to record using the meter
+counter = meter.create_metric(
+    "available memory",
+    "available memory",
+    "bytes",
+    int,
+    Counter,
+    ("environment",),
+)
+
+# Labelsets are used to identify key-values that are associated with a specific
+# metric that you want to record. These are useful for pre-aggregation and can
+# be used to store custom dimensions pertaining to a metric
+
+# The meter takes a dictionary of key value pairs
+label_set = meter.get_label_set({"environment": "staging"})
+
+# Handle usage
+# You can record metrics with metric handles. Handles are created by passing in
+# a labelset. A handle is essentially metric data that corresponds to a specific
+# set of labels. Therefore, getting a handle using the same set of labels will
+# yield the same metric handle.
+counter_handle = counter.get_handle(label_set)
+counter_handle.add(100)
+
+# Direct metric usage
+# You can record metrics directly using the metric instrument. You pass in a
+# labelset that you would like to record for.
+counter.add(25, label_set)
+
+# Record batch usage
+# You can record metrics in a batch by passing in a labelset and a sequence of
+# (metric, value) pairs. The value would be recorded for each metric using the
+# specified labelset for each.
+meter.record_batch(label_set, [(counter, 50)])

examples/metrics/stateful.py

@@ -0,0 +1,79 @@
+# Copyright 2019, 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 module serves as an example for a simple application using metrics
+Examples show how to recording affects the collection of metrics to be exported
+"""
+import time
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.batcher import UngroupedBatcher
+from opentelemetry.sdk.metrics.export.controller import PushController
+
+# Batcher used to collect all created metrics from meter ready for exporting
+# Pass in true/false to indicate whether the batcher is stateful. True
+# indicates the batcher computes checkpoints from over the process lifetime.
+# False indicates the batcher computes checkpoints which describe the updates
+# of a single collection period (deltas)
+batcher = UngroupedBatcher(True)
+# If a batcher is not provded, a default batcher is used
+# Meter is responsible for creating and recording metrics
+meter = Meter(batcher)
+metrics.set_preferred_meter_implementation(meter)
+# exporter to export metrics to the console
+exporter = ConsoleMetricsExporter()
+# controller collects metrics created from meter and exports it via the
+# exporter every interval
+controller = PushController(meter, exporter, 5)
+
+counter = meter.create_metric(
+    "available memory",
+    "available memory",
+    "bytes",
+    int,
+    Counter,
+    ("environment",),
+)
+
+counter2 = meter.create_metric(
+    "available memory2",
+    "available memory2",
+    "bytes2",
+    int,
+    Counter,
+    ("environment",),
+)
+
+label_set = meter.get_label_set({"environment": "staging"})
+label_set2 = meter.get_label_set({"environment": "testing"})
+
+counter.add(25, label_set)
+# We sleep for 5 seconds, exported value should be 25
+time.sleep(5)
+
+counter.add(50, label_set)
+# exported value should be 75
+time.sleep(5)
+
+counter.add(35, label_set2)
+# should be two exported values 75 and 35, one for each labelset
+time.sleep(5)
+
+counter2.add(5, label_set)
+# should be three exported values, labelsets can be reused for different
+# metrics but will be recorded seperately, 75, 35 and 5
+time.sleep(5)

examples/opentelemetry-example-app/src/opentelemetry_example_app/metrics_example.py

@@ -18,8 +18,12 @@
 
 from opentelemetry import metrics
 from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.batcher import UngroupedBatcher
+from opentelemetry.sdk.metrics.export.controller import PushController
 
-metrics.set_preferred_meter_implementation(lambda _: Meter())
+batcher = UngroupedBatcher(True)
+metrics.set_preferred_meter_implementation(lambda _: Meter(batcher))
 meter = metrics.meter()
 counter = meter.create_metric(
     "available memory",
@@ -33,14 +37,14 @@
 label_set = meter.get_label_set({"environment": "staging"})
 
 # Direct metric usage
-counter.add(label_set, 25)
+counter.add(25, label_set)
 
 # Handle usage
 counter_handle = counter.get_handle(label_set)
 counter_handle.add(100)
 
 # Record batch usage
 meter.record_batch(label_set, [(counter, 50)])
-print(counter_handle.data)
 
-# TODO: exporters
+exporter = ConsoleMetricsExporter()
+controller = PushController(meter, exporter, 5)

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

@@ -128,12 +128,12 @@ def get_handle(self, label_set: LabelSet) -> "CounterHandle":
         """Gets a `CounterHandle`."""
         return CounterHandle()
 
-    def add(self, label_set: LabelSet, value: ValueT) -> None:
+    def add(self, value: ValueT, label_set: LabelSet) -> None:
         """Increases the value of the counter by ``value``.
 
         Args:
-            label_set: `LabelSet` to associate with the returned handle.
             value: The value to add to the counter metric.
+            label_set: `LabelSet` to associate with the returned handle.
         """
 
 
@@ -150,12 +150,12 @@ def get_handle(self, label_set: LabelSet) -> "GaugeHandle":
         """Gets a `GaugeHandle`."""
         return GaugeHandle()
 
-    def set(self, label_set: LabelSet, value: ValueT) -> None:
+    def set(self, value: ValueT, label_set: LabelSet) -> None:
         """Sets the value of the gauge to ``value``.
 
         Args:
-            label_set: `LabelSet` to associate with the returned handle.
             value: The value to set the gauge metric to.
+            label_set: `LabelSet` to associate with the returned handle.
         """
 
 
@@ -171,12 +171,12 @@ def get_handle(self, label_set: LabelSet) -> "MeasureHandle":
         """Gets a `MeasureHandle` with a float value."""
         return MeasureHandle()
 
-    def record(self, label_set: LabelSet, value: ValueT) -> None:
+    def record(self, value: ValueT, label_set: LabelSet) -> None:
         """Records the ``value`` to the measure.
 
         Args:
-            label_set: `LabelSet` to associate with the returned handle.
             value: The value to record to this measure metric.
+            label_set: `LabelSet` to associate with the returned handle.
         """
 
 
@@ -221,6 +221,7 @@ def create_metric(
         label_keys: Sequence[str] = (),
         enabled: bool = True,
         monotonic: bool = False,
+        absolute: bool = True,
     ) -> "Metric":
         """Creates a ``metric_kind`` metric with type ``value_type``.
 
@@ -232,8 +233,10 @@ def create_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.
-            monotonic: Whether to only allow non-negative values.
-
+            monotonic: Configure a counter or gauge that accepts only
+                monotonic/non-monotonic updates.
+            absolute: Configure a measure that does or does not accept negative
+                updates.
         Returns: A new ``metric_type`` metric with values of ``value_type``.
         """
         # pylint: disable=no-self-use

opentelemetry-api/tests/metrics/test_metrics.py

@@ -52,7 +52,7 @@ def test_counter(self):
     def test_counter_add(self):
         counter = metrics.Counter()
         label_set = metrics.LabelSet()
-        counter.add(label_set, 1)
+        counter.add(1, label_set)
 
     def test_gauge(self):
         gauge = metrics.Gauge()
@@ -63,7 +63,7 @@ def test_gauge(self):
     def test_gauge_set(self):
         gauge = metrics.Gauge()
         label_set = metrics.LabelSet()
-        gauge.set(label_set, 1)
+        gauge.set(1, label_set)
 
     def test_measure(self):
         measure = metrics.Measure()
@@ -74,7 +74,7 @@ def test_measure(self):
     def test_measure_record(self):
         measure = metrics.Measure()
         label_set = metrics.LabelSet()
-        measure.record(label_set, 1)
+        measure.record(1, label_set)
 
     def test_default_handle(self):
         metrics.DefaultMetricHandle()