Update code documentation for Metric instruments

opentelemetry/src/metrics/instruments/counter.rs

@@ -5,6 +5,8 @@ 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. Avoid creating duplicate [`Counter`]s for the same instrument.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct Counter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
@@ -31,6 +33,8 @@ impl<T> Counter<T> {
 }
 
 /// An async instrument that records increasing values.
+///
+/// [`ObservableCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableCounter`]s for the same instrument.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct ObservableCounter<T> {

opentelemetry/src/metrics/instruments/gauge.rs

@@ -5,6 +5,8 @@ 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. Avoid creating duplicate [`Gauge`]s for the same instrument.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct Gauge<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
@@ -31,6 +33,8 @@ impl<T> Gauge<T> {
 }
 
 /// An async instrument that records independent readings.
+///
+/// [`ObservableGauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableGauge`]s for the same instrument.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct ObservableGauge<T> {

opentelemetry/src/metrics/instruments/histogram.rs

@@ -5,6 +5,8 @@ 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. Avoid creating duplicate [`Histogram`]s for the same instrument.
 #[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,8 @@ 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. Avoid creating duplicate [`UpDownCounter`]s for the same instrument.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct UpDownCounter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);
@@ -34,6 +36,8 @@ impl<T> UpDownCounter<T> {
 }
 
 /// An async instrument that records increasing or decreasing values.
+///
+/// [`ObservableUpDownCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableUpDownCounter`]s for the same instrument.
 #[derive(Clone)]
 #[non_exhaustive]
 pub struct ObservableUpDownCounter<T> {

opentelemetry/src/metrics/meter.rs

@@ -309,6 +309,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording increasing values.
+    ///
+    /// [`Counter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Counter`]s for the same instrument.
     pub fn u64_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -317,6 +319,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording increasing values.
+    ///
+    /// [`Counter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Counter`]s for the same instrument.
     pub fn f64_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -325,6 +329,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording increasing values via callback.
+    ///
+    /// [`ObservableCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableCounter`]s for the same instrument.
     pub fn u64_observable_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -333,6 +339,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording increasing values via callback.
+    ///
+    /// [`ObservableCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableCounter`]s for the same instrument.
     pub fn f64_observable_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -341,6 +349,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value.
+    ///
+    /// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`UpDownCounter`]s for the same instrument.
     pub fn i64_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -349,6 +359,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value.
+    ///
+    /// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`UpDownCounter`]s for the same instrument.
     pub fn f64_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -357,6 +369,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value via callback.
+    ///
+    /// [`ObservableUpDownCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableUpDownCounter`]s for the same instrument.
     pub fn i64_observable_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -365,6 +379,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording changes of a value via callback.
+    ///
+    /// [`ObservableUpDownCounter`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableUpDownCounter`]s for the same instrument.
     pub fn f64_observable_up_down_counter(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -373,6 +389,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording independent values.
+    ///
+    /// [`Gauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Gauge`]s for the same instrument.
     pub fn u64_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -381,6 +399,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording independent values.
+    ///
+    /// [`Gauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Gauge`]s for the same instrument.
     pub fn f64_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -389,6 +409,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording independent values.
+    ///
+    /// /// [`Gauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Gauge`]s for the same instrument.
     pub fn i64_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -397,6 +419,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording the current value via callback.
+    ///
+    /// [`ObservableGauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableGauge`]s for the same instrument.
     pub fn u64_observable_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -405,6 +429,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording the current value via callback.
+    ///
+    /// [`ObservableGauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableGauge`]s for the same instrument.
     pub fn i64_observable_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -413,6 +439,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording the current value via callback.
+    ///
+    /// [`ObservableGauge`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`ObservableGauge`]s for the same instrument.
     pub fn f64_observable_gauge(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -421,6 +449,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording a distribution of values.
+    ///
+    /// [`Histogram`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Histogram`]s for the same instrument.
     pub fn f64_histogram(
         &self,
         name: impl Into<Cow<'static, str>>,
@@ -429,6 +459,8 @@ impl Meter {
     }
 
     /// creates an instrument builder for recording a distribution of values.
+    ///
+    /// [`Histogram`] can be cloned to create multiple handles to the same instrument. Avoid creating duplicate [`Histogram`]s for the same instrument.
     pub fn u64_histogram(
         &self,
         name: impl Into<Cow<'static, str>>,