[docs] adding more metrics documentation (#2574)

* [docs] adding more metrics documentation

Adding docs around instruments and the methods to create them. I've also added an exclusion list for things that aren't really useful for users.

* fix lint

Co-authored-by: Srikanth Chekuri <[email protected]>

Author: Alex Boten

docs/conf.py

@@ -147,6 +147,7 @@
     "undoc-members": True,
     "show-inheritance": True,
     "member-order": "bysource",
+    "exclude-members": "_ProxyObservableUpDownCounter,_ProxyHistogram,_ProxyObservableGauge,_ProxyInstrument,_ProxyAsynchronousInstrument,_ProxyCounter,_ProxyUpDownCounter,_ProxyObservableCounter,_ProxyObservableGauge,_abc_impl",
 }
 
 # -- Options for HTML output -------------------------------------------------

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

@@ -136,19 +136,33 @@ def schema_url(self):
 
     @abstractmethod
     def create_counter(self, name, unit="", description="") -> Counter:
-        pass
+        """Creates a `Counter` instrument
+
+        Args:
+            name: The name of the instrument to be created
+            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.
+        """
 
     @abstractmethod
     def create_up_down_counter(
         self, name, unit="", description=""
     ) -> UpDownCounter:
-        pass
+        """Creates an `UpDownCounter` instrument
+
+        Args:
+            name: The name of the instrument to be created
+            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.
+        """
 
     @abstractmethod
     def create_observable_counter(
         self, name, callback, unit="", description=""
     ) -> ObservableCounter:
-        """Creates an observable counter instrument
+        """Creates an `ObservableCounter` instrument
 
         An observable counter observes a monotonically increasing count by
         calling a provided callback which returns multiple
@@ -229,19 +243,48 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Measurem
 
     @abstractmethod
     def create_histogram(self, name, unit="", description="") -> Histogram:
-        pass
+        """Creates a `Histogram` instrument
+
+        Args:
+            name: The name of the instrument to be created
+            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.
+        """
 
     @abstractmethod
     def create_observable_gauge(
         self, name, callback, unit="", description=""
     ) -> ObservableGauge:
-        pass
+        """Creates an `ObservableGauge` instrument
+
+        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.
+        """
 
     @abstractmethod
     def create_observable_up_down_counter(
         self, name, callback, unit="", description=""
     ) -> ObservableUpDownCounter:
-        pass
+        """Creates an `ObservableUpDownCounter` instrument
+
+        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.
+        """
 
 
 class _ProxyMeter(Meter):

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

@@ -111,6 +111,8 @@ class _NonMonotonic(_Adding):
 
 
 class Counter(_Monotonic, Synchronous):
+    """A Counter is a synchronous `Instrument` which supports non-negative increments."""
+
     @abstractmethod
     def add(self, amount, attributes=None):
         # FIXME check that the amount is non negative
@@ -135,6 +137,8 @@ def _create_real_instrument(self, meter: "metrics.Meter") -> Counter:
 
 
 class UpDownCounter(_NonMonotonic, Synchronous):
+    """An UpDownCounter is a synchronous `Instrument` which supports increments and decrements."""
+
     @abstractmethod
     def add(self, amount, attributes=None):
         pass
@@ -160,7 +164,9 @@ def _create_real_instrument(self, meter: "metrics.Meter") -> UpDownCounter:
 
 
 class ObservableCounter(_Monotonic, Asynchronous):
-    pass
+    """An ObservableCounter is an asynchronous `Instrument` which reports monotonically
+    increasing value(s) when the instrument is being observed.
+    """
 
 
 class DefaultObservableCounter(ObservableCounter):
@@ -180,7 +186,10 @@ def _create_real_instrument(
 
 
 class ObservableUpDownCounter(_NonMonotonic, Asynchronous):
-    pass
+    """An ObservableUpDownCounter is an asynchronous `Instrument` which reports additive value(s) (e.g.
+    the process heap size - it makes sense to report the heap size from multiple processes and sum them
+    up, so we get the total heap usage) when the instrument is being observed.
+    """
 
 
 class DefaultObservableUpDownCounter(ObservableUpDownCounter):
@@ -201,6 +210,11 @@ def _create_real_instrument(
 
 
 class Histogram(_Grouping, Synchronous):
+    """Histogram is a synchronous `Instrument` which can be used to report arbitrary values
+    that are likely to be statistically meaningful. It is intended for statistics such as
+    histograms, summaries, and percentile.
+    """
+
     @abstractmethod
     def record(self, amount, attributes=None):
         pass
@@ -226,7 +240,10 @@ def _create_real_instrument(self, meter: "metrics.Meter") -> Histogram:
 
 
 class ObservableGauge(_Grouping, Asynchronous):
-    pass
+    """Asynchronous Gauge is an asynchronous `Instrument` which reports non-additive value(s) (e.g.
+    the room temperature - it makes no sense to report the temperature value from multiple rooms
+    and sum them up) when the instrument is being observed.
+    """
 
 
 class DefaultObservableGauge(ObservableGauge):