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

@@ -27,147 +27,44 @@
 
 """
 from abc import ABC, abstractmethod
-from typing import Dict, List, Tuple, Type, Union
+from typing import Callable, Optional, Sequence, Tuple, Type, TypeVar
 
-from opentelemetry.metrics.handle import (
-    CounterHandle,
-    GaugeHandle,
-    MeasureHandle,
-)
-from opentelemetry.trace import SpanContext
+from opentelemetry.util import loader
 
+ValueT = TypeVar("ValueT", int, float)
 
-# pylint: disable=unused-argument
-class Meter:
-    """An interface to allow the recording of metrics.
-
-    `Metric` s are used for recording pre-defined aggregation (gauge and
-    counter), or raw values (measure) in which the aggregation and labels
-    for the exported metric are deferred.
-    """
-
-    def record_batch(
-        self,
-        label_tuples: Dict[str, str],
-        record_tuples: List[Tuple["Metric", Union[float, int]]],
-    ) -> 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.
-
-        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
-                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.
+class DefaultMetricHandle:
+    """The default MetricHandle.
 
-    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.
+    Used when no MetricHandle implementation is available.
     """
 
 
-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.
+class CounterHandle:
+    def add(self, value: ValueT) -> None:
+        """Increases the value of the handle by ``value``"""
 
-    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.
-
-    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.
-    """
 
+class GaugeHandle:
+    def set(self, value: ValueT) -> None:
+        """Sets the current value of the handle to ``value``."""
 
-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.
-
-    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.
-    """
+class MeasureHandle:
+    def record(self, value: ValueT) -> None:
+        """Records the given ``value`` to this handle."""
 
 
 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: Sequence[str]) -> "object":
         """Gets a handle, used for repeated-use of metrics instruments.
 
         Handles are useful to reduce the cost of repeatedly recording a metric
@@ -178,60 +75,150 @@ 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:
-        """Removes the handle from the Metric, if present.
 
-        The handle with matching label values will be removed.
+class DefaultMetric(Metric):
+    """The default Metric used when no Metric implementation is available."""
 
-        args:
-            label_values: The list of label values to match against.
-        """
+    def get_handle(self, label_values: Sequence[str]) -> "DefaultMetricHandle":
+        return DefaultMetricHandle()
 
-    def clear(self) -> None:
-        """Removes all handles from the `Metric`."""
 
+class Counter(Metric):
+    """A counter type metric that expresses the computation of a sum."""
 
-class FloatCounter(Metric):
-    """A counter type metric that holds float values."""
+    def get_handle(self, label_values: Sequence[str]) -> "CounterHandle":
+        """Gets a `CounterHandle`."""
+        return CounterHandle()
 
-    def get_handle(self, label_values: List[str]) -> "CounterHandle":
-        """Gets a `CounterHandle` with a float value."""
 
+class Gauge(Metric):
+    """A gauge type metric that expresses a pre-calculated value.
 
-class IntCounter(Metric):
-    """A counter type metric that holds int values."""
+    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: List[str]) -> "CounterHandle":
-        """Gets a `CounterHandle` with an int value."""
+    def get_handle(self, label_values: Sequence[str]) -> "GaugeHandle":
+        """Gets a `GaugeHandle`."""
+        return GaugeHandle()
 
 
-class FloatGauge(Metric):
-    """A gauge type metric that holds float values."""
+class Measure(Metric):
+    """A measure type metric that represent raw stats that are recorded.
 
-    def get_handle(self, label_values: List[str]) -> "GaugeHandle":
-        """Gets a `GaugeHandle` with a float value."""
+    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: Sequence[str]) -> "MeasureHandle":
+        """Gets a `MeasureHandle` with a float value."""
+        return MeasureHandle()
 
-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."""
+MetricT = TypeVar("MetricT", Counter, Gauge, Measure)
 
 
-class FloatMeasure(Metric):
-    """A measure type metric that holds float values."""
+# pylint: disable=unused-argument
+class Meter:
+    """An interface to allow the recording of metrics.
 
-    def get_handle(self, label_values: List[str]) -> "MeasureHandle":
-        """Gets a `MeasureHandle` with a float value."""
+    `Metric` s are used for recording pre-defined aggregation (gauge and
+    counter), or raw values (measure) in which the aggregation and labels
+    for the exported metric are deferred.
+    """
+
+    def record_batch(
+        self,
+        label_values: Sequence[str],
+        record_tuples: Sequence[Tuple["Metric", ValueT]],
+    ) -> 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 metric and handles that
+        match the key-value pairs in the label tuples.
+
+        Args:
+            label_values: The values that will be matched against to record for
+                the handles under each metric that has those labels.
+            record_tuples: A sequence of pairs of `Metric` s and the
+                corresponding value to record for that metric.
+        """
+
+    def create_metric(
+        self,
+        name: str,
+        description: str,
+        unit: str,
+        value_type: Type[ValueT],
+        metric_type: Type[MetricT],
+        label_keys: Sequence[str] = None,
+        enabled: bool = True,
+        monotonic: bool = False,
+    ) -> "Metric":
+        """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.
+            metric_type: The type of metric being created.
+            label_keys: The keys for the labels with dynamic values.
+                Order of the sequence 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_type`` metric with values of ``value_type``.
+        """
+        # pylint: disable=no-self-use
+        return DefaultMetric()
+
+
+# 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]]
+
+_METER = None
+_METER_FACTORY = None
+
+
+def meter() -> Meter:
+    """Gets the current global :class:`~.Meter` object.
+
+    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 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:
+        factory: Callback that should create a new :class:`Meter` instance.
+    """
+    global _METER, _METER_FACTORY  # pylint:disable=global-statement
 
-class IntMeasure(Metric):
-    """A measure type metric that holds int values."""
+    if _METER:
+        raise RuntimeError("Meter already loaded.")
 
-    def get_handle(self, label_values: List[str]) -> "MeasureHandle":
-        """Gets a `MeasureHandle` with an int value."""
+    _METER_FACTORY = factory

opentelemetry-api/src/opentelemetry/metrics/examples/pre_aggregated.py → opentelemetry-api/tests/metrics/__init__.py

@@ -11,22 +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.
-
-# pylint: skip-file
-from opentelemetry import metrics
-
-METER = metrics.Meter()
-COUNTER = METER.create_counter(
-    "sum numbers",
-    "sum numbers over time",
-    "number",
-    metrics.ValueType.FLOAT,
-    ["environment"],
-)
-
-# Metrics sent to some exporter
-METRIC_TESTING = COUNTER.get_handle("Testing")
-METRIC_STAGING = COUNTER.get_handle("Staging")
-
-for i in range(100):
-    METRIC_STAGING.add(i)