Move Metrics API behind internal package

Author: aabmass

.github/workflows/test.yml

@@ -10,7 +10,7 @@ env:
   # Otherwise, set variable to the commit of your branch on
   # opentelemetry-python-contrib which is compatible with these Core repo
   # changes.
-  CONTRIB_REPO_SHA: 4cfca481f8e2c8af5f7cfd032997fac692995f67
+  CONTRIB_REPO_SHA: 008cd2370dcd3e87cca8c0ddbb0b820681fd7346
   # This is needed because we do not clone the core repo in contrib builds anymore.
   # When running contrib builds as part of core builds, we use actions/checkout@v2 which
   # does not set an environment variable (simply just runs tox), which is different when

CHANGELOG.md

@@ -7,8 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/open-telemetry/opentelemetry-python/compare/v1.11.1-0.30b1...HEAD)
 
-## [1.11.1-0.30b1](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v1.11.1-0.30b1) - 2022-04-21
+- Move Metrics API behind internal package
+  ([#2651](https://github.com/open-telemetry/opentelemetry-python/pull/2651))
 
+## [1.11.1-0.30b1](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v1.11.1-0.30b1) - 2022-04-21
 
 - Add parameter to MetricReader constructor to select aggregation per instrument kind
   ([#2638](https://github.com/open-telemetry/opentelemetry-python/pull/2638))

docs/api/metrics.instrument.rst

@@ -8,13 +8,8 @@ opentelemetry._metrics package
 
    Once metrics become stable, this package will be be renamed to ``opentelemetry.metrics``.
 
-Submodules
-----------
-
 .. toctree::
 
-   metrics.instrument
-   metrics.observation
 
 Module contents
 ---------------

docs/api/metrics.observation.rst

@@ -97,9 +97,6 @@
 # https://github.com/sphinx-doc/sphinx/pull/3744
 nitpick_ignore = [
     ("py:class", "ValueT"),
-    ("py:class", "MetricT"),
-    ("py:class", "InstrumentT"),
-    ("py:obj", "opentelemetry._metrics.instrument.InstrumentT"),
     # Even if wrapt is added to intersphinx_mapping, sphinx keeps failing
     # with "class reference target not found: ObjectProxy".
     ("py:class", "ObjectProxy"),
@@ -142,24 +139,7 @@
     "examples/error_handler/error_handler_1",
 ]
 
-_exclude_members = [
-    "_ProxyObservableUpDownCounter",
-    "_ProxyHistogram",
-    "_ProxyObservableGauge",
-    "_ProxyInstrument",
-    "_ProxyAsynchronousInstrument",
-    "_ProxyCounter",
-    "_ProxyUpDownCounter",
-    "_ProxyObservableCounter",
-    "_ProxyObservableGauge",
-    "_abc_impl",
-    "_Adding",
-    "_Grouping",
-    "_Monotonic",
-    "_NonMonotonic",
-    "Synchronous",
-    "Asynchronous",
-]
+_exclude_members = ["_abc_impl"]
 
 autodoc_default_options = {
     "members": True,

docs/api/metrics.rst

@@ -1,7 +1,10 @@
 from typing import Iterable
 
-from opentelemetry._metrics import get_meter_provider, set_meter_provider
-from opentelemetry._metrics.observation import Observation
+from opentelemetry._metrics import (
+    Observation,
+    get_meter_provider,
+    set_meter_provider,
+)
 from opentelemetry.exporter.otlp.proto.grpc._metric_exporter import (
     OTLPMetricExporter,
 )

docs/conf.py

@@ -17,8 +17,11 @@
 
 from typing import Iterable
 
-from opentelemetry._metrics import get_meter_provider, set_meter_provider
-from opentelemetry._metrics.observation import Observation
+from opentelemetry._metrics import (
+    Observation,
+    get_meter_provider,
+    set_meter_provider,
+)
 from opentelemetry.sdk._metrics import MeterProvider
 from opentelemetry.sdk._metrics.export import (
     ConsoleMetricExporter,

docs/examples/metrics/example.py

@@ -0,0 +1,122 @@
+# 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.
+
+"""
+The OpenTelemetry metrics API  describes the classes used to generate
+metrics.
+
+The :class:`.MeterProvider` provides users access to the :class:`.Meter` which in
+turn is used to create :class:`.Instrument` objects. The :class:`.Instrument` objects are
+used to record measurements.
+
+This module provides abstract (i.e. unimplemented) classes required for
+metrics, and a concrete no-op implementation :class:`.NoOpMeter` that allows applications
+to use the API package alone without a supporting implementation.
+
+To get a meter, you need to provide the package name from which you are
+calling the meter APIs to OpenTelemetry by calling `MeterProvider.get_meter`
+with the calling instrumentation name and the version of your package.
+
+The following code shows how to obtain a meter using the global :class:`.MeterProvider`::
+
+    from opentelemetry._metrics import get_meter
+
+    meter = get_meter("example-meter")
+    counter = meter.create_counter("example-counter")
+
+.. versionadded:: 1.10.0
+"""
+
+from opentelemetry._metrics._internal import (
+    Meter,
+    MeterProvider,
+    NoOpMeter,
+    NoOpMeterProvider,
+    get_meter,
+    get_meter_provider,
+    set_meter_provider,
+)
+from opentelemetry._metrics._internal.instrument import (
+    Asynchronous,
+    CallbackT,
+    Counter,
+    Histogram,
+    Instrument,
+    NoOpCounter,
+    NoOpHistogram,
+    NoOpObservableCounter,
+    NoOpObservableGauge,
+    NoOpObservableUpDownCounter,
+    NoOpUpDownCounter,
+    ObservableCounter,
+    ObservableGauge,
+    ObservableUpDownCounter,
+    Synchronous,
+    UpDownCounter,
+)
+from opentelemetry._metrics._internal.observation import Observation
+
+for obj in [
+    Counter,
+    Synchronous,
+    Asynchronous,
+    get_meter_provider,
+    get_meter,
+    Histogram,
+    Meter,
+    MeterProvider,
+    Instrument,
+    NoOpCounter,
+    NoOpHistogram,
+    NoOpMeter,
+    NoOpMeterProvider,
+    NoOpObservableCounter,
+    NoOpObservableGauge,
+    NoOpObservableUpDownCounter,
+    NoOpUpDownCounter,
+    ObservableCounter,
+    ObservableGauge,
+    ObservableUpDownCounter,
+    Observation,
+    set_meter_provider,
+    UpDownCounter,
+]:
+    obj.__module__ = "opentelemetry._metrics"
+
+__all__ = [
+    "MeterProvider",
+    "NoOpMeterProvider",
+    "Meter",
+    "Counter",
+    "NoOpCounter",
+    "UpDownCounter",
+    "NoOpUpDownCounter",
+    "Histogram",
+    "NoOpHistogram",
+    "ObservableCounter",
+    "NoOpObservableCounter",
+    "ObservableUpDownCounter",
+    "Instrument",
+    "Synchronous",
+    "Asynchronous",
+    "NoOpObservableGauge",
+    "ObservableGauge",
+    "NoOpObservableUpDownCounter",
+    "get_meter",
+    "get_meter_provider",
+    "set_meter_provider",
+    "Observation",
+    "CallbackT",
+    "NoOpMeter",
+]

docs/getting_started/metrics_example.py

@@ -47,7 +47,7 @@
 from threading import Lock
 from typing import List, Optional, Sequence, Set, Tuple, Union, cast
 
-from opentelemetry._metrics.instrument import (
+from opentelemetry._metrics._internal.instrument import (
     CallbackT,
     Counter,
     Histogram,
@@ -77,7 +77,7 @@
 _logger = getLogger(__name__)
 
 
-ProxyInstrumentT = Union[
+_ProxyInstrumentT = Union[
     _ProxyCounter,
     _ProxyHistogram,
     _ProxyObservableCounter,
@@ -279,9 +279,8 @@ def create_observable_counter(
     ) -> ObservableCounter:
         """Creates an `ObservableCounter` instrument
 
-        An observable counter observes a monotonically increasing count by
-        calling provided callbacks which returns multiple
-        :class:`~opentelemetry._metrics.observation.Observation`.
+        An observable counter observes a monotonically increasing count by calling provided
+        callbacks which returns multiple :class:`~opentelemetry._metrics.Observation`.
 
         For example, an observable counter could be used to report system CPU
         time periodically. Here is a basic implementation::
@@ -319,9 +318,8 @@ def cpu_time_callback() -> Iterable[Observation]:
                         yield Observation(int(states[1]) // 100, {"cpu": cpu, "state": "nice"})
                         # ... other states
 
-        Alternatively, you can pass a sequence of generators directly instead
-        of a sequence of callbacks, which each should return iterables of
-        :class:`~opentelemetry._metrics.observation.Observation`::
+        Alternatively, you can pass a sequence of generators directly instead of a sequence of
+        callbacks, which each should return iterables of :class:`~opentelemetry._metrics.Observation`::
 
             def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observation]]:
                 while True:
@@ -348,10 +346,8 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observat
         Args:
             name: The name of the instrument to be created
             callbacks: A sequence of callbacks that return an iterable of
-                :class:`~opentelemetry._metrics.observation.Observation`.
-                Alternatively, can be a sequence of generators that each yields
-                iterables of
-                :class:`~opentelemetry._metrics.observation.Observation`.
+                :class:`~opentelemetry._metrics.Observation`. Alternatively, can be a sequence of generators that each
+                yields iterables of :class:`~opentelemetry._metrics.Observation`.
             unit: The unit for observations this instrument reports. For
                 example, ``By`` for bytes. UCUM units are recommended.
             description: A description for this instrument and what it measures.
@@ -364,7 +360,7 @@ def create_histogram(
         unit: str = "",
         description: str = "",
     ) -> Histogram:
-        """Creates a `opentelemetry._metrics.instrument.Histogram` instrument
+        """Creates a :class:`~opentelemetry._metrics.Histogram` instrument
 
         Args:
             name: The name of the instrument to be created
@@ -386,9 +382,8 @@ def create_observable_gauge(
         Args:
             name: The name of the instrument to be created
             callbacks: A sequence of callbacks that return an iterable of
-                :class:`~opentelemetry._metrics.observation.Observation`.
-                Alternatively, can be a generator that yields iterables of
-                :class:`~opentelemetry._metrics.observation.Observation`.
+                :class:`~opentelemetry._metrics.Observation`. Alternatively, can be a generator that yields iterables
+                of :class:`~opentelemetry._metrics.Observation`.
             unit: The unit for observations this instrument reports. For
                 example, ``By`` for bytes. UCUM units are recommended.
             description: A description for this instrument and what it measures.
@@ -407,9 +402,8 @@ def create_observable_up_down_counter(
         Args:
             name: The name of the instrument to be created
             callbacks: A sequence of callbacks that return an iterable of
-                :class:`~opentelemetry._metrics.observation.Observation`.
-                Alternatively, can be a generator that yields iterables of
-                :class:`~opentelemetry._metrics.observation.Observation`.
+                :class:`~opentelemetry._metrics.Observation`. Alternatively, can be a generator that yields iterables
+                of :class:`~opentelemetry._metrics.Observation`.
             unit: The unit for observations this instrument reports. For
                 example, ``By`` for bytes. UCUM units are recommended.
             description: A description for this instrument and what it measures.
@@ -425,7 +419,7 @@ def __init__(
     ) -> None:
         super().__init__(name, version=version, schema_url=schema_url)
         self._lock = Lock()
-        self._instruments: List[ProxyInstrumentT] = []
+        self._instruments: List[_ProxyInstrumentT] = []
         self._real_meter: Optional[Meter] = None
 
     def on_set_meter_provider(self, meter_provider: MeterProvider) -> None:
@@ -718,7 +712,7 @@ def get_meter(
     """Returns a `Meter` for use by the given instrumentation library.
 
     This function is a convenience wrapper for
-    opentelemetry.trace.MeterProvider.get_meter.
+    `opentelemetry._metrics.MeterProvider.get_meter`.
 
     If meter_provider is omitted the current configured one is used.
     """