Implement ExplicitBucketBoundaries advisory for Histograms

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#4364](https://github.com/open-telemetry/opentelemetry-python/pull/4364))
 - Add Python 3.13 support
   ([#4353](https://github.com/open-telemetry/opentelemetry-python/pull/4353))
+- Add support for `explicit_bucket_boundaries` advisory for Histograms
+  ([#4361](https://github.com/open-telemetry/opentelemetry-python/pull/4361))
 
 ## Version 1.29.0/0.50b0 (2024-12-11)
 

docs/examples/metrics/instruments/example.py

@@ -58,5 +58,13 @@ def observable_gauge_func(options: CallbackOptions) -> Iterable[Observation]:
 histogram = meter.create_histogram("histogram")
 histogram.record(99.9)
 
+
+# Histogram with explicit_bucket_boundaries advisory
+histogram = meter.create_histogram(
+    "histogram_with_advisory",
+    advisory={"explicit_bucket_boundaries": [0, 1, 2]},
+)
+histogram.record(99.9)
+
 # Async Gauge
 gauge = meter.create_observable_gauge("gauge", [observable_gauge_func])

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

@@ -74,7 +74,7 @@
 )
 from opentelemetry.util._once import Once
 from opentelemetry.util._providers import _load_provider
-from opentelemetry.util.types import Attributes
+from opentelemetry.util.types import Attributes, MetricsInstrumentAdvisory
 
 _logger = getLogger(__name__)
 
@@ -379,6 +379,7 @@ def create_histogram(
         name: str,
         unit: str = "",
         description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
     ) -> Histogram:
         """Creates a :class:`~opentelemetry.metrics.Histogram` instrument
 
@@ -526,13 +527,14 @@ def create_histogram(
         name: str,
         unit: str = "",
         description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
     ) -> Histogram:
         with self._lock:
             if self._real_meter:
                 return self._real_meter.create_histogram(
-                    name, unit, description
+                    name, unit, description, advisory
                 )
-            proxy = _ProxyHistogram(name, unit, description)
+            proxy = _ProxyHistogram(name, unit, description, advisory)
             self._instruments.append(proxy)
             return proxy
 
@@ -686,6 +688,7 @@ def create_histogram(
         name: str,
         unit: str = "",
         description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
     ) -> Histogram:
         """Returns a no-op Histogram."""
         if self._is_instrument_registered(
@@ -699,7 +702,9 @@ def create_histogram(
                 unit,
                 description,
             )
-        return NoOpHistogram(name, unit=unit, description=description)
+        return NoOpHistogram(
+            name, unit=unit, description=description, advisory=advisory
+        )
 
     def create_observable_gauge(
         self,

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

@@ -35,7 +35,7 @@
 from opentelemetry import metrics
 from opentelemetry.context import Context
 from opentelemetry.metrics._internal.observation import Observation
-from opentelemetry.util.types import Attributes
+from opentelemetry.util.types import Attributes, MetricsInstrumentAdvisory
 
 _logger = getLogger(__name__)
 
@@ -330,6 +330,16 @@ class Histogram(Synchronous):
     histograms, summaries, and percentile.
     """
 
+    @abstractmethod
+    def __init__(
+        self,
+        name: str,
+        unit: str = "",
+        description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
+    ) -> None:
+        pass
+
     @abstractmethod
     def record(
         self,
@@ -348,8 +358,11 @@ def __init__(
         name: str,
         unit: str = "",
         description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
     ) -> None:
-        super().__init__(name, unit=unit, description=description)
+        super().__init__(
+            name, unit=unit, description=description, advisory=advisory
+        )
 
     def record(
         self,
@@ -361,6 +374,20 @@ def record(
 
 
 class _ProxyHistogram(_ProxyInstrument[Histogram], Histogram):
+    # pylint: disable=super-init-not-called
+    def __init__(
+        self,
+        name: str,
+        unit: str = "",
+        description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
+    ) -> None:
+        self._name = name
+        self._unit = unit
+        self._description = description
+        self._advisory = advisory
+        self._real_instrument: Optional[Histogram] = None
+
     def record(
         self,
         amount: Union[int, float],
@@ -372,7 +399,7 @@ def record(
 
     def _create_real_instrument(self, meter: "metrics.Meter") -> Histogram:
         return meter.create_histogram(
-            self._name, self._unit, self._description
+            self._name, self._unit, self._description, self._advisory
         )
 
 

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

@@ -12,8 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
-from typing import Mapping, Optional, Sequence, Tuple, Union
+from typing import Mapping, Optional, Sequence, Tuple, TypedDict, Union
 
 # This is the implementation of the "Any" type as specified by the specifications of OpenTelemetry data model for logs.
 # For more details, refer to the OTel specification:
@@ -56,3 +55,7 @@
     ],
     ...,
 ]
+
+
+class MetricsInstrumentAdvisory(TypedDict):
+    explicit_bucket_boundaries: Optional[AnyValue]

opentelemetry-api/tests/metrics/test_meter.py

@@ -39,7 +39,7 @@ def create_observable_counter(
             name, callbacks, unit=unit, description=description
         )
 
-    def create_histogram(self, name, unit="", description=""):
+    def create_histogram(self, name, unit="", description="", advisory=None):
         super().create_histogram(name, unit=unit, description=description)
 
     def create_gauge(self, name, unit="", description=""):

opentelemetry-api/tests/metrics/test_meter_provider.py

@@ -274,7 +274,7 @@ def test_proxy_meter(self):
             name, unit, description
         )
         real_meter.create_histogram.assert_called_once_with(
-            name, unit, description
+            name, unit, description, None
         )
         real_meter.create_gauge.assert_called_once_with(
             name, unit, description

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

@@ -11,6 +11,7 @@
 # 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.
+
 import weakref
 from atexit import register, unregister
 from logging import getLogger
@@ -63,7 +64,7 @@
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.util.instrumentation import InstrumentationScope
 from opentelemetry.util._once import Once
-from opentelemetry.util.types import Attributes
+from opentelemetry.util.types import Attributes, MetricsInstrumentAdvisory
 
 _logger = getLogger(__name__)
 
@@ -196,7 +197,29 @@ def create_observable_counter(
             self._instrument_id_instrument[instrument_id] = instrument
             return instrument
 
-    def create_histogram(self, name, unit="", description="") -> APIHistogram:
+    def create_histogram(
+        self,
+        name: str,
+        unit: str = "",
+        description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
+    ) -> APIHistogram:
+        if advisory is not None:
+            raise_error = False
+            try:
+                boundaries = advisory["explicit_bucket_boundaries"]
+                raise_error = not (
+                    boundaries
+                    and all(isinstance(e, (int, float)) for e in boundaries)
+                )
+            except (KeyError, TypeError):
+                raise_error = True
+
+            if raise_error:
+                raise ValueError(
+                    "Advisory must be a dict with explicit_bucket_boundaries key containing a sequence of numbers"
+                )
+
         (
             is_instrument_registered,
             instrument_id,
@@ -223,6 +246,7 @@ def create_histogram(self, name, unit="", description="") -> APIHistogram:
             self._measurement_consumer,
             unit,
             description,
+            advisory,
         )
         with self._instrument_id_instrument_lock:
             self._instrument_id_instrument[instrument_id] = instrument

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

@@ -437,32 +437,40 @@ def collect(
         )
 
 
+_DEFAULT_EXPLICIT_BUCKET_HISTOGRAM_AGGREGATION_BOUNDARIES: Sequence[float] = (
+    0.0,
+    5.0,
+    10.0,
+    25.0,
+    50.0,
+    75.0,
+    100.0,
+    250.0,
+    500.0,
+    750.0,
+    1000.0,
+    2500.0,
+    5000.0,
+    7500.0,
+    10000.0,
+)
+
+
 class _ExplicitBucketHistogramAggregation(_Aggregation[HistogramPoint]):
     def __init__(
         self,
         attributes: Attributes,
         instrument_aggregation_temporality: AggregationTemporality,
         start_time_unix_nano: int,
         reservoir_builder: ExemplarReservoirBuilder,
-        boundaries: Sequence[float] = (
-            0.0,
-            5.0,
-            10.0,
-            25.0,
-            50.0,
-            75.0,
-            100.0,
-            250.0,
-            500.0,
-            750.0,
-            1000.0,
-            2500.0,
-            5000.0,
-            7500.0,
-            10000.0,
-        ),
+        boundaries: Optional[Sequence[float]] = None,
         record_min_max: bool = True,
     ):
+        if boundaries is None:
+            boundaries = (
+                _DEFAULT_EXPLICIT_BUCKET_HISTOGRAM_AGGREGATION_BOUNDARIES
+            )
+
         super().__init__(
             attributes,
             reservoir_builder=partial(
@@ -1268,6 +1276,11 @@ def _create_aggregation(
             )
 
         if isinstance(instrument, Histogram):
+            boundaries: Optional[Sequence[float]] = (
+                instrument.advisory.get("explicit_bucket_boundaries")
+                if instrument.advisory is not None
+                else None
+            )
             return _ExplicitBucketHistogramAggregation(
                 attributes,
                 reservoir_builder=reservoir_factory(
@@ -1276,6 +1289,7 @@ def _create_aggregation(
                 instrument_aggregation_temporality=(
                     AggregationTemporality.DELTA
                 ),
+                boundaries=boundaries,
                 start_time_unix_nano=start_time_unix_nano,
             )
 
@@ -1347,25 +1361,13 @@ class ExplicitBucketHistogramAggregation(Aggregation):
 
     def __init__(
         self,
-        boundaries: Sequence[float] = (
-            0.0,
-            5.0,
-            10.0,
-            25.0,
-            50.0,
-            75.0,
-            100.0,
-            250.0,
-            500.0,
-            750.0,
-            1000.0,
-            2500.0,
-            5000.0,
-            7500.0,
-            10000.0,
-        ),
+        boundaries: Optional[Sequence[float]] = None,
         record_min_max: bool = True,
     ) -> None:
+        if boundaries is None:
+            boundaries = (
+                _DEFAULT_EXPLICIT_BUCKET_HISTOGRAM_AGGREGATION_BOUNDARIES
+            )
         self._boundaries = boundaries
         self._record_min_max = record_min_max
 

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

@@ -34,6 +34,7 @@
 from opentelemetry.metrics._internal.instrument import CallbackOptions
 from opentelemetry.sdk.metrics._internal.measurement import Measurement
 from opentelemetry.sdk.util.instrumentation import InstrumentationScope
+from opentelemetry.util.types import MetricsInstrumentAdvisory
 
 _logger = getLogger(__name__)
 
@@ -219,6 +220,24 @@ def __new__(cls, *args, **kwargs):
 
 
 class Histogram(_Synchronous, APIHistogram):
+    def __init__(
+        self,
+        name: str,
+        instrumentation_scope: InstrumentationScope,
+        measurement_consumer: "opentelemetry.sdk.metrics.MeasurementConsumer",
+        unit: str = "",
+        description: str = "",
+        advisory: Optional[MetricsInstrumentAdvisory] = None,
+    ):
+        super().__init__(
+            name,
+            unit=unit,
+            description=description,
+            instrumentation_scope=instrumentation_scope,
+            measurement_consumer=measurement_consumer,
+        )
+        self.advisory = advisory
+
     def __new__(cls, *args, **kwargs):
         if cls is Histogram:
             raise TypeError("Histogram must be instantiated via a meter.")