diff --git a/opentelemetry-api/src/opentelemetry/metrics/__init__.py b/opentelemetry-api/src/opentelemetry/metrics/__init__.py index 28e6b4bdff5..83d210e063b 100644 --- a/opentelemetry-api/src/opentelemetry/metrics/__init__.py +++ b/opentelemetry-api/src/opentelemetry/metrics/__init__.py @@ -127,6 +127,85 @@ def create_up_down_counter( def create_observable_counter( self, name, callback, unit="", description="" ) -> ObservableCounter: + """Creates an observable counter instrument + + An observable counter observes a monotonically increasing count by + calling a provided callback which returns multiple + :class:`~opentelemetry.metrics.measurement.Measurement`. + + For example, an observable counter could be used to report system CPU + time periodically. Here is a basic implementation:: + + def cpu_time_callback() -> Iterable[Measurement]: + measurements = [] + with open("/proc/stat") as procstat: + procstat.readline() # skip the first line + for line in procstat: + if not line.startswith("cpu"): break + cpu, *states = line.split() + measurements.append(Measurement(int(states[0]) // 100, {"cpu": cpu, "state": "user"})) + measurements.append(Measurement(int(states[1]) // 100, {"cpu": cpu, "state": "nice"})) + measurements.append(Measurement(int(states[2]) // 100, {"cpu": cpu, "state": "system"})) + # ... other states + return measurements + + meter.create_observable_counter( + "system.cpu.time", + callback=cpu_time_callback, + unit="s", + description="CPU time" + ) + + To reduce memory usage, you can use generator callbacks instead of + building the full list:: + + def cpu_time_callback() -> Iterable[Measurement]: + with open("/proc/stat") as procstat: + procstat.readline() # skip the first line + for line in procstat: + if not line.startswith("cpu"): break + cpu, *states = line.split() + yield Measurement(int(states[0]) // 100, {"cpu": cpu, "state": "user"}) + 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 + :class:`~opentelemetry.metrics.measurement.Measurement`:: + + def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Measurement]]: + while True: + measurements = [] + with open("/proc/stat") as procstat: + procstat.readline() # skip the first line + for line in procstat: + if not line.startswith("cpu"): break + cpu, *states = line.split() + if "user" in states_to_include: + measurements.append(Measurement(int(states[0]) // 100, {"cpu": cpu, "state": "user"})) + if "nice" in states_to_include: + measurements.append(Measurement(int(states[1]) // 100, {"cpu": cpu, "state": "nice"})) + # ... other states + yield measurements + + meter.create_observable_counter( + "system.cpu.time", + callback=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 + :class:`~opentelemetry.metrics.measurement.Measurement`. + Alternatively, can be a generator that 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. + description: A description for this instrument and what it measures. + """ + self._secure_instrument_name(name) @abstractmethod diff --git a/opentelemetry-api/src/opentelemetry/metrics/instrument.py b/opentelemetry-api/src/opentelemetry/metrics/instrument.py index 1f3831a169e..5d382056408 100644 --- a/opentelemetry-api/src/opentelemetry/metrics/instrument.py +++ b/opentelemetry-api/src/opentelemetry/metrics/instrument.py @@ -16,14 +16,19 @@ # type: ignore - from abc import ABC, abstractmethod +from collections import abc as collections_abc from logging import getLogger from re import compile as compile_ -from types import GeneratorType +from typing import Callable, Generator, Iterable, Union from opentelemetry.metrics.measurement import Measurement +_TInstrumentCallback = Callable[[], Iterable[Measurement]] +_TInstrumentCallbackGenerator = Generator[Iterable[Measurement], None, None] +TCallback = Union[_TInstrumentCallback, _TInstrumentCallbackGenerator] + + _logger = getLogger(__name__) @@ -75,30 +80,65 @@ class Synchronous(Instrument): class Asynchronous(Instrument): @abstractmethod def __init__( - self, name, callback, *args, unit="", description="", **kwargs + self, + name, + callback: TCallback, + *args, + unit="", + description="", + **kwargs ): - super().__init__(name, *args, unit=unit, description="", **kwargs) - - if not isinstance(callback, GeneratorType): - _logger.error("callback must be a generator") + super().__init__( + name, *args, unit=unit, description=description, **kwargs + ) - else: - super().__init__( - name, unit=unit, description=description, *args, **kwargs - ) + if isinstance(callback, collections_abc.Callable): self._callback = callback + elif isinstance(callback, collections_abc.Generator): + self._callback = self._wrap_generator_callback(callback) + else: + _logger.error("callback must be a callable or generator") + + def _wrap_generator_callback( + self, + generator_callback: _TInstrumentCallbackGenerator, + ) -> _TInstrumentCallback: + """Wraps a generator style callback into a callable one""" + has_items = True + + def inner() -> Iterable[Measurement]: + nonlocal has_items + if not has_items: + return [] + + try: + return next(generator_callback) + except StopIteration: + has_items = False + _logger.error( + "callback generator for instrument %s ran out of measurements", + self._name, + ) + return [] + + return inner - @property def callback(self): - def function(): - measurement = next(self._callback) + measurements = self._callback() + if not isinstance(measurements, collections_abc.Iterable): + _logger.error( + "Callback must return an iterable of Measurement, got %s", + type(measurements), + ) + return + for measurement in measurements: if not isinstance(measurement, Measurement): - _logger.error("Callback must return a Measurement") - return None - - return measurement - - return function + _logger.error( + "Callback must return an iterable of Measurement, " + "iterable contained type %s", + type(measurement), + ) + yield measurement class _Adding(Instrument): @@ -147,18 +187,13 @@ def add(self, amount, attributes=None): class ObservableCounter(_Monotonic, Asynchronous): - @property def callback(self): - def function(): - measurement = super(ObservableCounter, self).callback() + measurements = super().callback() - if measurement is not None and measurement.value < 0: + for measurement in measurements: + if measurement.value < 0: _logger.error("Amount must be non-negative") - return None - - return measurement - - return function + yield measurement class DefaultObservableCounter(ObservableCounter): diff --git a/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py b/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py new file mode 100644 index 00000000000..347f6c4dc48 --- /dev/null +++ b/opentelemetry-api/tests/metrics/integration_test/test_cpu_time.py @@ -0,0 +1,194 @@ +# Copyright The OpenTelemetry Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. +# type: ignore + +import io +from typing import Generator, Iterable +from unittest import TestCase + +from opentelemetry.metrics import _DefaultMeter +from opentelemetry.metrics.measurement import Measurement + +# FIXME Test that the instrument methods can be called concurrently safely. + + +class ChildMeasurement(Measurement): + def __init__(self, value, attributes=None): + super().__init__(value, attributes=attributes) + + def __eq__(self, o: Measurement) -> bool: + return self.value == o.value and self.attributes == o.attributes + + +class TestCpuTimeIntegration(TestCase): + """Integration test of scraping CPU time from proc stat with an observable + counter""" + + procstat_str = """\ +cpu 8549517 4919096 9165935 1430260740 1641349 0 1646147 623279 0 0 +cpu0 615029 317746 594601 89126459 129629 0 834346 42137 0 0 +cpu1 588232 349185 640492 89156411 124485 0 241004 41862 0 0 +intr 4370168813 38 9 0 0 1639 0 0 0 0 0 2865202 0 152 0 0 0 0 0 0 0 0 0 0 0 0 7236812 5966240 4501046 6467792 7289114 6048205 5299600 5178254 4642580 6826812 6880917 6230308 6307699 4699637 6119330 4905094 5644039 4700633 10539029 5365438 6086908 2227906 5094323 9685701 10137610 7739951 7143508 8123281 4968458 5683103 9890878 4466603 0 0 0 8929628 0 5 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +ctxt 6877594077 +btime 1631501040 +processes 2557351 +procs_running 2 +procs_blocked 0 +softirq 1644603067 0 166540056 208 309152755 8936439 0 1354908 935642970 13 222975718\n""" + + measurements_expected = [ + ChildMeasurement(6150, {"cpu": "cpu0", "state": "user"}), + ChildMeasurement(3177, {"cpu": "cpu0", "state": "nice"}), + ChildMeasurement(5946, {"cpu": "cpu0", "state": "system"}), + ChildMeasurement(891264, {"cpu": "cpu0", "state": "idle"}), + ChildMeasurement(1296, {"cpu": "cpu0", "state": "iowait"}), + ChildMeasurement(0, {"cpu": "cpu0", "state": "irq"}), + ChildMeasurement(8343, {"cpu": "cpu0", "state": "softirq"}), + ChildMeasurement(421, {"cpu": "cpu0", "state": "guest"}), + ChildMeasurement(0, {"cpu": "cpu0", "state": "guest_nice"}), + ChildMeasurement(5882, {"cpu": "cpu1", "state": "user"}), + ChildMeasurement(3491, {"cpu": "cpu1", "state": "nice"}), + ChildMeasurement(6404, {"cpu": "cpu1", "state": "system"}), + ChildMeasurement(891564, {"cpu": "cpu1", "state": "idle"}), + ChildMeasurement(1244, {"cpu": "cpu1", "state": "iowait"}), + ChildMeasurement(0, {"cpu": "cpu1", "state": "irq"}), + ChildMeasurement(2410, {"cpu": "cpu1", "state": "softirq"}), + ChildMeasurement(418, {"cpu": "cpu1", "state": "guest"}), + ChildMeasurement(0, {"cpu": "cpu1", "state": "guest_nice"}), + ] + + def test_cpu_time_callback(self): + meter = _DefaultMeter("foo") + + def cpu_time_callback() -> Iterable[Measurement]: + procstat = io.StringIO(self.procstat_str) + procstat.readline() # skip the first line + for line in procstat: + if not line.startswith("cpu"): + break + cpu, *states = line.split() + yield ChildMeasurement( + int(states[0]) // 100, {"cpu": cpu, "state": "user"} + ) + yield ChildMeasurement( + int(states[1]) // 100, {"cpu": cpu, "state": "nice"} + ) + yield ChildMeasurement( + int(states[2]) // 100, {"cpu": cpu, "state": "system"} + ) + yield ChildMeasurement( + int(states[3]) // 100, {"cpu": cpu, "state": "idle"} + ) + yield ChildMeasurement( + int(states[4]) // 100, {"cpu": cpu, "state": "iowait"} + ) + yield ChildMeasurement( + int(states[5]) // 100, {"cpu": cpu, "state": "irq"} + ) + yield ChildMeasurement( + int(states[6]) // 100, {"cpu": cpu, "state": "softirq"} + ) + yield ChildMeasurement( + int(states[7]) // 100, {"cpu": cpu, "state": "guest"} + ) + yield ChildMeasurement( + int(states[8]) // 100, {"cpu": cpu, "state": "guest_nice"} + ) + + observable_counter = meter.create_observable_counter( + "system.cpu.time", + callback=cpu_time_callback, + unit="s", + description="CPU time", + ) + measurements = list(observable_counter.callback()) + self.assertEqual(measurements, self.measurements_expected) + + def test_cpu_time_generator(self): + meter = _DefaultMeter("foo") + + def cpu_time_generator() -> Generator[ + Iterable[Measurement], None, None + ]: + while True: + measurements = [] + procstat = io.StringIO(self.procstat_str) + procstat.readline() # skip the first line + for line in procstat: + if not line.startswith("cpu"): + break + cpu, *states = line.split() + measurements.append( + ChildMeasurement( + int(states[0]) // 100, + {"cpu": cpu, "state": "user"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[1]) // 100, + {"cpu": cpu, "state": "nice"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[2]) // 100, + {"cpu": cpu, "state": "system"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[3]) // 100, + {"cpu": cpu, "state": "idle"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[4]) // 100, + {"cpu": cpu, "state": "iowait"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[5]) // 100, {"cpu": cpu, "state": "irq"} + ) + ) + measurements.append( + ChildMeasurement( + int(states[6]) // 100, + {"cpu": cpu, "state": "softirq"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[7]) // 100, + {"cpu": cpu, "state": "guest"}, + ) + ) + measurements.append( + ChildMeasurement( + int(states[8]) // 100, + {"cpu": cpu, "state": "guest_nice"}, + ) + ) + yield measurements + + observable_counter = meter.create_observable_counter( + "system.cpu.time", + callback=cpu_time_generator(), + unit="s", + description="CPU time", + ) + measurements = list(observable_counter.callback()) + self.assertEqual(measurements, self.measurements_expected) diff --git a/opentelemetry-api/tests/metrics/test_instruments.py b/opentelemetry-api/tests/metrics/test_instruments.py index 4de45157dda..2dd100c9ed7 100644 --- a/opentelemetry-api/tests/metrics/test_instruments.py +++ b/opentelemetry-api/tests/metrics/test_instruments.py @@ -307,11 +307,11 @@ def test_create_observable_counter_api(self): "", ) - def test_observable_counter_callback(self): + def test_observable_counter_generator(self): """ - Test that the API for creating a asynchronous counter accepts a callback. - Test that the callback function reports measurements. - Test that there is a way to pass state to the callback. + Test that the API for creating a asynchronous counter accepts a generator. + Test that the generator function reports iterable of measurements. + Test that there is a way to pass state to the generator. Test that the instrument accepts positive measurements. Test that the instrument does not accept negative measurements. """ @@ -337,20 +337,68 @@ def callback(): ) with self.assertLogs(level=ERROR): - observable_counter.callback() + # use list() to consume the whole generator returned by callback() + list(observable_counter.callback()) def callback(): - yield ChildMeasurement(1) - yield ChildMeasurement(-1) + yield [ChildMeasurement(1), ChildMeasurement(2)] + yield [ChildMeasurement(-1)] observable_counter = DefaultObservableCounter("name", callback()) with self.assertRaises(AssertionError): with self.assertLogs(level=ERROR): - observable_counter.callback() + list(observable_counter.callback()) with self.assertLogs(level=ERROR): - observable_counter.callback() + list(observable_counter.callback()) + + # out of items in generator, should log once + with self.assertLogs(level=ERROR): + list(observable_counter.callback()) + + # but log only once + with self.assertRaises(AssertionError): + with self.assertLogs(level=ERROR): + list(observable_counter.callback()) + + def test_observable_counter_callback(self): + """ + Equivalent to test_observable_counter_generator but uses the callback + form. + """ + + def callback_invalid_return(): + return 1 + + with self.assertRaises(AssertionError): + with self.assertLogs(level=ERROR): + observable_counter = DefaultObservableCounter( + "name", callback_invalid_return + ) + + with self.assertLogs(level=ERROR): + # use list() to consume the whole generator returned by callback() + list(observable_counter.callback()) + + def callback_valid(): + return [ChildMeasurement(1), ChildMeasurement(2)] + + observable_counter = DefaultObservableCounter("name", callback_valid) + + with self.assertRaises(AssertionError): + with self.assertLogs(level=ERROR): + list(observable_counter.callback()) + + def callback_one_invalid(): + return [ChildMeasurement(1), ChildMeasurement(-2)] + + observable_counter = DefaultObservableCounter( + "name", callback_one_invalid + ) + + with self.assertLogs(level=ERROR): + list(observable_counter.callback()) class TestHistogram(TestCase): @@ -527,7 +575,15 @@ def callback(): observable_gauge = DefaultObservableGauge("name", callback()) with self.assertLogs(level=ERROR): - observable_gauge.callback() + list(observable_gauge.callback()) + + def callback(): + yield [ChildMeasurement(1), ChildMeasurement(-1)] + + observable_gauge = DefaultObservableGauge("name", callback()) + with self.assertRaises(AssertionError): + with self.assertLogs(level=ERROR): + list(observable_gauge.callback()) class TestUpDownCounter(TestCase):