From f8f57e37dc7fce3193d0a79562acd0d97d1d483f Mon Sep 17 00:00:00 2001
From: Utkarsh Umesan Pillai <66651184+utpilla@users.noreply.github.com>
Date: Wed, 6 Nov 2024 23:39:15 +0000
Subject: [PATCH 1/3] Update Metrics API docs

---
 .../src/metrics/instruments/counter.rs        |  4 +++
 .../src/metrics/instruments/gauge.rs          |  4 +++
 .../src/metrics/instruments/histogram.rs      |  2 ++
 .../metrics/instruments/up_down_counter.rs    |  4 +++
 opentelemetry/src/metrics/meter.rs            | 32 +++++++++++++++++++
 5 files changed, 46 insertions(+)

diff --git a/opentelemetry/src/metrics/instruments/counter.rs b/opentelemetry/src/metrics/instruments/counter.rs
index 171756f46b..39fc596821 100644
--- a/opentelemetry/src/metrics/instruments/counter.rs
+++ b/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> {
diff --git a/opentelemetry/src/metrics/instruments/gauge.rs b/opentelemetry/src/metrics/instruments/gauge.rs
index 914c3178a9..8f2c781249 100644
--- a/opentelemetry/src/metrics/instruments/gauge.rs
+++ b/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> {
diff --git a/opentelemetry/src/metrics/instruments/histogram.rs b/opentelemetry/src/metrics/instruments/histogram.rs
index ed5da8dbce..5bf2e33214 100644
--- a/opentelemetry/src/metrics/instruments/histogram.rs
+++ b/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>);
diff --git a/opentelemetry/src/metrics/instruments/up_down_counter.rs b/opentelemetry/src/metrics/instruments/up_down_counter.rs
index 0814e41cda..2844866575 100644
--- a/opentelemetry/src/metrics/instruments/up_down_counter.rs
+++ b/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> {
diff --git a/opentelemetry/src/metrics/meter.rs b/opentelemetry/src/metrics/meter.rs
index 15846865e1..cde9a98185 100644
--- a/opentelemetry/src/metrics/meter.rs
+++ b/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>>,

From d46cc1dc01c3bf70f8616f3e7db5a737285d5618 Mon Sep 17 00:00:00 2001
From: Utkarsh Umesan Pillai <66651184+utpilla@users.noreply.github.com>
Date: Thu, 7 Nov 2024 22:58:15 +0000
Subject: [PATCH 2/3] Remove documentation for asynchronous instruments

---
 opentelemetry/src/metrics/instruments/counter.rs   |  2 --
 opentelemetry/src/metrics/instruments/gauge.rs     |  2 --
 .../src/metrics/instruments/up_down_counter.rs     |  2 --
 opentelemetry/src/metrics/meter.rs                 | 14 --------------
 4 files changed, 20 deletions(-)

diff --git a/opentelemetry/src/metrics/instruments/counter.rs b/opentelemetry/src/metrics/instruments/counter.rs
index 39fc596821..9751605bee 100644
--- a/opentelemetry/src/metrics/instruments/counter.rs
+++ b/opentelemetry/src/metrics/instruments/counter.rs
@@ -33,8 +33,6 @@ 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> {
diff --git a/opentelemetry/src/metrics/instruments/gauge.rs b/opentelemetry/src/metrics/instruments/gauge.rs
index 8f2c781249..2b821d9b2b 100644
--- a/opentelemetry/src/metrics/instruments/gauge.rs
+++ b/opentelemetry/src/metrics/instruments/gauge.rs
@@ -33,8 +33,6 @@ 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> {
diff --git a/opentelemetry/src/metrics/instruments/up_down_counter.rs b/opentelemetry/src/metrics/instruments/up_down_counter.rs
index 2844866575..f691499da7 100644
--- a/opentelemetry/src/metrics/instruments/up_down_counter.rs
+++ b/opentelemetry/src/metrics/instruments/up_down_counter.rs
@@ -36,8 +36,6 @@ 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> {
diff --git a/opentelemetry/src/metrics/meter.rs b/opentelemetry/src/metrics/meter.rs
index cde9a98185..b4ce3483cb 100644
--- a/opentelemetry/src/metrics/meter.rs
+++ b/opentelemetry/src/metrics/meter.rs
@@ -329,8 +329,6 @@ 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>>,
@@ -339,8 +337,6 @@ 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>>,
@@ -369,8 +365,6 @@ 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>>,
@@ -379,8 +373,6 @@ 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>>,
@@ -419,8 +411,6 @@ 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>>,
@@ -429,8 +419,6 @@ 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>>,
@@ -439,8 +427,6 @@ 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>>,

From a1c56e6b3547fe60165facb083e82b7db2c6389b Mon Sep 17 00:00:00 2001
From: Utkarsh Umesan Pillai <66651184+utpilla@users.noreply.github.com>
Date: Fri, 8 Nov 2024 00:50:31 +0000
Subject: [PATCH 3/3] Address PR comments

---
 .../src/metrics/instruments/counter.rs        |  4 +-
 .../src/metrics/instruments/gauge.rs          |  4 +-
 .../src/metrics/instruments/histogram.rs      |  4 +-
 .../metrics/instruments/up_down_counter.rs    |  4 +-
 opentelemetry/src/metrics/meter.rs            | 41 ++++++++++++++-----
 5 files changed, 43 insertions(+), 14 deletions(-)

diff --git a/opentelemetry/src/metrics/instruments/counter.rs b/opentelemetry/src/metrics/instruments/counter.rs
index 9751605bee..8d72657686 100644
--- a/opentelemetry/src/metrics/instruments/counter.rs
+++ b/opentelemetry/src/metrics/instruments/counter.rs
@@ -6,7 +6,9 @@ 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.
+/// [`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>);
diff --git a/opentelemetry/src/metrics/instruments/gauge.rs b/opentelemetry/src/metrics/instruments/gauge.rs
index 2b821d9b2b..0b2bb4d82c 100644
--- a/opentelemetry/src/metrics/instruments/gauge.rs
+++ b/opentelemetry/src/metrics/instruments/gauge.rs
@@ -6,7 +6,9 @@ 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.
+/// [`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>);
diff --git a/opentelemetry/src/metrics/instruments/histogram.rs b/opentelemetry/src/metrics/instruments/histogram.rs
index 5bf2e33214..73c7d0bc96 100644
--- a/opentelemetry/src/metrics/instruments/histogram.rs
+++ b/opentelemetry/src/metrics/instruments/histogram.rs
@@ -6,7 +6,9 @@ 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.
+/// [`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>);
diff --git a/opentelemetry/src/metrics/instruments/up_down_counter.rs b/opentelemetry/src/metrics/instruments/up_down_counter.rs
index f691499da7..b9fb996329 100644
--- a/opentelemetry/src/metrics/instruments/up_down_counter.rs
+++ b/opentelemetry/src/metrics/instruments/up_down_counter.rs
@@ -6,7 +6,9 @@ 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.
+/// [`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>);
diff --git a/opentelemetry/src/metrics/meter.rs b/opentelemetry/src/metrics/meter.rs
index b4ce3483cb..e22b23502a 100644
--- a/opentelemetry/src/metrics/meter.rs
+++ b/opentelemetry/src/metrics/meter.rs
@@ -310,7 +310,9 @@ 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.
+    /// [`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>>,
@@ -320,7 +322,9 @@ 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.
+    /// [`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>>,
@@ -346,7 +350,9 @@ 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.
+    /// [`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>>,
@@ -356,7 +362,9 @@ 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.
+    /// [`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>>,
@@ -365,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>>,
@@ -382,7 +394,9 @@ 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.
+    /// [`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>>,
@@ -392,7 +406,9 @@ 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.
+    /// [`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>>,
@@ -401,8 +417,9 @@ 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.
+    /// [`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>>,
@@ -436,7 +453,9 @@ 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.
+    /// [`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>>,
@@ -446,7 +465,9 @@ 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.
+    /// [`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>>,