From 6b3621d4b99dd2defb910b3192e11a866d076e9c Mon Sep 17 00:00:00 2001
From: Aaron Abbott <aaronabbott@google.com>
Date: Thu, 28 Oct 2021 21:04:00 +0000
Subject: [PATCH 1/2] Make metrics api/sdk packages private `*._metrics`

---
 docs/api/metrics.instrument.rst                  |  6 +++---
 docs/api/metrics.measurement.rst                 |  6 +++---
 docs/api/metrics.rst                             |  6 +++---
 docs/conf.py                                     |  2 +-
 .../{metrics => _metrics}/__init__.py            | 12 ++++++------
 .../{metrics => _metrics}/instrument.py          |  4 ++--
 .../{metrics => _metrics}/measurement.py         |  0
 .../metrics/integration_test/test_cpu_time.py    |  4 ++--
 .../tests/metrics/test_instruments.py            |  4 ++--
 .../tests/metrics/test_measurement.py            |  2 +-
 opentelemetry-api/tests/metrics/test_meter.py    |  2 +-
 .../tests/metrics/test_meter_provider.py         | 16 +++++++++-------
 .../sdk/{metrics => _metrics}/__init__.py        | 10 +++++-----
 opentelemetry-sdk/tests/metrics/test_metrics.py  |  2 +-
 .../util/src/opentelemetry/test/globals_test.py  |  2 +-
 15 files changed, 40 insertions(+), 38 deletions(-)
 rename opentelemetry-api/src/opentelemetry/{metrics => _metrics}/__init__.py (97%)
 rename opentelemetry-api/src/opentelemetry/{metrics => _metrics}/instrument.py (98%)
 rename opentelemetry-api/src/opentelemetry/{metrics => _metrics}/measurement.py (100%)
 rename opentelemetry-sdk/src/opentelemetry/sdk/{metrics => _metrics}/__init__.py (95%)

diff --git a/docs/api/metrics.instrument.rst b/docs/api/metrics.instrument.rst
index efceaf74c6d..4a678ef07f1 100644
--- a/docs/api/metrics.instrument.rst
+++ b/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:
diff --git a/docs/api/metrics.measurement.rst b/docs/api/metrics.measurement.rst
index 4674169c134..d9b70aa1939 100644
--- a/docs/api/metrics.measurement.rst
+++ b/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:
diff --git a/docs/api/metrics.rst b/docs/api/metrics.rst
index e445a5015e1..fd7acc3ed90 100644
--- a/docs/api/metrics.rst
+++ b/docs/api/metrics.rst
@@ -1,5 +1,5 @@
-opentelemetry.metrics package
-=============================
+opentelemetry._metrics package
+==============================
 
 Submodules
 ----------
@@ -12,4 +12,4 @@ Submodules
 Module contents
 ---------------
 
-.. automodule:: opentelemetry.metrics
+.. automodule:: opentelemetry._metrics
diff --git a/docs/conf.py b/docs/conf.py
index f79b12db0a6..fef6b1d3a9f 100644
--- a/docs/conf.py
+++ b/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"),
diff --git a/opentelemetry-api/src/opentelemetry/metrics/__init__.py b/opentelemetry-api/src/opentelemetry/_metrics/__init__.py
similarity index 97%
rename from opentelemetry-api/src/opentelemetry/metrics/__init__.py
rename to opentelemetry-api/src/opentelemetry/_metrics/__init__.py
index 2cf15cb267e..289f749d513 100644
--- a/opentelemetry-api/src/opentelemetry/metrics/__init__.py
+++ b/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.
diff --git a/opentelemetry-api/src/opentelemetry/metrics/instrument.py b/opentelemetry-api/src/opentelemetry/_metrics/instrument.py
similarity index 98%
rename from opentelemetry-api/src/opentelemetry/metrics/instrument.py
rename to opentelemetry-api/src/opentelemetry/_metrics/instrument.py
index ce93b4ac45c..76838209ebc 100644
--- a/opentelemetry-api/src/opentelemetry/metrics/instrument.py
+++ b/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]
diff --git a/opentelemetry-api/src/opentelemetry/metrics/measurement.py b/opentelemetry-api/src/opentelemetry/_metrics/measurement.py
similarity index 100%
rename from opentelemetry-api/src/opentelemetry/metrics/measurement.py
rename to opentelemetry-api/src/opentelemetry/_metrics/measurement.py
diff --git a/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py b/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py
index a45b6dfc503..96176a58b3e 100644
--- a/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py
+++ b/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.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.
 
diff --git a/opentelemetry-api/tests/metrics/test_instruments.py b/opentelemetry-api/tests/metrics/test_instruments.py
index 05adaa43988..f3a79aec462 100644
--- a/opentelemetry-api/tests/metrics/test_instruments.py
+++ b/opentelemetry-api/tests/metrics/test_instruments.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,
diff --git a/opentelemetry-api/tests/metrics/test_measurement.py b/opentelemetry-api/tests/metrics/test_measurement.py
index 7fcd33d04f9..8791bc1a2fa 100644
--- a/opentelemetry-api/tests/metrics/test_measurement.py
+++ b/opentelemetry-api/tests/metrics/test_measurement.py
@@ -14,7 +14,7 @@
 
 from unittest import TestCase
 
-from opentelemetry.metrics.measurement import Measurement
+from opentelemetry._metrics.measurement import Measurement
 
 
 class TestMeasurement(TestCase):
diff --git a/opentelemetry-api/tests/metrics/test_meter.py b/opentelemetry-api/tests/metrics/test_meter.py
index 5c39526ca62..6834df31f87 100644
--- a/opentelemetry-api/tests/metrics/test_meter.py
+++ b/opentelemetry-api/tests/metrics/test_meter.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.
 
diff --git a/opentelemetry-api/tests/metrics/test_meter_provider.py b/opentelemetry-api/tests/metrics/test_meter_provider.py
index 15c4d7cea71..6d44e236a9b 100644
--- a/opentelemetry-api/tests/metrics/test_meter_provider.py
+++ b/opentelemetry-api/tests/metrics/test_meter_provider.py
@@ -18,9 +18,8 @@
 
 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,
@@ -28,7 +27,7 @@
     get_meter_provider,
     set_meter_provider,
 )
-from opentelemetry.metrics.instrument import (
+from opentelemetry._metrics.instrument import (
     _ProxyCounter,
     _ProxyHistogram,
     _ProxyObservableCounter,
@@ -36,6 +35,7 @@
     _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"
diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/__init__.py
similarity index 95%
rename from opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py
rename to opentelemetry-sdk/src/opentelemetry/sdk/_metrics/__init__.py
index 384e52512a9..1f306f68b31 100644
--- a/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py
+++ b/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/__init__.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,
diff --git a/opentelemetry-sdk/tests/metrics/test_metrics.py b/opentelemetry-sdk/tests/metrics/test_metrics.py
index 828d66821d4..b473f4f69fb 100644
--- a/opentelemetry-sdk/tests/metrics/test_metrics.py
+++ b/opentelemetry-sdk/tests/metrics/test_metrics.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,
diff --git a/tests/util/src/opentelemetry/test/globals_test.py b/tests/util/src/opentelemetry/test/globals_test.py
index a2626116b13..f5e4ddaea36 100644
--- a/tests/util/src/opentelemetry/test/globals_test.py
+++ b/tests/util/src/opentelemetry/test/globals_test.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
 

From 09d8c25facfbe308579455f938dcb277505878f4 Mon Sep 17 00:00:00 2001
From: Aaron Abbott <aaronabbott@google.com>
Date: Thu, 28 Oct 2021 21:22:10 +0000
Subject: [PATCH 2/2] add warning

---
 docs/api/metrics.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/api/metrics.rst b/docs/api/metrics.rst
index fd7acc3ed90..d4e29b624bc 100644
--- a/docs/api/metrics.rst
+++ b/docs/api/metrics.rst
@@ -1,6 +1,13 @@
 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
 ----------