Make metrics public

Fixes #2682

CHANGELOG.md

@@ -7,6 +7,8 @@ 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)
 
+- Make metrics components public
+  ([#2684](https://github.com/open-telemetry/opentelemetry-python/pull/2684))
 - Update to semantic conventions v1.11.0
   ([#2669](https://github.com/open-telemetry/opentelemetry-python/pull/2669))
 - Update opentelemetry-proto to v0.17.0

docs/api/metrics.rst

@@ -1,17 +1,10 @@
-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``.
+opentelemetry.metrics package
+=============================
 
 .. toctree::
 
 
 Module contents
 ---------------
 
-.. automodule:: opentelemetry._metrics
+.. automodule:: opentelemetry.metrics

docs/conf.py

@@ -99,11 +99,11 @@
     ("py:class", "ValueT"),
     (
         "py:class",
-        "opentelemetry.sdk._metrics._internal.instrument._Synchronous",
+        "opentelemetry.sdk.metrics._internal.instrument._Synchronous",
     ),
     (
         "py:class",
-        "opentelemetry.sdk._metrics._internal.instrument._Asynchronous",
+        "opentelemetry.sdk.metrics._internal.instrument._Asynchronous",
     ),
     # Even if wrapt is added to intersphinx_mapping, sphinx keeps failing
     # with "class reference target not found: ObjectProxy".

docs/examples/metrics/README.rst

@@ -1,11 +1,6 @@
 OpenTelemetry Metrics SDK
 =========================
 
-.. warning::
-   OpenTelemetry Python metrics are in an experimental state. The APIs within
-   :mod:`opentelemetry.sdk._metrics` are subject to change in minor/patch releases and there are no
-   backward compatability guarantees at this time.
-
 Start the Collector locally to see data being exported. Write the following file:
 
 .. code-block:: yaml
@@ -45,4 +40,4 @@ The resulting metrics will appear in the output from the collector and look simi
 
 .. code-block:: sh
 
-TODO
+TODO

docs/examples/metrics/example.py

@@ -1,16 +1,16 @@
 from typing import Iterable
 
-from opentelemetry._metrics import (
+from opentelemetry.exporter.otlp.proto.grpc._metric_exporter import (
+    OTLPMetricExporter,
+)
+from opentelemetry.metrics import (
     Observation,
     get_meter_provider,
     set_meter_provider,
 )
-from opentelemetry._metrics._internal.instrument import CallbackOptions
-from opentelemetry.exporter.otlp.proto.grpc._metric_exporter import (
-    OTLPMetricExporter,
-)
-from opentelemetry.sdk._metrics import MeterProvider
-from opentelemetry.sdk._metrics.export import PeriodicExportingMetricReader
+from opentelemetry.metrics._internal.instrument import CallbackOptions
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
 
 exporter = OTLPMetricExporter(insecure=True)
 reader = PeriodicExportingMetricReader(exporter)

docs/getting_started/metrics_example.py

@@ -17,14 +17,14 @@
 
 from typing import Iterable
 
-from opentelemetry._metrics import (
+from opentelemetry.metrics import (
     CallbackOptions,
     Observation,
     get_meter_provider,
     set_meter_provider,
 )
-from opentelemetry.sdk._metrics import MeterProvider
-from opentelemetry.sdk._metrics.export import (
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import (
     ConsoleMetricExporter,
     PeriodicExportingMetricReader,
 )

docs/sdk/metrics.export.rst

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

docs/sdk/metrics.rst

@@ -1,13 +1,6 @@
-opentelemetry.sdk._metrics package
+opentelemetry.sdk.metrics package
 ==================================
 
-.. warning::
-   OpenTelemetry Python metrics are in an experimental state. The APIs within
-   :mod:`opentelemetry.sdk._metrics` are subject to change in minor/patch releases and there are no
-   backward compatability guarantees at this time.
-
-   Once metrics become stable, this package will be be renamed to ``opentelemetry.sdk.metrics``.
-
 Submodules
 ----------
 
@@ -16,7 +9,7 @@ Submodules
    metrics.export
    metrics.view
 
-.. automodule:: opentelemetry.sdk._metrics
+.. automodule:: opentelemetry.sdk.metrics
     :members:
     :undoc-members:
     :show-inheritance:

docs/sdk/metrics.view.rst

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

exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc/_metric_exporter/__init__.py

@@ -30,14 +30,14 @@
 from opentelemetry.sdk.environment_variables import (
     OTEL_EXPORTER_OTLP_METRICS_INSECURE,
 )
-from opentelemetry.sdk._metrics.export import (
+from opentelemetry.sdk.metrics.export import (
     Gauge,
     Histogram,
     Metric,
     Sum,
 )
 
-from opentelemetry.sdk._metrics.export import (
+from opentelemetry.sdk.metrics.export import (
     MetricExporter,
     MetricExportResult,
     MetricsData,

exporter/opentelemetry-exporter-otlp-proto-grpc/tests/metrics/test_otlp_metrics_exporter.py

@@ -40,7 +40,10 @@
 from opentelemetry.proto.resource.v1.resource_pb2 import (
     Resource as OTLPResource,
 )
-from opentelemetry.sdk._metrics.export import (
+from opentelemetry.sdk.environment_variables import (
+    OTEL_EXPORTER_OTLP_METRICS_INSECURE,
+)
+from opentelemetry.sdk.metrics.export import (
     AggregationTemporality,
     Histogram,
     HistogramDataPoint,
@@ -50,9 +53,6 @@
     ResourceMetrics,
     ScopeMetrics,
 )
-from opentelemetry.sdk.environment_variables import (
-    OTEL_EXPORTER_OTLP_METRICS_INSECURE,
-)
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.util.instrumentation import (
     InstrumentationScope as SDKInstrumentationScope,

exporter/opentelemetry-exporter-prometheus/src/opentelemetry/exporter/prometheus/__init__.py

@@ -31,7 +31,7 @@
 
     from opentelemetry._metrics import get_meter_provider, set_meter_provider
     from opentelemetry.exporter.prometheus import PrometheusMetricReader
-    from opentelemetry.sdk._metrics import MeterProvider
+    from opentelemetry.sdk.metrics import MeterProvider
 
     # Start Prometheus client
     start_http_server(port=8000, addr="localhost")
@@ -77,7 +77,7 @@
 )
 from prometheus_client.core import Metric as PrometheusMetric
 
-from opentelemetry.sdk._metrics.export import (
+from opentelemetry.sdk.metrics.export import (
     Gauge,
     Histogram,
     HistogramDataPoint,

exporter/opentelemetry-exporter-prometheus/tests/test_prometheus_exporter.py

@@ -23,7 +23,7 @@
     PrometheusMetricReader,
     _CustomCollector,
 )
-from opentelemetry.sdk._metrics.export import (
+from opentelemetry.sdk.metrics.export import (
     AggregationTemporality,
     Histogram,
     HistogramDataPoint,

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

@@ -30,15 +30,15 @@
 
 The following code shows how to obtain a meter using the global :class:`.MeterProvider`::
 
-    from opentelemetry._metrics import get_meter
+    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 (
+from opentelemetry.metrics._internal import (
     Meter,
     MeterProvider,
     NoOpMeter,
@@ -47,7 +47,7 @@
     get_meter_provider,
     set_meter_provider,
 )
-from opentelemetry._metrics._internal.instrument import (
+from opentelemetry.metrics._internal.instrument import (
     Asynchronous,
     CallbackOptions,
     CallbackT,
@@ -66,7 +66,7 @@
     Synchronous,
     UpDownCounter,
 )
-from opentelemetry._metrics._internal.observation import Observation
+from opentelemetry.metrics._internal.observation import Observation
 
 for obj in [
     Counter,

opentelemetry-api/src/opentelemetry/_metrics/_internal/__init__.py → opentelemetry-api/src/opentelemetry/metrics/_internal/__init__.py

@@ -32,7 +32,7 @@
 
 The following code shows how to obtain a meter using the global :class:`.MeterProvider`::
 
-    from opentelemetry._metrics import get_meter
+    from opentelemetry.metrics import get_meter
 
     meter = get_meter("example-meter")
     counter = meter.create_counter("example-counter")
@@ -47,7 +47,10 @@
 from threading import Lock
 from typing import List, Optional, Sequence, Set, Tuple, Union, cast
 
-from opentelemetry._metrics._internal.instrument import (
+from opentelemetry.environment_variables import (
+    _OTEL_PYTHON_METER_PROVIDER as OTEL_PYTHON_METER_PROVIDER,
+)
+from opentelemetry.metrics._internal.instrument import (
     CallbackT,
     Counter,
     Histogram,
@@ -68,9 +71,6 @@
     _ProxyObservableUpDownCounter,
     _ProxyUpDownCounter,
 )
-from opentelemetry.environment_variables import (
-    _OTEL_PYTHON_METER_PROVIDER as OTEL_PYTHON_METER_PROVIDER,
-)
 from opentelemetry.util._once import Once
 from opentelemetry.util._providers import _load_provider
 
@@ -280,8 +280,8 @@ def create_observable_counter(
         """Creates an `ObservableCounter` instrument
 
         An observable counter observes a monotonically increasing count by calling provided
-        callbacks which accept a :class:`~opentelemetry._metrics.CallbackOptions` and return
-        multiple :class:`~opentelemetry._metrics.Observation`.
+        callbacks which accept a :class:`~opentelemetry.metrics.CallbackOptions` and return
+        multiple :class:`~opentelemetry.metrics.Observation`.
 
         For example, an observable counter could be used to report system CPU
         time periodically. Here is a basic implementation::
@@ -320,7 +320,7 @@ def cpu_time_callback(options: CallbackOptions) -> Iterable[Observation]:
                         # ... 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`::
+        callbacks, which each should return iterables of :class:`~opentelemetry.metrics.Observation`::
 
             def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observation]]:
                 # accept options sent in from OpenTelemetry
@@ -347,7 +347,7 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observat
                 description="CPU time"
             )
 
-        The :class:`~opentelemetry._metrics.CallbackOptions` contain a timeout which the
+        The :class:`~opentelemetry.metrics.CallbackOptions` contain a timeout which the
         callback should respect. For example if the callback does asynchronous work, like
         making HTTP requests, it should respect the timeout::
 
@@ -359,8 +359,8 @@ def scrape_http_callback(options: CallbackOptions) -> Iterable[Observation]:
         Args:
             name: The name of the instrument to be created
             callbacks: A sequence of callbacks that return an iterable of
-                :class:`~opentelemetry._metrics.Observation`. Alternatively, can be a sequence of generators that each
-                yields iterables of :class:`~opentelemetry._metrics.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.
@@ -373,7 +373,7 @@ def create_histogram(
         unit: str = "",
         description: str = "",
     ) -> Histogram:
-        """Creates a :class:`~opentelemetry._metrics.Histogram` instrument
+        """Creates a :class:`~opentelemetry.metrics.Histogram` instrument
 
         Args:
             name: The name of the instrument to be created
@@ -395,8 +395,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`. Alternatively, can be a generator that yields iterables
-                of :class:`~opentelemetry._metrics.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.
@@ -415,8 +415,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`. Alternatively, can be a generator that yields iterables
-                of :class:`~opentelemetry._metrics.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.
@@ -725,7 +725,7 @@ def get_meter(
     """Returns a `Meter` for use by the given instrumentation library.
 
     This function is a convenience wrapper for
-    `opentelemetry._metrics.MeterProvider.get_meter`.
+    `opentelemetry.metrics.MeterProvider.get_meter`.
 
     If meter_provider is omitted the current configured one is used.
     """

opentelemetry-api/src/opentelemetry/_metrics/_internal/instrument.py → opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py

@@ -33,8 +33,8 @@
 )
 
 # pylint: disable=unused-import; needed for typing and sphinx
-from opentelemetry import _metrics as metrics
-from opentelemetry._metrics._internal.observation import Observation
+from opentelemetry import metrics
+from opentelemetry.metrics._internal.observation import Observation
 from opentelemetry.util.types import Attributes
 
 _logger = getLogger(__name__)

opentelemetry-api/src/opentelemetry/util/_providers.py

@@ -19,7 +19,7 @@
 from pkg_resources import iter_entry_points
 
 if TYPE_CHECKING:
-    from opentelemetry._metrics import MeterProvider
+    from opentelemetry.metrics import MeterProvider
     from opentelemetry.trace import TracerProvider
 
 Provider = TypeVar("Provider", "TracerProvider", "MeterProvider")

opentelemetry-api/tests/metrics/test_instruments.py

@@ -16,7 +16,7 @@
 from inspect import Signature, isabstract, signature
 from unittest import TestCase
 
-from opentelemetry._metrics import (
+from opentelemetry.metrics import (
     Counter,
     Histogram,
     Instrument,