Add support for zero or more callbacks (#2602)

* Add support for zero or more callbacks

Fixes #2601

* Add changelog entry

* Update opentelemetry-api/src/opentelemetry/_metrics/__init__.py

Co-authored-by: Leighton Chen <[email protected]>

* Update opentelemetry-api/src/opentelemetry/_metrics/__init__.py

Co-authored-by: Leighton Chen <[email protected]>

Co-authored-by: Leighton Chen <[email protected]>

Author: ocelotl

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.10.0-0.29b0...HEAD)
 
+- Add support for zero or more callbacks
+  ([#2602](https://github.com/open-telemetry/opentelemetry-python/pull/2602))
 - Fix parsing of trace flags when extracting traceparent
   ([#2577](https://github.com/open-telemetry/opentelemetry-python/pull/2577))
 - Add default aggregation

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

@@ -181,12 +181,12 @@ def create_up_down_counter(
 
     @abstractmethod
     def create_observable_counter(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableCounter:
         """Creates an `ObservableCounter` instrument
 
         An observable counter observes a monotonically increasing count by
-        calling a provided callback which returns multiple
+        calling provided callbacks which returns multiple
         :class:`~opentelemetry._metrics.measurement.Measurement`.
 
         For example, an observable counter could be used to report system CPU
@@ -207,7 +207,7 @@ def cpu_time_callback() -> Iterable[Measurement]:
 
             meter.create_observable_counter(
                 "system.cpu.time",
-                callback=cpu_time_callback,
+                callbacks=[cpu_time_callback],
                 unit="s",
                 description="CPU time"
             )
@@ -225,8 +225,8 @@ def cpu_time_callback() -> Iterable[Measurement]:
                         yield Measurement(int(states[1]) // 100, {"cpu": cpu, "state": "nice"})
                         # ... other states
 
-        Alternatively, you can pass a generator directly instead of a callback,
-        which should return iterables of
+        Alternatively, you can pass a sequence of generators directly instead
+        of a sequence of callbacks, which each should return iterables of
         :class:`~opentelemetry._metrics.measurement.Measurement`::
 
             def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Measurement]]:
@@ -246,16 +246,17 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Measurem
 
             meter.create_observable_counter(
                 "system.cpu.time",
-                callback=cpu_time_callback({"user", "system"}),
+                callbacks=[cpu_time_callback({"user", "system"})],
                 unit="s",
                 description="CPU time"
             )
 
         Args:
             name: The name of the instrument to be created
-            callback: A callback that returns an iterable of
+            callbacks: A sequence of callbacks that return an iterable of
                 :class:`~opentelemetry._metrics.measurement.Measurement`.
-                Alternatively, can be a generator that yields iterables of
+                Alternatively, can be a sequence of generators that each yields
+                iterables of
                 :class:`~opentelemetry._metrics.measurement.Measurement`.
             unit: The unit for measurements this instrument reports. For
                 example, ``By`` for bytes. UCUM units are recommended.
@@ -275,13 +276,13 @@ def create_histogram(self, name, unit="", description="") -> Histogram:
 
     @abstractmethod
     def create_observable_gauge(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableGauge:
         """Creates an `ObservableGauge` instrument
 
         Args:
             name: The name of the instrument to be created
-            callback: A callback that returns an iterable of
+            callbacks: A sequence of callbacks that return an iterable of
                 :class:`~opentelemetry._metrics.measurement.Measurement`.
                 Alternatively, can be a generator that yields iterables of
                 :class:`~opentelemetry._metrics.measurement.Measurement`.
@@ -292,13 +293,13 @@ def create_observable_gauge(
 
     @abstractmethod
     def create_observable_up_down_counter(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableUpDownCounter:
         """Creates an `ObservableUpDownCounter` instrument
 
         Args:
             name: The name of the instrument to be created
-            callback: A callback that returns an iterable of
+            callbacks: A sequence of callbacks that return an iterable of
                 :class:`~opentelemetry._metrics.measurement.Measurement`.
                 Alternatively, can be a generator that yields iterables of
                 :class:`~opentelemetry._metrics.measurement.Measurement`.
@@ -358,15 +359,15 @@ def create_up_down_counter(
             return proxy
 
     def create_observable_counter(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableCounter:
         with self._lock:
             if self._real_meter:
                 return self._real_meter.create_observable_counter(
-                    name, callback, unit, description
+                    name, callbacks, unit, description
                 )
             proxy = _ProxyObservableCounter(
-                name, callback, unit=unit, description=description
+                name, callbacks, unit=unit, description=description
             )
             self._instruments.append(proxy)
             return proxy
@@ -382,32 +383,32 @@ def create_histogram(self, name, unit="", description="") -> Histogram:
             return proxy
 
     def create_observable_gauge(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableGauge:
         with self._lock:
             if self._real_meter:
                 return self._real_meter.create_observable_gauge(
-                    name, callback, unit, description
+                    name, callbacks, unit, description
                 )
             proxy = _ProxyObservableGauge(
-                name, callback, unit=unit, description=description
+                name, callbacks, unit=unit, description=description
             )
             self._instruments.append(proxy)
             return proxy
 
     def create_observable_up_down_counter(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableUpDownCounter:
         with self._lock:
             if self._real_meter:
                 return self._real_meter.create_observable_up_down_counter(
                     name,
-                    callback,
+                    callbacks,
                     unit,
                     description,
                 )
             proxy = _ProxyObservableUpDownCounter(
-                name, callback, unit=unit, description=description
+                name, callbacks, unit=unit, description=description
             )
             self._instruments.append(proxy)
             return proxy
@@ -454,11 +455,11 @@ def create_up_down_counter(
         return DefaultUpDownCounter(name, unit=unit, description=description)
 
     def create_observable_counter(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableCounter:
         """Returns a no-op ObservableCounter."""
         super().create_observable_counter(
-            name, callback, unit=unit, description=description
+            name, callbacks, unit=unit, description=description
         )
         if self._check_instrument_id(
             name, DefaultObservableCounter, unit, description
@@ -473,7 +474,7 @@ def create_observable_counter(
             )
         return DefaultObservableCounter(
             name,
-            callback,
+            callbacks,
             unit=unit,
             description=description,
         )
@@ -495,11 +496,11 @@ def create_histogram(self, name, unit="", description="") -> Histogram:
         return DefaultHistogram(name, unit=unit, description=description)
 
     def create_observable_gauge(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableGauge:
         """Returns a no-op ObservableGauge."""
         super().create_observable_gauge(
-            name, callback, unit=unit, description=description
+            name, callbacks, unit=unit, description=description
         )
         if self._check_instrument_id(
             name, DefaultObservableGauge, unit, description
@@ -514,17 +515,17 @@ def create_observable_gauge(
             )
         return DefaultObservableGauge(
             name,
-            callback,
+            callbacks,
             unit=unit,
             description=description,
         )
 
     def create_observable_up_down_counter(
-        self, name, callback, unit="", description=""
+        self, name, callbacks=None, unit="", description=""
     ) -> ObservableUpDownCounter:
         """Returns a no-op ObservableUpDownCounter."""
         super().create_observable_up_down_counter(
-            name, callback, unit=unit, description=description
+            name, callbacks, unit=unit, description=description
         )
         if self._check_instrument_id(
             name, DefaultObservableUpDownCounter, unit, description
@@ -539,7 +540,7 @@ def create_observable_up_down_counter(
             )
         return DefaultObservableUpDownCounter(
             name,
-            callback,
+            callbacks,
             unit=unit,
             description=description,
         )

opentelemetry-api/src/opentelemetry/_metrics/instrument.py

@@ -73,9 +73,9 @@ def _create_real_instrument(self, meter: "metrics.Meter") -> InstrumentT:
 
 
 class _ProxyAsynchronousInstrument(_ProxyInstrument[InstrumentT]):
-    def __init__(self, name, callback, unit, description) -> None:
+    def __init__(self, name, callbacks, unit, description) -> None:
         super().__init__(name, unit, description)
-        self._callback = callback
+        self._callbacks = callbacks
 
 
 class Synchronous(Instrument):
@@ -87,7 +87,7 @@ class Asynchronous(Instrument):
     def __init__(
         self,
         name,
-        callback,
+        callbacks=None,
         unit="",
         description="",
     ):
@@ -170,8 +170,8 @@ class ObservableCounter(_Monotonic, Asynchronous):
 
 
 class DefaultObservableCounter(ObservableCounter):
-    def __init__(self, name, callback, unit="", description=""):
-        super().__init__(name, callback, unit=unit, description=description)
+    def __init__(self, name, callbacks=None, unit="", description=""):
+        super().__init__(name, callbacks, unit=unit, description=description)
 
 
 class _ProxyObservableCounter(
@@ -181,7 +181,7 @@ def _create_real_instrument(
         self, meter: "metrics.Meter"
     ) -> ObservableCounter:
         return meter.create_observable_counter(
-            self._name, self._callback, self._unit, self._description
+            self._name, self._callbacks, self._unit, self._description
         )
 
 
@@ -193,8 +193,8 @@ class ObservableUpDownCounter(_NonMonotonic, Asynchronous):
 
 
 class DefaultObservableUpDownCounter(ObservableUpDownCounter):
-    def __init__(self, name, callback, unit="", description=""):
-        super().__init__(name, callback, unit=unit, description=description)
+    def __init__(self, name, callbacks=None, unit="", description=""):
+        super().__init__(name, callbacks, unit=unit, description=description)
 
 
 class _ProxyObservableUpDownCounter(
@@ -205,7 +205,7 @@ def _create_real_instrument(
         self, meter: "metrics.Meter"
     ) -> ObservableUpDownCounter:
         return meter.create_observable_up_down_counter(
-            self._name, self._callback, self._unit, self._description
+            self._name, self._callbacks, self._unit, self._description
         )
 
 
@@ -247,8 +247,8 @@ class ObservableGauge(_Grouping, Asynchronous):
 
 
 class DefaultObservableGauge(ObservableGauge):
-    def __init__(self, name, callback, unit="", description=""):
-        super().__init__(name, callback, unit=unit, description=description)
+    def __init__(self, name, callbacks=None, unit="", description=""):
+        super().__init__(name, callbacks, unit=unit, description=description)
 
 
 class _ProxyObservableGauge(
@@ -259,5 +259,5 @@ def _create_real_instrument(
         self, meter: "metrics.Meter"
     ) -> ObservableGauge:
         return meter.create_observable_gauge(
-            self._name, self._callback, self._unit, self._description
+            self._name, self._callbacks, self._unit, self._description
         )