Merge branch 'main' into exporter-metrics

Author: xrmx

.github/workflows/check-links.yml

@@ -4,11 +4,13 @@ on:
     branches: [ main ]
     paths:
       - '**/*.md'
+      - '**/*.rst'
       - '.github/workflows/check-links.yml'
       - '.github/workflows/check_links_config.json'
   pull_request:
     paths:
       - '**/*.md'
+      - '**/*.rst'
       - '.github/workflows/check-links.yml'
       - '.github/workflows/check_links_config.json'
 
@@ -34,6 +36,7 @@ jobs:
         with:
           files: |
             **/*.md
+            **/*.rst
 
       - name: Install markdown-link-check
         if: steps.changed-files.outputs.any_changed == 'true'

CHANGELOG.md

@@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Fix incorrect code example in `create_tracer()` docstring
+  ([#5072](https://github.com/open-telemetry/opentelemetry-python/issues/5072))
+- `opentelemetry-sdk`: add `load_entry_point` shared utility to declarative file configuration for loading plugins via entry points; refactor propagator loading to use it
+  ([#5093](https://github.com/open-telemetry/opentelemetry-python/pull/5093))
 - `opentelemetry-sdk`: fix YAML structure injection via environment variable substitution in declarative file configuration; values containing newlines are now emitted as quoted YAML scalars per spec requirement
   ([#5091](https://github.com/open-telemetry/opentelemetry-python/pull/5091))
 - `opentelemetry-sdk`: Add `create_logger_provider`/`configure_logger_provider` to declarative file configuration, enabling LoggerProvider instantiation from config files without reading env vars

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py

@@ -15,11 +15,39 @@
 from __future__ import annotations
 
 import logging
-from typing import Optional
+from typing import Optional, Type
+
+from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.util._importlib_metadata import entry_points
 
 _logger = logging.getLogger(__name__)
 
 
+def load_entry_point(group: str, name: str) -> Type:
+    """Load a plugin class from an entry point group by name.
+
+    Returns the loaded class — callers are responsible for instantiation
+    with whatever arguments their config requires.
+
+    Raises:
+        ConfigurationError: If the entry point is not found or fails to load.
+    """
+    try:
+        ep = next(iter(entry_points(group=group, name=name)), None)
+        if ep is None:
+            raise ConfigurationError(
+                f"Plugin '{name}' not found in group '{group}'. "
+                "Make sure the package providing this plugin is installed."
+            )
+        return ep.load()
+    except ConfigurationError:
+        raise
+    except Exception as exc:
+        raise ConfigurationError(
+            f"Failed to load plugin '{name}' from group '{group}': {exc}"
+        ) from exc
+
+
 def _parse_headers(
     headers: Optional[list],
     headers_list: Optional[str],

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_propagator.py

@@ -20,7 +20,7 @@
 from opentelemetry.propagate import set_global_textmap
 from opentelemetry.propagators.composite import CompositePropagator
 from opentelemetry.propagators.textmap import TextMapPropagator
-from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._common import load_entry_point
 from opentelemetry.sdk._configuration.models import (
     Propagator as PropagatorConfig,
 )
@@ -30,28 +30,11 @@
 from opentelemetry.trace.propagation.tracecontext import (
     TraceContextTextMapPropagator,
 )
-from opentelemetry.util._importlib_metadata import entry_points
 
 
 def _load_entry_point_propagator(name: str) -> TextMapPropagator:
-    """Load a propagator by name from the opentelemetry_propagator entry point group."""
-    try:
-        ep = next(
-            iter(entry_points(group="opentelemetry_propagator", name=name)),
-            None,
-        )
-        if not ep:
-            raise ConfigurationError(
-                f"Propagator '{name}' not found. "
-                "It may not be installed or may be misspelled."
-            )
-        return ep.load()()
-    except ConfigurationError:
-        raise
-    except Exception as exc:
-        raise ConfigurationError(
-            f"Failed to load propagator '{name}': {exc}"
-        ) from exc
+    """Load and instantiate a propagator by name."""
+    return load_entry_point("opentelemetry_propagator", name)()
 
 
 def _propagators_from_textmap_config(

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py

@@ -18,14 +18,14 @@
 from time import time_ns
 from typing import Dict, List, Optional, Sequence
 
-from opentelemetry.metrics import Instrument
 from opentelemetry.sdk.metrics._internal.aggregation import (
     Aggregation,
     AggregationTemporality,
     DefaultAggregation,
     _Aggregation,
     _SumAggregation,
 )
+from opentelemetry.sdk.metrics._internal.instrument import _Instrument
 from opentelemetry.sdk.metrics._internal.measurement import Measurement
 from opentelemetry.sdk.metrics._internal.point import DataPointT
 from opentelemetry.sdk.metrics._internal.view import View
@@ -37,7 +37,7 @@ class _ViewInstrumentMatch:
     def __init__(
         self,
         view: View,
-        instrument: Instrument,
+        instrument: _Instrument,
         instrument_class_aggregation: Dict[type, Aggregation],
     ):
         self._view = view

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/aggregation.py

@@ -35,7 +35,6 @@
     Asynchronous,
     Counter,
     Histogram,
-    Instrument,
     ObservableCounter,
     ObservableGauge,
     ObservableUpDownCounter,
@@ -59,6 +58,7 @@
 from opentelemetry.sdk.metrics._internal.exponential_histogram.mapping.logarithm_mapping import (
     LogarithmMapping,
 )
+from opentelemetry.sdk.metrics._internal.instrument import _Instrument
 from opentelemetry.sdk.metrics._internal.measurement import Measurement
 from opentelemetry.sdk.metrics._internal.point import Buckets as BucketsPoint
 from opentelemetry.sdk.metrics._internal.point import (
@@ -1200,7 +1200,7 @@ class Aggregation(ABC):
     @abstractmethod
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder
@@ -1231,7 +1231,7 @@ class DefaultAggregation(Aggregation):
 
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder
@@ -1323,7 +1323,7 @@ def __init__(
 
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder
@@ -1372,7 +1372,7 @@ def __init__(
 
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder
@@ -1416,7 +1416,7 @@ class SumAggregation(Aggregation):
 
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder
@@ -1450,7 +1450,7 @@ class LastValueAggregation(Aggregation):
 
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder
@@ -1468,7 +1468,7 @@ class DropAggregation(Aggregation):
 
     def _create_aggregation(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         attributes: Attributes,
         reservoir_factory: Callable[
             [Type[_Aggregation]], ExemplarReservoirBuilder

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/instrument.py

@@ -17,11 +17,21 @@
 
 from logging import getLogger
 from time import time_ns
-from typing import TYPE_CHECKING, Generator, Iterable, List, Sequence, Union
+from typing import (
+    TYPE_CHECKING,
+    Generator,
+    Iterable,
+    List,
+    Protocol,
+    Sequence,
+    Union,
+    cast,
+    runtime_checkable,
+)
 
 # This kind of import is needed to avoid Sphinx errors.
 from opentelemetry.context import Context, get_current
-from opentelemetry.metrics import CallbackT
+from opentelemetry.metrics import Asynchronous, CallbackT, Synchronous
 from opentelemetry.metrics import Counter as APICounter
 from opentelemetry.metrics import Histogram as APIHistogram
 from opentelemetry.metrics import ObservableCounter as APIObservableCounter
@@ -55,7 +65,15 @@
 )
 
 
-class _Synchronous:
+@runtime_checkable
+class _Instrument(Protocol):
+    name: str
+    unit: str
+    description: str
+    instrumentation_scope: InstrumentationScope
+
+
+class _Synchronous(_Instrument, Synchronous):
     def __init__(
         self,
         name: str,
@@ -79,7 +97,7 @@ def __init__(
 
         name = result["name"]
         unit = result["unit"]
-        description = result["description"]
+        description = cast(str, result["description"])
 
         self.name = name.lower()
         self.unit = unit
@@ -93,13 +111,13 @@ def _is_enabled(self) -> bool:
         return self._meter_config is None or self._meter_config.is_enabled
 
 
-class _Asynchronous:
+class _Asynchronous(_Instrument, Asynchronous):
     def __init__(
         self,
         name: str,
         instrumentation_scope: InstrumentationScope,
         measurement_consumer: MeasurementConsumer,
-        callbacks: Iterable[CallbackT] | None = None,
+        callbacks: Sequence[CallbackT] | None = None,
         unit: str = "",
         description: str = "",
         *,
@@ -118,7 +136,7 @@ def __init__(
 
         name = result["name"]
         unit = result["unit"]
-        description = result["description"]
+        description = cast(str, result["description"])
 
         self.name = name.lower()
         self.unit = unit

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/measurement.py

@@ -12,13 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Union
+from typing import TYPE_CHECKING, Union
 
 from opentelemetry.context import Context
-from opentelemetry.metrics import Instrument
 from opentelemetry.util.types import Attributes
 
+if TYPE_CHECKING:
+    from opentelemetry.sdk.metrics._internal.instrument import _Instrument
+
 
 @dataclass(frozen=True)
 class Measurement:
@@ -35,6 +39,6 @@ class Measurement:
 
     value: Union[int, float]
     time_unix_nano: int
-    instrument: Instrument
+    instrument: _Instrument
     context: Context
     attributes: Attributes = None

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/metric_reader_storage.py

@@ -20,7 +20,6 @@
 from opentelemetry.metrics import (
     Asynchronous,
     Counter,
-    Instrument,
     ObservableCounter,
 )
 from opentelemetry.sdk.metrics._internal._view_instrument_match import (
@@ -36,6 +35,7 @@
     _LastValueAggregation,
     _SumAggregation,
 )
+from opentelemetry.sdk.metrics._internal.instrument import _Instrument
 from opentelemetry.sdk.metrics._internal.measurement import Measurement
 from opentelemetry.sdk.metrics._internal.point import (
     ExponentialHistogram,
@@ -70,13 +70,13 @@ def __init__(
         self._lock = RLock()
         self._sdk_config = sdk_config
         self._instrument_view_instrument_matches: Dict[
-            Instrument, List[_ViewInstrumentMatch]
+            _Instrument, List[_ViewInstrumentMatch]
         ] = {}
         self._instrument_class_temporality = instrument_class_temporality
         self._instrument_class_aggregation = instrument_class_aggregation
 
     def _get_or_init_view_instrument_match(
-        self, instrument: Instrument
+        self, instrument: _Instrument
     ) -> List[_ViewInstrumentMatch]:
         # Optimistically get the relevant views for the given instrument. Once set for a given
         # instrument, the mapping will never change
@@ -253,7 +253,7 @@ def collect(self) -> Optional[MetricsData]:
 
     def _handle_view_instrument_match(
         self,
-        instrument: Instrument,
+        instrument: _Instrument,
         view_instrument_matches: List["_ViewInstrumentMatch"],
     ) -> None:
         for view in self._sdk_config.views:
@@ -292,7 +292,7 @@ def _handle_view_instrument_match(
 
     @staticmethod
     def _check_view_instrument_compatibility(
-        view: View, instrument: Instrument
+        view: View, instrument: _Instrument
     ) -> bool:
         """
         Checks if a view and an instrument are compatible.

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/view.py

@@ -30,6 +30,7 @@
     ExemplarReservoirBuilder,
     SimpleFixedSizeExemplarReservoir,
 )
+from opentelemetry.sdk.metrics._internal.instrument import _Instrument
 
 _logger = getLogger(__name__)
 
@@ -164,7 +165,7 @@ def __init__(
 
     # pylint: disable=too-many-return-statements
     # pylint: disable=too-many-branches
-    def _match(self, instrument: Instrument) -> bool:
+    def _match(self, instrument: _Instrument) -> bool:
         if self._instrument_type is not None:
             if not isinstance(instrument, self._instrument_type):
                 return False