Update code documentation for Metric instruments (#2281)

opentelemetry/src/metrics/instruments/counter.rs

@@ -5,6 +5,10 @@ use std::sync::Arc;
 use super::SyncInstrument;
 
 /// An instrument that records increasing values.
+///
+/// [`Counter`] can be cloned to create multiple handles to the same instrument. If a [`Counter`] needs to be shared,
+/// users are recommended to clone the [`Counter`] instead of creating duplicate [`Counter`]s for the same metric. Creating
+/// duplicate [`Counter`]s for the same metric could lower SDK performance.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct Counter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/instruments/gauge.rs

@@ -5,6 +5,10 @@ use std::sync::Arc;
 use super::SyncInstrument;
 
 /// An instrument that records independent values
+///
+/// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
+/// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
+/// duplicate [`Gauge`]s for the same metric could lower SDK performance.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct Gauge<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/instruments/histogram.rs

@@ -5,6 +5,10 @@ use std::sync::Arc;
 use super::SyncInstrument;
 
 /// An instrument that records a distribution of values.
+///
+/// [`Histogram`] can be cloned to create multiple handles to the same instrument. If a [`Histogram`] needs to be shared,
+/// users are recommended to clone the [`Histogram`] instead of creating duplicate [`Histogram`]s for the same metric. Creating
+/// duplicate [`Histogram`]s for the same metric could lower SDK performance.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct Histogram<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/instruments/up_down_counter.rs

@@ -5,6 +5,10 @@ use std::sync::Arc;
 use super::SyncInstrument;
 
 /// An instrument that records increasing or decreasing values.
+///
+/// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
+/// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
+/// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct UpDownCounter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/meter.rs

@@ -309,6 +309,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording increasing values.
+    ///
+    /// [`Counter`] can be cloned to create multiple handles to the same instrument. If a [`Counter`] needs to be shared,
+    /// users are recommended to clone the [`Counter`] instead of creating duplicate [`Counter`]s for the same metric. Creating
+    /// duplicate [`Counter`]s for the same metric could lower SDK performance.
     pub fn u64_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -317,6 +321,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording increasing values.
+    ///
+    /// [`Counter`] can be cloned to create multiple handles to the same instrument. If a [`Counter`] needs to be shared,
+    /// users are recommended to clone the [`Counter`] instead of creating duplicate [`Counter`]s for the same metric. Creating
+    /// duplicate [`Counter`]s for the same metric could lower SDK performance.
     pub fn f64_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -341,6 +349,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value.
+    ///
+    /// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
+    /// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
+    /// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
     pub fn i64_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -349,6 +361,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value.
+    ///
+    /// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
+    /// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
+    /// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
     pub fn f64_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -357,6 +373,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value via callback.
+    ///
+    /// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
+    /// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
+    /// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
     pub fn i64_observable_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -373,6 +393,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording independent values.
+    ///
+    /// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
+    /// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
+    /// duplicate [`Gauge`]s for the same metric could lower SDK performance.
     pub fn u64_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -381,6 +405,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording independent values.
+    ///
+    /// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
+    /// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
+    /// duplicate [`Gauge`]s for the same metric could lower SDK performance.
     pub fn f64_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -389,6 +417,9 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording independent values.
+    /// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
+    /// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
+    /// duplicate [`Gauge`]s for the same metric could lower SDK performance.
     pub fn i64_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -421,6 +452,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording a distribution of values.
+    ///
+    /// [`Histogram`] can be cloned to create multiple handles to the same instrument. If a [`Histogram`] needs to be shared,
+    /// users are recommended to clone the [`Histogram`] instead of creating duplicate [`Histogram`]s for the same metric. Creating
+    /// duplicate [`Histogram`]s for the same metric could lower SDK performance.
     pub fn f64_histogram(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -429,6 +464,10 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording a distribution of values.
+    ///
+    /// [`Histogram`] can be cloned to create multiple handles to the same instrument. If a [`Histogram`] needs to be shared,
+    /// users are recommended to clone the [`Histogram`] instead of creating duplicate [`Histogram`]s for the same metric. Creating
+    /// duplicate [`Histogram`]s for the same metric could lower SDK performance.
     pub fn u64_histogram(
         &self,
         name: impl Into<Cow<'static, str>>,