opentelemetry-api: add advisory parameters to Histograms

Author: xrmx

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: MetricsInstrumentAdvisory = None,
     ) -> Histogram:
         """Creates a :class:`~opentelemetry.metrics.Histogram` instrument
 
@@ -526,13 +527,14 @@ def create_histogram(
         name: str,
         unit: str = "",
         description: str = "",
+        advisory: 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: 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: MetricsInstrumentAdvisory = None,
+    ) -> None:
+        pass
+
     @abstractmethod
     def record(
         self,
@@ -348,8 +358,11 @@ def __init__(
         name: str,
         unit: str = "",
         description: str = "",
+        advisory: 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,19 @@ def record(
 
 
 class _ProxyHistogram(_ProxyInstrument[Histogram], Histogram):
+    def __init__(
+        self,
+        name: str,
+        unit: str = "",
+        description: str = "",
+        advisory: MetricsInstrumentAdvisory = None,
+    ) -> None:
+        self._name = name
+        self._unit = unit
+        self._description = description
+        self._advisory = advisory
+        self._real_instrument: Optional[InstrumentT] = None
+
     def record(
         self,
         amount: Union[int, float],
@@ -372,7 +398,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 Literal, Mapping, Optional, Sequence, Tuple, 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,8 @@
     ],
     ...,
 ]
+
+MetricsInstrumentAdvisoryKey = Literal["ExplicitBucketBoundaries"]
+MetricsInstrumentAdvisory = Optional[
+    Mapping[MetricsInstrumentAdvisoryKey, AnyValue]
+]

opentelemetry-api/tests/metrics/test_meter_provider.py

@@ -251,7 +251,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