Metrics Implementation

docs/opentelemetry.metrics.rst

@@ -1,13 +1,6 @@
 opentelemetry.metrics package
 =============================
 
-Submodules
-----------
-
-.. toctree::
-
-   opentelemetry.metrics.handle
-
 Module contents
 ---------------
 

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

@@ -26,15 +26,15 @@
 
 
 """
+import enum
+
 from abc import ABC, abstractmethod
-from typing import Dict, List, Tuple, Type, Union
+from typing import Callable, Generic, Optional, Tuple, Type, TypeVar, Union
+
+from opentelemetry.util import loader
 
-from opentelemetry.metrics.handle import (
-    CounterHandle,
-    GaugeHandle,
-    MeasureHandle,
-)
-from opentelemetry.trace import SpanContext
+MetricKind = Union[Type["Counter"], Type["Gauge"], Type["Measure"]]
+ValueType = TypeVar('ValueType', int, float)
 
 
 # pylint: disable=unused-argument
@@ -48,126 +48,104 @@ class Meter:
 
     def record_batch(
         self,
-        label_tuples: Dict[str, str],
-        record_tuples: List[Tuple["Metric", Union[float, int]]],
+        label_values: Tuple[str],
+        record_tuples: Tuple[Tuple["Metric", "ValueType"]],
     ) -> None:
         """Atomically records a batch of `Metric` and value pairs.
 
         Allows the functionality of acting upon multiple metrics with
-        a single API call. Implementations should find handles that match
-        the key-value pairs in the label tuples.
+        a single API call. Implementations should find metric and handles that
+        match the key-value pairs in the label tuples.
 
         Args:
-            label_tuples: A collection of key value pairs that will be matched
-                against to record for the metric-handle that has those labels.
-            record_tuples: A list of pairs of `Metric` s and the
+            label_values: The values that will be matched against to record for
+            the handles under each metric that has those labels.
+            record_tuples: A tuple of pairs of `Metric` s and the
                 corresponding value to record for that metric.
         """
 
 
-def create_counter(
-    name: str,
-    description: str,
-    unit: str,
-    value_type: Union[Type[float], Type[int]],
-    is_bidirectional: bool = False,
-    label_keys: List[str] = None,
-    span_context: SpanContext = None,
-) -> Union["FloatCounter", "IntCounter"]:
-    """Creates a counter metric with type value_type.
-
-    By default, counter values can only go up (unidirectional). The API
-    should reject negative inputs to unidirectional counter metrics.
-    Counter metrics have a bidirectional option to allow for negative
-    inputs.
+    def create_metric(
+        self,
+        name: str,
+        description: str,
+        unit: str,
+        value_type: "ValueType",
+        metric_kind: "MetricKind",
+        label_keys: Tuple[str] = None,
+        enabled: bool = True,
+        monotonic: bool = False,
+    ) -> "MetricKind":
+        """Creates a `metric_kind` metric with type `value_type`.
 
-    Args:
-        name: The name of the counter.
-        description: Human readable description of the metric.
-        unit: Unit of the metric values.
-        value_type: The type of values being recorded by the metric.
-        is_bidirectional: Set to true to allow negative inputs.
-        label_keys: list of keys for the labels with dynamic values.
-            Order of the list is important as the same order must be used
-            on recording when suppling values for these labels.
-        span_context: The `SpanContext` that identifies the `Span`
-            that the metric is associated with.
-
-    Returns: A new counter metric for values of the given value_type.
-    """
+        Args:
+            name: The name of the counter.
+            description: Human-readable description of the metric.
+            unit: Unit of the metric values.
+            value_type: The type of values being recorded by the metric.
+            label_keys: The keys for the labels with dynamic values.
+                Order of the tuple is important as the same order must be used
+                on recording when suppling values for these labels.
+            enabled: Whether to report the metric by default.
+            monotonic: Whether to only allow non-negative values.
+
+        Returns: A new ``metric_kind`` metric with values of ``value_type``.
+        """
 
+# Once https://github.com/python/mypy/issues/7092 is resolved,
+# the following type definition should be replaced with
+# from opentelemetry.util.loader import ImplementationFactory
+ImplementationFactory = Callable[
+    [Type[Meter]], Optional[Meter]
+]
 
-def create_gauge(
-    name: str,
-    description: str,
-    unit: str,
-    value_type: Union[Type[float], Type[int]],
-    is_unidirectional: bool = False,
-    label_keys: List[str] = None,
-    span_context: SpanContext = None,
-) -> Union["FloatGauge", "IntGauge"]:
-    """Creates a gauge metric with type value_type.
+_METER = None
+_METER_FACTORY = None
 
-    By default, gauge values can go both up and down (bidirectional). The API
-    allows for an optional unidirectional flag, in which when set will reject
-    descending update values.
+def meter() -> Meter:
+    """Gets the current global :class:`~.Meter` object.
 
-    Args:
-        name: The name of the gauge.
-        description: Human readable description of the metric.
-        unit: Unit of the metric values.
-        value_type: The type of values being recorded by the metric.
-        is_unidirectional: Set to true to reject negative inputs.
-        label_keys: list of keys for the labels with dynamic values.
-            Order of the list is important as the same order must be used
-            on recording when suppling values for these labels.
-        span_context: The `SpanContext` that identifies the `Span`
-            that the metric is associated with.
-
-    Returns: A new gauge metric for values of the given value_type.
+    If there isn't one set yet, a default will be loaded.
     """
+    global _METER, _METER_FACTORY  # pylint:disable=global-statement
+
+    if _METER is None:
+        # pylint:disable=protected-access
+        _METER = loader._load_impl(Meter, _METER_FACTORY)
+        del _METER_FACTORY
 
+    return _METER
 
-def create_measure(
-    name: str,
-    description: str,
-    unit: str,
-    value_type: Union[Type[float], Type[int]],
-    is_non_negative: bool = False,
-    label_keys: List[str] = None,
-    span_context: SpanContext = None,
-) -> Union["FloatMeasure", "IntMeasure"]:
-    """Creates a measure metric with type value_type.
 
-    Measure metrics represent raw statistics that are recorded. As an option,
-    measure metrics can be declared as non-negative. The API will reject
-    negative metric events for non-negative measures.
+def set_preferred_meter_implementation(
+    factory: ImplementationFactory
+) -> None:
+    """Set the factory to be used to create the meter.
+
+    See :mod:`opentelemetry.util.loader` for details.
+
+    This function may not be called after a meter is already loaded.
 
     Args:
-        name: The name of the measure.
-        description: Human readable description of the metric.
-        unit: Unit of the metric values.
-        value_type: The type of values being recorded by the metric.
-        is_non_negative: Set to true to reject negative inputs.
-        label_keys: list of keys for the labels with dynamic values.
-            Order of the list is important as the same order must be used
-            on recording when suppling values for these labels.
-        span_context: The `SpanContext` that identifies the `Span`
-            that the metric is associated with.
-
-    Returns: A new measure metric for values of the given value_type.
+        factory: Callback that should create a new :class:`Meter` instance.
     """
+    global _METER, _METER_FACTORY  # pylint:disable=global-statement
+
+    if _METER:
+        raise RuntimeError("Meter already loaded.")
+
+    _METER_FACTORY = factory
 
 
 class Metric(ABC):
     """Base class for various types of metrics.
 
     Metric class that inherit from this class are specialized with the type of
-    time series that the metric holds.
+    handle that the metric holds.
     """
 
     @abstractmethod
-    def get_handle(self, label_values: List[str]) -> "object":
+    def get_handle(self, label_values: Tuple[str]) -> "MetricHandle":
         """Gets a handle, used for repeated-use of metrics instruments.
 
         Handles are useful to reduce the cost of repeatedly recording a metric
@@ -178,60 +156,68 @@ def get_handle(self, label_values: List[str]) -> "object":
         a value was not provided are permitted.
 
         Args:
-            label_values: A list of label values that will be associated
-                with the return handle.
+            label_values: Values to associate with the returned handle.
         """
 
-    def remove_handle(self, label_values: List[str]) -> None:
+    def remove_handle(self, label_values: Tuple[str]) -> None:
         """Removes the handle from the Metric, if present.
 
         The handle with matching label values will be removed.
 
         args:
-            label_values: The list of label values to match against.
+            label_values: The label values to match against.
         """
 
     def clear(self) -> None:
         """Removes all handles from the `Metric`."""
 
 
-class FloatCounter(Metric):
-    """A counter type metric that holds float values."""
-
-    def get_handle(self, label_values: List[str]) -> "CounterHandle":
-        """Gets a `CounterHandle` with a float value."""
+class Counter(Metric):
+    """A counter type metric that expresses the computation of a sum."""
 
+    def get_handle(self, label_values: Tuple[str]) -> "CounterHandle":
+        """Gets a `CounterHandle`."""
 
-class IntCounter(Metric):
-    """A counter type metric that holds int values."""
 
-    def get_handle(self, label_values: List[str]) -> "CounterHandle":
-        """Gets a `CounterHandle` with an int value."""
+class Gauge(Metric):
+    """A gauge type metric that expresses a pre-calculated value.
+
+    Gauge metrics have a value that is either `Set()` by explicit
+    instrumentation or observed through a callback. This kind of metric
+    should be used when the metric cannot be expressed as a sum or because
+    the measurement interval is arbitrary.
+    """
 
+    def get_handle(self, label_values: Tuple[str]) -> "GaugeHandle":
+        """Gets a `GaugeHandle`."""
 
-class FloatGauge(Metric):
-    """A gauge type metric that holds float values."""
 
-    def get_handle(self, label_values: List[str]) -> "GaugeHandle":
-        """Gets a `GaugeHandle` with a float value."""
+class Measure(Metric):
+    """A measure type metric that represent raw stats that are recorded.
+
+    Measure metrics represent raw statistics that are recorded. By
+    default, measure metrics can accept both positive and negatives.
+    Negative inputs will be discarded when monotonic is True.
+    """
 
+    def get_handle(self, label_values: Tuple[str]) -> "MeasureHandle":
+        """Gets a `MeasureHandle` with a float value."""
 
-class IntGauge(Metric):
-    """A gauge type metric that holds int values."""
 
-    def get_handle(self, label_values: List[str]) -> "GaugeHandle":
-        """Gets a `GaugeHandle` with an int value."""
+class MetricHandle:
+    """An interface for metric handles."""
 
 
-class FloatMeasure(Metric):
-    """A measure type metric that holds float values."""
+class CounterHandle(MetricHandle):
+    def add(self, value: "ValueType") -> None:
+        """Increases the value of the handle by `value`"""
 
-    def get_handle(self, label_values: List[str]) -> "MeasureHandle":
-        """Gets a `MeasureHandle` with a float value."""
 
+class GaugeHandle(MetricHandle):
+    def set(self, value: "ValueType") -> None:
+        """Sets the current value of the handle to `value`."""
 
-class IntMeasure(Metric):
-    """A measure type metric that holds int values."""
 
-    def get_handle(self, label_values: List[str]) -> "MeasureHandle":
-        """Gets a `MeasureHandle` with an int value."""
+class MeasureHandle(MetricHandle):
+    def record(self, value: "ValueType") -> None:
+        """Records the given `value` to this handle."""

opentelemetry-api/src/opentelemetry/metrics/handle.py → opentelemetry-api/tests/metrics/__init__.py

@@ -11,23 +11,3 @@
 # 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 typing
-
-
-class CounterHandle:
-    def add(self, value: typing.Union[float, int]) -> None:
-        """Adds the given value to the current value.
-
-        The input value cannot be negative if not bidirectional.
-        """
-
-
-class GaugeHandle:
-    def set(self, value: typing.Union[float, int]) -> None:
-        """Sets the current value to the given value. Can be negative."""
-
-
-class MeasureHandle:
-    def record(self, value: typing.Union[float, int]) -> None:
-        """Records the given value to this measure."""