Merge branch 'main' into main

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Add Synchronous Gauge instrument
+ ([#3462](https://github.com/open-telemetry/opentelemetry-python/pull/3462))
 - Drop support for 3.7
  ([#3668](https://github.com/open-telemetry/opentelemetry-python/pull/3668))
 - Include key in attribute sequence warning

docs/conf.py

@@ -178,3 +178,14 @@
  "scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"),
  "scm_web": (scm_web + "/%s", "scm_web"),
 }
+
+
+def on_missing_reference(app, env, node, contnode):
+ # FIXME Remove when opentelemetry.metrics._Gauge is renamed to
+ # opentelemetry.metrics.Gauge
+ if node["reftarget"] == "opentelemetry.metrics.Gauge":
+ return contnode
+
+
+def setup(app):
+ app.connect("missing-reference", on_missing_reference)

docs/getting_started/metrics_example.py

@@ -75,4 +75,10 @@ def observable_gauge_func(options: CallbackOptions) -> Iterable[Observation]:
 histogram.record(99.9)
 
 # Async Gauge
-gauge = meter.create_observable_gauge("gauge", [observable_gauge_func])
+observable_gauge = meter.create_observable_gauge(
+ "observable_gauge", [observable_gauge_func]
+)
+
+# Sync Gauge
+gauge = meter.create_gauge("gauge")
+gauge.set(1)

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

@@ -53,9 +53,15 @@
  CallbackOptions,
  CallbackT,
  Counter,
+)
+from opentelemetry.metrics._internal.instrument import Gauge as _Gauge
+from opentelemetry.metrics._internal.instrument import (
  Histogram,
  Instrument,
  NoOpCounter,
+)
+from opentelemetry.metrics._internal.instrument import NoOpGauge as _NoOpGauge
+from opentelemetry.metrics._internal.instrument import (
  NoOpHistogram,
  NoOpObservableCounter,
  NoOpObservableGauge,
@@ -74,6 +80,8 @@
  Synchronous,
  Asynchronous,
  CallbackOptions,
+ _Gauge,
+ _NoOpGauge,
  get_meter_provider,
  get_meter,
  Histogram,
@@ -103,6 +111,8 @@
  "NoOpMeterProvider",
  "Meter",
  "Counter",
+ "_Gauge",
+ "_NoOpGauge",
  "NoOpCounter",
  "UpDownCounter",
  "NoOpUpDownCounter",

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

@@ -51,8 +51,10 @@
 from opentelemetry.metrics._internal.instrument import (
  CallbackT,
  Counter,
+ Gauge,
  Histogram,
  NoOpCounter,
+ NoOpGauge,
  NoOpHistogram,
  NoOpObservableCounter,
  NoOpObservableGauge,
@@ -63,6 +65,7 @@
  ObservableUpDownCounter,
  UpDownCounter,
  _ProxyCounter,
+ _ProxyGauge,
  _ProxyHistogram,
  _ProxyObservableCounter,
  _ProxyObservableGauge,
@@ -79,6 +82,7 @@
 _ProxyInstrumentT = Union[
  _ProxyCounter,
  _ProxyHistogram,
+ _ProxyGauge,
  _ProxyObservableCounter,
  _ProxyObservableGauge,
  _ProxyObservableUpDownCounter,
@@ -381,6 +385,22 @@ def create_histogram(
  description: A description for this instrument and what it measures.
  """
 
+ @abstractmethod
+ def create_gauge(
+ self,
+ name: str,
+ unit: str = "",
+ description: str = "",
+ ) -> Gauge:
+ """Creates a ``Gauge`` instrument
+
+ Args:
+ name: The name of the instrument to be created
+ unit: The unit for observations this instrument reports. For
+ example, ``By`` for bytes. UCUM units are recommended.
+ description: A description for this instrument and what it measures.
+ """
+
  @abstractmethod
  def create_observable_gauge(
  self,
@@ -512,6 +532,19 @@ def create_histogram(
  self._instruments.append(proxy)
  return proxy
 
+ def create_gauge(
+ self,
+ name: str,
+ unit: str = "",
+ description: str = "",
+ ) -> Gauge:
+ with self._lock:
+ if self._real_meter:
+ return self._real_meter.create_gauge(name, unit, description)
+ proxy = _ProxyGauge(name, unit, description)
+ self._instruments.append(proxy)
+ return proxy
+
  def create_observable_gauge(
  self,
  name: str,
@@ -579,6 +612,27 @@ def create_counter(
  )
  return NoOpCounter(name, unit=unit, description=description)
 
+ def create_gauge(
+ self,
+ name: str,
+ unit: str = "",
+ description: str = "",
+ ) -> Gauge:
+ """Returns a no-op Gauge."""
+ super().create_gauge(name, unit=unit, description=description)
+ if self._is_instrument_registered(name, NoOpGauge, unit, description)[
+ 0
+ ]:
+ _logger.warning(
+ "An instrument with name %s, type %s, unit %s and "
+ "description %s has been created already.",
+ name,
+ Gauge.__name__,
+ unit,
+ description,
+ )
+ return NoOpGauge(name, unit=unit, description=description)
+
  def create_up_down_counter(
  self,
  name: str,

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

@@ -396,3 +396,50 @@ def _create_real_instrument(
  return meter.create_observable_gauge(
  self._name, self._callbacks, self._unit, self._description
  )
+
+
+class Gauge(Synchronous):
+ """A Gauge is a synchronous `Instrument` which can be used to record non-additive values as they occur."""
+
+ @abstractmethod
+ def set(
+ self,
+ amount: Union[int, float],
+ attributes: Optional[Attributes] = None,
+ ) -> None:
+ pass
+
+
+class NoOpGauge(Gauge):
+ """No-op implementation of ``Gauge``."""
+
+ def __init__(
+ self,
+ name: str,
+ unit: str = "",
+ description: str = "",
+ ) -> None:
+ super().__init__(name, unit=unit, description=description)
+
+ def set(
+ self,
+ amount: Union[int, float],
+ attributes: Optional[Attributes] = None,
+ ) -> None:
+ return super().set(amount, attributes=attributes)
+
+
+class _ProxyGauge(
+ _ProxyInstrument[Gauge],
+ Gauge,
+):
+ def set(
+ self,
+ amount: Union[int, float],
+ attributes: Optional[Attributes] = None,
+ ) -> None:
+ if self._real_instrument:
+ self._real_instrument.set(amount, attributes)
+
+ def _create_real_instrument(self, meter: "metrics.Meter") -> Gauge:
+ return meter.create_gauge(self._name, self._unit, self._description)

opentelemetry-api/tests/metrics/test_instruments.py

@@ -29,6 +29,7 @@
  ObservableGauge,
  ObservableUpDownCounter,
  UpDownCounter,
+ _Gauge,
 )
 
 # FIXME Test that the instrument methods can be called concurrently safely.
@@ -277,6 +278,50 @@ def test_histogram_record_method(self):
  self.assertIsNone(NoOpHistogram("name").record(1))
 
 
+class TestGauge(TestCase):
+ def test_create_gauge(self):
+ """
+ Test that the Gauge can be created with create_gauge.
+ """
+
+ self.assertTrue(
+ isinstance(NoOpMeter("name").create_gauge("name"), _Gauge)
+ )
+
+ def test_api_gauge_abstract(self):
+ """
+ Test that the API Gauge is an abstract class.
+ """
+
+ self.assertTrue(isabstract(_Gauge))
+
+ def test_create_gauge_api(self):
+ """
+ Test that the API for creating a gauge accepts the name of the instrument.
+ Test that the API for creating a gauge accepts a sequence of callbacks.
+ Test that the API for creating a gauge accepts the unit of the instrument.
+ Test that the API for creating a gauge accepts the description of the instrument
+ """
+
+ create_gauge_signature = signature(Meter.create_gauge)
+ self.assertIn("name", create_gauge_signature.parameters.keys())
+ self.assertIs(
+ create_gauge_signature.parameters["name"].default,
+ Signature.empty,
+ )
+ create_gauge_signature = signature(Meter.create_gauge)
+ create_gauge_signature = signature(Meter.create_gauge)
+ self.assertIn("unit", create_gauge_signature.parameters.keys())
+ self.assertIs(create_gauge_signature.parameters["unit"].default, "")
+
+ create_gauge_signature = signature(Meter.create_gauge)
+ self.assertIn("description", create_gauge_signature.parameters.keys())
+ self.assertIs(
+ create_gauge_signature.parameters["description"].default,
+ "",
+ )
+
+
 class TestObservableGauge(TestCase):
  def test_create_observable_gauge(self):
  """

opentelemetry-api/tests/metrics/test_meter.py

@@ -41,6 +41,9 @@ def create_observable_counter(
  def create_histogram(self, name, unit="", description=""):
  super().create_histogram(name, unit=unit, description=description)
 
+ def create_gauge(self, name, unit="", description=""):
+ super().create_gauge(name, unit=unit, description=description)
+
  def create_observable_gauge(self, name, callback, unit="", description=""):
  super().create_observable_gauge(
  name, callback, unit=unit, description=description
@@ -64,6 +67,7 @@ def test_repeated_instrument_names(self):
  test_meter.create_up_down_counter("up_down_counter")
  test_meter.create_observable_counter("observable_counter", Mock())
  test_meter.create_histogram("histogram")
+ test_meter.create_gauge("gauge")
  test_meter.create_observable_gauge("observable_gauge", Mock())
  test_meter.create_observable_up_down_counter(
  "observable_up_down_counter", Mock()
@@ -75,6 +79,7 @@ def test_repeated_instrument_names(self):
  "counter",
  "up_down_counter",
  "histogram",
+ "gauge",
  ]:
  with self.assertLogs(level=WARNING):
  getattr(test_meter, f"create_{instrument_name}")(
@@ -123,6 +128,14 @@ def test_create_histogram(self):
  self.assertTrue(hasattr(Meter, "create_histogram"))
  self.assertTrue(Meter.create_histogram.__isabstractmethod__)
 
+ def test_create_gauge(self):
+ """
+ Test that the meter provides a function to create a new Gauge
+ """
+
+ self.assertTrue(hasattr(Meter, "create_gauge"))
+ self.assertTrue(Meter.create_gauge.__isabstractmethod__)
+
  def test_create_observable_gauge(self):
  """
  Test that the meter provides a function to create a new ObservableGauge