[Metrics API] Simplify public API contract of instruments for SDK (#2207)

Co-authored-by: Cijo Thomas <[email protected]>

Author: utpilla

opentelemetry-sdk/src/metrics/instrument.rs

@@ -1,7 +1,7 @@
 use std::{borrow::Cow, collections::HashSet, sync::Arc};
 
 use opentelemetry::{
-    metrics::{AsyncInstrument, SyncCounter, SyncGauge, SyncHistogram, SyncUpDownCounter},
+    metrics::{AsyncInstrument, SyncInstrument},
     Key, KeyValue,
 };
 
@@ -252,32 +252,8 @@ pub(crate) struct ResolvedMeasures<T> {
     pub(crate) measures: Vec<Arc<dyn Measure<T>>>,
 }
 
-impl<T: Copy + 'static> SyncCounter<T> for ResolvedMeasures<T> {
-    fn add(&self, val: T, attrs: &[KeyValue]) {
-        for measure in &self.measures {
-            measure.call(val, attrs)
-        }
-    }
-}
-
-impl<T: Copy + 'static> SyncUpDownCounter<T> for ResolvedMeasures<T> {
-    fn add(&self, val: T, attrs: &[KeyValue]) {
-        for measure in &self.measures {
-            measure.call(val, attrs)
-        }
-    }
-}
-
-impl<T: Copy + 'static> SyncGauge<T> for ResolvedMeasures<T> {
-    fn record(&self, val: T, attrs: &[KeyValue]) {
-        for measure in &self.measures {
-            measure.call(val, attrs)
-        }
-    }
-}
-
-impl<T: Copy + 'static> SyncHistogram<T> for ResolvedMeasures<T> {
-    fn record(&self, val: T, attrs: &[KeyValue]) {
+impl<T: Copy + 'static> SyncInstrument<T> for ResolvedMeasures<T> {
+    fn measure(&self, val: T, attrs: &[KeyValue]) {
         for measure in &self.measures {
             measure.call(val, attrs)
         }

opentelemetry-sdk/src/metrics/noop.rs

@@ -1,8 +1,5 @@
 use opentelemetry::{
-    metrics::{
-        AsyncInstrument, InstrumentProvider, SyncCounter, SyncGauge, SyncHistogram,
-        SyncUpDownCounter,
-    },
+    metrics::{AsyncInstrument, InstrumentProvider, SyncInstrument},
     KeyValue,
 };
 
@@ -34,26 +31,8 @@ impl NoopSyncInstrument {
     }
 }
 
-impl<T> SyncCounter<T> for NoopSyncInstrument {
-    fn add(&self, _value: T, _attributes: &[KeyValue]) {
-        // Ignored
-    }
-}
-
-impl<T> SyncUpDownCounter<T> for NoopSyncInstrument {
-    fn add(&self, _value: T, _attributes: &[KeyValue]) {
-        // Ignored
-    }
-}
-
-impl<T> SyncHistogram<T> for NoopSyncInstrument {
-    fn record(&self, _value: T, _attributes: &[KeyValue]) {
-        // Ignored
-    }
-}
-
-impl<T> SyncGauge<T> for NoopSyncInstrument {
-    fn record(&self, _value: T, _attributes: &[KeyValue]) {
+impl<T> SyncInstrument<T> for NoopSyncInstrument {
+    fn measure(&self, _value: T, _attributes: &[KeyValue]) {
         // Ignored
     }
 }

opentelemetry/CHANGELOG.md

@@ -4,7 +4,8 @@
 
 - Bump MSRV to 1.70 [#2179](https://github.com/open-telemetry/opentelemetry-rust/pull/2179)
 - Add `LogRecord::set_trace_context`; an optional method conditional on the `trace` feature for setting trace context on a log record.
-- Remove unnecessary public methods named `as_any` from `AsyncInstrument` trait and the implementing instruments: `ObservableCounter`, `ObservableGauge`, and `ObservableUpDownCounter` [#2187](https://github.com/open-telemetry/opentelemetry-rust/issues/2187)
+- Removed unnecessary public methods named `as_any` from `AsyncInstrument` trait and the implementing instruments: `ObservableCounter`, `ObservableGauge`, and `ObservableUpDownCounter` [#2187](https://github.com/open-telemetry/opentelemetry-rust/issues/2187)
+- Introduced `SyncInstrument` trait to replace the individual synchronous instrument traits (`SyncCounter`, `SyncGauge`, `SyncHistogram`, `SyncUpDownCounter`) which are meant for SDK implementation. [#2207](https://github.com/open-telemetry/opentelemetry-rust/issues/2207)
 
 ## v0.26.0
 Released 2024-Sep-30

opentelemetry/src/metrics/instruments/counter.rs

@@ -2,16 +2,12 @@ use crate::{metrics::AsyncInstrument, KeyValue};
 use core::fmt;
 use std::sync::Arc;
 
-/// An SDK implemented instrument that records increasing values.
-pub trait SyncCounter<T> {
-    /// Records an increment to the counter.
-    fn add(&self, value: T, attributes: &[KeyValue]);
-}
+use super::SyncInstrument;
 
 /// An instrument that records increasing values.
 #[derive(Clone)]
 #[non_exhaustive]
-pub struct Counter<T>(Arc<dyn SyncCounter<T> + Send + Sync>);
+pub struct Counter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
 
 impl<T> fmt::Debug for Counter<T>
 where
@@ -24,13 +20,13 @@ where
 
 impl<T> Counter<T> {
     /// Create a new counter.
-    pub fn new(inner: Arc<dyn SyncCounter<T> + Send + Sync>) -> Self {
+    pub fn new(inner: Arc<dyn SyncInstrument<T> + Send + Sync>) -> Self {
         Counter(inner)
     }
 
     /// Records an increment to the counter.
     pub fn add(&self, value: T, attributes: &[KeyValue]) {
-        self.0.add(value, attributes)
+        self.0.measure(value, attributes)
     }
 }
 

opentelemetry/src/metrics/instruments/gauge.rs

@@ -2,16 +2,12 @@ use crate::{metrics::AsyncInstrument, KeyValue};
 use core::fmt;
 use std::sync::Arc;
 
-/// An SDK implemented instrument that records independent values
-pub trait SyncGauge<T> {
-    /// Records an independent value.
-    fn record(&self, value: T, attributes: &[KeyValue]);
-}
+use super::SyncInstrument;
 
 /// An instrument that records independent values
 #[derive(Clone)]
 #[non_exhaustive]
-pub struct Gauge<T>(Arc<dyn SyncGauge<T> + Send + Sync>);
+pub struct Gauge<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
 
 impl<T> fmt::Debug for Gauge<T>
 where
@@ -24,13 +20,13 @@ where
 
 impl<T> Gauge<T> {
     /// Create a new gauge.
-    pub fn new(inner: Arc<dyn SyncGauge<T> + Send + Sync>) -> Self {
+    pub fn new(inner: Arc<dyn SyncInstrument<T> + Send + Sync>) -> Self {
         Gauge(inner)
     }
 
     /// Records an independent value.
     pub fn record(&self, value: T, attributes: &[KeyValue]) {
-        self.0.record(value, attributes)
+        self.0.measure(value, attributes)
     }
 }
 

opentelemetry/src/metrics/instruments/histogram.rs

@@ -2,16 +2,12 @@ use crate::KeyValue;
 use core::fmt;
 use std::sync::Arc;
 
-/// An SDK implemented instrument that records a distribution of values.
-pub trait SyncHistogram<T> {
-    /// Adds an additional value to the distribution.
-    fn record(&self, value: T, attributes: &[KeyValue]);
-}
+use super::SyncInstrument;
 
 /// An instrument that records a distribution of values.
 #[derive(Clone)]
 #[non_exhaustive]
-pub struct Histogram<T>(Arc<dyn SyncHistogram<T> + Send + Sync>);
+pub struct Histogram<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
 
 impl<T> fmt::Debug for Histogram<T>
 where
@@ -24,12 +20,12 @@ where
 
 impl<T> Histogram<T> {
     /// Create a new histogram.
-    pub fn new(inner: Arc<dyn SyncHistogram<T> + Send + Sync>) -> Self {
+    pub fn new(inner: Arc<dyn SyncInstrument<T> + Send + Sync>) -> Self {
         Histogram(inner)
     }
 
     /// Adds an additional value to the distribution.
     pub fn record(&self, value: T, attributes: &[KeyValue]) {
-        self.0.record(value, attributes)
+        self.0.measure(value, attributes)
     }
 }

opentelemetry/src/metrics/instruments/mod.rs

@@ -24,6 +24,12 @@ pub trait AsyncInstrument<T>: Send + Sync {
     fn observe(&self, measurement: T, attributes: &[KeyValue]);
 }
 
+/// An SDK implemented instrument that records measurements synchronously.
+pub trait SyncInstrument<T>: Send + Sync {
+    /// Records a measurement synchronously.
+    fn measure(&self, measurement: T, attributes: &[KeyValue]);
+}
+
 /// Configuration for building a Histogram.
 #[non_exhaustive] // We expect to add more configuration fields in the future
 pub struct HistogramBuilder<'a, T> {

opentelemetry/src/metrics/instruments/up_down_counter.rs

@@ -2,18 +2,12 @@ use crate::KeyValue;
 use core::fmt;
 use std::sync::Arc;
 
-use super::AsyncInstrument;
-
-/// An SDK implemented instrument that records increasing or decreasing values.
-pub trait SyncUpDownCounter<T> {
-    /// Records an increment or decrement to the counter.
-    fn add(&self, value: T, attributes: &[KeyValue]);
-}
+use super::{AsyncInstrument, SyncInstrument};
 
 /// An instrument that records increasing or decreasing values.
 #[derive(Clone)]
 #[non_exhaustive]
-pub struct UpDownCounter<T>(Arc<dyn SyncUpDownCounter<T> + Send + Sync>);
+pub struct UpDownCounter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
 
 impl<T> fmt::Debug for UpDownCounter<T>
 where
@@ -29,13 +23,13 @@ where
 
 impl<T> UpDownCounter<T> {
     /// Create a new up down counter.
-    pub fn new(inner: Arc<dyn SyncUpDownCounter<T> + Send + Sync>) -> Self {
+    pub fn new(inner: Arc<dyn SyncInstrument<T> + Send + Sync>) -> Self {
         UpDownCounter(inner)
     }
 
     /// Records an increment or decrement to the counter.
     pub fn add(&self, value: T, attributes: &[KeyValue]) {
-        self.0.add(value, attributes)
+        self.0.measure(value, attributes)
     }
 }
 

opentelemetry/src/metrics/mod.rs

@@ -13,11 +13,12 @@ pub(crate) mod noop;
 
 use crate::{Array, ExportError, KeyValue, Value};
 pub use instruments::{
-    counter::{Counter, ObservableCounter, SyncCounter},
-    gauge::{Gauge, ObservableGauge, SyncGauge},
-    histogram::{Histogram, SyncHistogram},
-    up_down_counter::{ObservableUpDownCounter, SyncUpDownCounter, UpDownCounter},
+    counter::{Counter, ObservableCounter},
+    gauge::{Gauge, ObservableGauge},
+    histogram::Histogram,
+    up_down_counter::{ObservableUpDownCounter, UpDownCounter},
     AsyncInstrument, AsyncInstrumentBuilder, Callback, HistogramBuilder, InstrumentBuilder,
+    SyncInstrument,
 };
 pub use meter::{Meter, MeterProvider};
 

opentelemetry/src/metrics/noop.rs

@@ -4,14 +4,13 @@
 //! has been set. It is expected to have minimal resource utilization and
 //! runtime impact.
 use crate::{
-    metrics::{
-        AsyncInstrument, InstrumentProvider, Meter, MeterProvider, SyncCounter, SyncGauge,
-        SyncHistogram, SyncUpDownCounter,
-    },
+    metrics::{AsyncInstrument, InstrumentProvider, Meter, MeterProvider},
     KeyValue,
 };
 use std::sync::Arc;
 
+use super::instruments::SyncInstrument;
+
 /// A no-op instance of a `MetricProvider`
 #[derive(Debug, Default)]
 pub(crate) struct NoopMeterProvider {
@@ -65,26 +64,8 @@ impl NoopSyncInstrument {
     }
 }
 
-impl<T> SyncCounter<T> for NoopSyncInstrument {
-    fn add(&self, _value: T, _attributes: &[KeyValue]) {
-        // Ignored
-    }
-}
-
-impl<T> SyncUpDownCounter<T> for NoopSyncInstrument {
-    fn add(&self, _value: T, _attributes: &[KeyValue]) {
-        // Ignored
-    }
-}
-
-impl<T> SyncHistogram<T> for NoopSyncInstrument {
-    fn record(&self, _value: T, _attributes: &[KeyValue]) {
-        // Ignored
-    }
-}
-
-impl<T> SyncGauge<T> for NoopSyncInstrument {
-    fn record(&self, _value: T, _attributes: &[KeyValue]) {
+impl<T> SyncInstrument<T> for NoopSyncInstrument {
+    fn measure(&self, _value: T, _attributes: &[KeyValue]) {
         // Ignored
     }
 }