Make metrics api/sdk packages private *._metrics (#2249)

* Make metrics api/sdk packages private `*._metrics`

* add warning

Author: aabmass

docs/api/metrics.instrument.rst

@@ -1,7 +1,7 @@
-opentelemetry.metrics.instrument
-================================
+opentelemetry._metrics.instrument
+=================================
 
-.. automodule:: opentelemetry.metrics.instrument
+.. automodule:: opentelemetry._metrics.instrument
     :members:
     :private-members:
     :undoc-members:

docs/api/metrics.measurement.rst

@@ -1,7 +1,7 @@
-opentelemetry.metrics.measurement
-=================================
+opentelemetry._metrics.measurement
+==================================
 
-.. automodule:: opentelemetry.metrics.measurement
+.. automodule:: opentelemetry._metrics.measurement
     :members:
     :undoc-members:
     :show-inheritance:

docs/api/metrics.rst

@@ -1,5 +1,12 @@
-opentelemetry.metrics package
-=============================
+opentelemetry._metrics package
+==============================
+
+.. warning::
+   OpenTelemetry Python metrics are in an experimental state. The APIs within
+   :mod:`opentelemetry._metrics` are subject to change in minor/patch releases and make no
+   backward compatability guarantees at this time.
+
+   Once metrics become stable, this package will be be renamed to ``opentelemetry.metrics``.
 
 Submodules
 ----------
@@ -12,4 +19,4 @@ Submodules
 Module contents
 ---------------
 
-.. automodule:: opentelemetry.metrics
+.. automodule:: opentelemetry._metrics

docs/conf.py

@@ -99,7 +99,7 @@
     ("py:class", "ValueT"),
     ("py:class", "MetricT"),
     ("py:class", "InstrumentT"),
-    ("py:obj", "opentelemetry.metrics.instrument.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"),

opentelemetry-api/src/opentelemetry/metrics/__init__.py renamed to opentelemetry-api/src/opentelemetry/_metrics/__init__.py

@@ -28,8 +28,7 @@
 from threading import Lock
 from typing import List, Optional, cast
 
-from opentelemetry.environment_variables import OTEL_PYTHON_METER_PROVIDER
-from opentelemetry.metrics.instrument import (
+from opentelemetry._metrics.instrument import (
     Counter,
     DefaultCounter,
     DefaultHistogram,
@@ -50,6 +49,7 @@
     _ProxyObservableUpDownCounter,
     _ProxyUpDownCounter,
 )
+from opentelemetry.environment_variables import OTEL_PYTHON_METER_PROVIDER
 from opentelemetry.util._once import Once
 from opentelemetry.util._providers import _load_provider
 
@@ -147,7 +147,7 @@ def create_observable_counter(
 
         An observable counter observes a monotonically increasing count by
         calling a provided callback which returns multiple
-        :class:`~opentelemetry.metrics.measurement.Measurement`.
+        :class:`~opentelemetry._metrics.measurement.Measurement`.
 
         For example, an observable counter could be used to report system CPU
         time periodically. Here is a basic implementation::
@@ -187,7 +187,7 @@ def cpu_time_callback() -> Iterable[Measurement]:
 
         Alternatively, you can pass a generator directly instead of a callback,
         which should return iterables of
-        :class:`~opentelemetry.metrics.measurement.Measurement`::
+        :class:`~opentelemetry._metrics.measurement.Measurement`::
 
             def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Measurement]]:
                 while True:
@@ -214,9 +214,9 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Measurem
         Args:
             name: The name of the instrument to be created
             callback: A callback that returns an iterable of
-                :class:`~opentelemetry.metrics.measurement.Measurement`.
+                :class:`~opentelemetry._metrics.measurement.Measurement`.
                 Alternatively, can be a generator that yields iterables of
-                :class:`~opentelemetry.metrics.measurement.Measurement`.
+                :class:`~opentelemetry._metrics.measurement.Measurement`.
             unit: The unit for measurements this instrument reports. For
                 example, ``By`` for bytes. UCUM units are recommended.
             description: A description for this instrument and what it measures.

opentelemetry-api/src/opentelemetry/metrics/instrument.py renamed to opentelemetry-api/src/opentelemetry/_metrics/instrument.py

@@ -30,8 +30,8 @@
 )
 
 # pylint: disable=unused-import; needed for typing and sphinx
-from opentelemetry import metrics
-from opentelemetry.metrics.measurement import Measurement
+from opentelemetry import _metrics as metrics
+from opentelemetry._metrics.measurement import Measurement
 
 _TInstrumentCallback = Callable[[], Iterable[Measurement]]
 _TInstrumentCallbackGenerator = Generator[Iterable[Measurement], None, None]

opentelemetry-api/src/opentelemetry/metrics/measurement.py renamed to opentelemetry-api/src/opentelemetry/_metrics/measurement.py

@@ -17,8 +17,8 @@
 from typing import Generator, Iterable
 from unittest import TestCase
 
-from opentelemetry.metrics import _DefaultMeter
-from opentelemetry.metrics.measurement import Measurement
+from opentelemetry._metrics import _DefaultMeter
+from opentelemetry._metrics.measurement import Measurement
 
 # FIXME Test that the instrument methods can be called concurrently safely.
 

opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py

@@ -16,8 +16,8 @@
 from inspect import Signature, isabstract, signature
 from unittest import TestCase
 
-from opentelemetry.metrics import Meter, _DefaultMeter
-from opentelemetry.metrics.instrument import (
+from opentelemetry._metrics import Meter, _DefaultMeter
+from opentelemetry._metrics.instrument import (
     Counter,
     DefaultCounter,
     DefaultHistogram,

opentelemetry-api/tests/metrics/test_instruments.py

@@ -14,7 +14,7 @@
 
 from unittest import TestCase
 
-from opentelemetry.metrics.measurement import Measurement
+from opentelemetry._metrics.measurement import Measurement
 
 
 class TestMeasurement(TestCase):

opentelemetry-api/tests/metrics/test_measurement.py

@@ -15,7 +15,7 @@
 
 from unittest import TestCase
 
-from opentelemetry.metrics import Meter
+from opentelemetry._metrics import Meter
 
 # FIXME Test that the meter methods can be called concurrently safely.
 

opentelemetry-api/tests/metrics/test_meter.py

@@ -18,24 +18,24 @@
 
 from pytest import fixture
 
-from opentelemetry import metrics
-from opentelemetry.environment_variables import OTEL_PYTHON_METER_PROVIDER
-from opentelemetry.metrics import (
+from opentelemetry import _metrics as metrics
+from opentelemetry._metrics import (
     _DefaultMeter,
     _DefaultMeterProvider,
     _ProxyMeter,
     _ProxyMeterProvider,
     get_meter_provider,
     set_meter_provider,
 )
-from opentelemetry.metrics.instrument import (
+from opentelemetry._metrics.instrument import (
     _ProxyCounter,
     _ProxyHistogram,
     _ProxyObservableCounter,
     _ProxyObservableGauge,
     _ProxyObservableUpDownCounter,
     _ProxyUpDownCounter,
 )
+from opentelemetry.environment_variables import OTEL_PYTHON_METER_PROVIDER
 from opentelemetry.test.globals_test import (
     MetricsGlobalsTest,
     reset_metrics_globals,
@@ -67,7 +67,9 @@ def test_set_meter_provider(reset_meter_provider):
 
 
 def test_set_meter_provider_calls_proxy_provider(reset_meter_provider):
-    with patch("opentelemetry.metrics._PROXY_METER_PROVIDER") as mock_proxy_mp:
+    with patch(
+        "opentelemetry._metrics._PROXY_METER_PROVIDER"
+    ) as mock_proxy_mp:
         mock_real_mp = Mock()
         set_meter_provider(mock_real_mp)
         mock_proxy_mp.on_set_meter_provider.assert_called_once_with(
@@ -90,9 +92,9 @@ def test_get_meter_provider(reset_meter_provider):
         "os.environ", {OTEL_PYTHON_METER_PROVIDER: "test_meter_provider"}
     ):
 
-        with patch("opentelemetry.metrics._load_provider", Mock()):
+        with patch("opentelemetry._metrics._load_provider", Mock()):
             with patch(
-                "opentelemetry.metrics.cast",
+                "opentelemetry._metrics.cast",
                 Mock(**{"return_value": "test_meter_provider"}),
             ):
                 assert get_meter_provider() == "test_meter_provider"

opentelemetry-api/tests/metrics/test_meter_provider.py

@@ -19,10 +19,10 @@
 from logging import getLogger
 from typing import Optional
 
-from opentelemetry.metrics import Meter as APIMeter
-from opentelemetry.metrics import MeterProvider as APIMeterProvider
-from opentelemetry.metrics import _DefaultMeter
-from opentelemetry.metrics.instrument import (
+from opentelemetry._metrics import Meter as APIMeter
+from opentelemetry._metrics import MeterProvider as APIMeterProvider
+from opentelemetry._metrics import _DefaultMeter
+from opentelemetry._metrics.instrument import (
     Counter,
     Histogram,
     ObservableCounter,
@@ -80,7 +80,7 @@ def create_observable_up_down_counter(
 
 
 class MeterProvider(APIMeterProvider):
-    """See `opentelemetry.metrics.MeterProvider`."""
+    """See `opentelemetry._metrics.MeterProvider`."""
 
     def __init__(
         self,

opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py renamed to opentelemetry-sdk/src/opentelemetry/sdk/_metrics/__init__.py

@@ -17,7 +17,7 @@
 from unittest import TestCase
 from unittest.mock import Mock
 
-from opentelemetry.sdk.metrics import (
+from opentelemetry.sdk._metrics import (
     ConsoleMetricExporter,
     MeterProvider,
     SDKMetricReader,

opentelemetry-sdk/tests/metrics/test_metrics.py

@@ -14,7 +14,7 @@
 
 import unittest
 
-from opentelemetry import metrics as metrics_api
+from opentelemetry import _metrics as metrics_api
 from opentelemetry import trace as trace_api
 from opentelemetry.util._once import Once