Skip to content

Commit a707bb9

Browse files
authored
Update code documentation for Metric instruments (#2281)
1 parent c322a50 commit a707bb9

File tree

5 files changed

+55
-0
lines changed

5 files changed

+55
-0
lines changed

opentelemetry/src/metrics/instruments/counter.rs

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ use std::sync::Arc;
55
use super::SyncInstrument;
66

77
/// An instrument that records increasing values.
8+
///
9+
/// [`Counter`] can be cloned to create multiple handles to the same instrument. If a [`Counter`] needs to be shared,
10+
/// users are recommended to clone the [`Counter`] instead of creating duplicate [`Counter`]s for the same metric. Creating
11+
/// duplicate [`Counter`]s for the same metric could lower SDK performance.
812
#[derive(Clone)]
913
#[non_exhaustive]
1014
pub struct Counter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/instruments/gauge.rs

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ use std::sync::Arc;
55
use super::SyncInstrument;
66

77
/// An instrument that records independent values
8+
///
9+
/// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
10+
/// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
11+
/// duplicate [`Gauge`]s for the same metric could lower SDK performance.
812
#[derive(Clone)]
913
#[non_exhaustive]
1014
pub struct Gauge<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/instruments/histogram.rs

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ use std::sync::Arc;
55
use super::SyncInstrument;
66

77
/// An instrument that records a distribution of values.
8+
///
9+
/// [`Histogram`] can be cloned to create multiple handles to the same instrument. If a [`Histogram`] needs to be shared,
10+
/// users are recommended to clone the [`Histogram`] instead of creating duplicate [`Histogram`]s for the same metric. Creating
11+
/// duplicate [`Histogram`]s for the same metric could lower SDK performance.
812
#[derive(Clone)]
913
#[non_exhaustive]
1014
pub struct Histogram<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/instruments/up_down_counter.rs

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ use std::sync::Arc;
55
use super::SyncInstrument;
66

77
/// An instrument that records increasing or decreasing values.
8+
///
9+
/// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
10+
/// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
11+
/// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
812
#[derive(Clone)]
913
#[non_exhaustive]
1014
pub struct UpDownCounter<T>(Arc<dyn SyncInstrument<T> + Send + Sync>);

opentelemetry/src/metrics/meter.rs

+39
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,10 @@ impl Meter {
309309
}
310310

311311
/// creates an instrument builder for recording increasing values.
312+
///
313+
/// [`Counter`] can be cloned to create multiple handles to the same instrument. If a [`Counter`] needs to be shared,
314+
/// users are recommended to clone the [`Counter`] instead of creating duplicate [`Counter`]s for the same metric. Creating
315+
/// duplicate [`Counter`]s for the same metric could lower SDK performance.
312316
pub fn u64_counter(
313317
&self,
314318
name: impl Into<Cow<'static, str>>,
@@ -317,6 +321,10 @@ impl Meter {
317321
}
318322

319323
/// creates an instrument builder for recording increasing values.
324+
///
325+
/// [`Counter`] can be cloned to create multiple handles to the same instrument. If a [`Counter`] needs to be shared,
326+
/// users are recommended to clone the [`Counter`] instead of creating duplicate [`Counter`]s for the same metric. Creating
327+
/// duplicate [`Counter`]s for the same metric could lower SDK performance.
320328
pub fn f64_counter(
321329
&self,
322330
name: impl Into<Cow<'static, str>>,
@@ -341,6 +349,10 @@ impl Meter {
341349
}
342350

343351
/// creates an instrument builder for recording changes of a value.
352+
///
353+
/// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
354+
/// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
355+
/// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
344356
pub fn i64_up_down_counter(
345357
&self,
346358
name: impl Into<Cow<'static, str>>,
@@ -349,6 +361,10 @@ impl Meter {
349361
}
350362

351363
/// creates an instrument builder for recording changes of a value.
364+
///
365+
/// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
366+
/// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
367+
/// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
352368
pub fn f64_up_down_counter(
353369
&self,
354370
name: impl Into<Cow<'static, str>>,
@@ -357,6 +373,10 @@ impl Meter {
357373
}
358374

359375
/// creates an instrument builder for recording changes of a value via callback.
376+
///
377+
/// [`UpDownCounter`] can be cloned to create multiple handles to the same instrument. If a [`UpDownCounter`] needs to be shared,
378+
/// users are recommended to clone the [`UpDownCounter`] instead of creating duplicate [`UpDownCounter`]s for the same metric. Creating
379+
/// duplicate [`UpDownCounter`]s for the same metric could lower SDK performance.
360380
pub fn i64_observable_up_down_counter(
361381
&self,
362382
name: impl Into<Cow<'static, str>>,
@@ -373,6 +393,10 @@ impl Meter {
373393
}
374394

375395
/// creates an instrument builder for recording independent values.
396+
///
397+
/// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
398+
/// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
399+
/// duplicate [`Gauge`]s for the same metric could lower SDK performance.
376400
pub fn u64_gauge(
377401
&self,
378402
name: impl Into<Cow<'static, str>>,
@@ -381,6 +405,10 @@ impl Meter {
381405
}
382406

383407
/// creates an instrument builder for recording independent values.
408+
///
409+
/// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
410+
/// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
411+
/// duplicate [`Gauge`]s for the same metric could lower SDK performance.
384412
pub fn f64_gauge(
385413
&self,
386414
name: impl Into<Cow<'static, str>>,
@@ -389,6 +417,9 @@ impl Meter {
389417
}
390418

391419
/// creates an instrument builder for recording independent values.
420+
/// [`Gauge`] can be cloned to create multiple handles to the same instrument. If a [`Gauge`] needs to be shared,
421+
/// users are recommended to clone the [`Gauge`] instead of creating duplicate [`Gauge`]s for the same metric. Creating
422+
/// duplicate [`Gauge`]s for the same metric could lower SDK performance.
392423
pub fn i64_gauge(
393424
&self,
394425
name: impl Into<Cow<'static, str>>,
@@ -421,6 +452,10 @@ impl Meter {
421452
}
422453

423454
/// creates an instrument builder for recording a distribution of values.
455+
///
456+
/// [`Histogram`] can be cloned to create multiple handles to the same instrument. If a [`Histogram`] needs to be shared,
457+
/// users are recommended to clone the [`Histogram`] instead of creating duplicate [`Histogram`]s for the same metric. Creating
458+
/// duplicate [`Histogram`]s for the same metric could lower SDK performance.
424459
pub fn f64_histogram(
425460
&self,
426461
name: impl Into<Cow<'static, str>>,
@@ -429,6 +464,10 @@ impl Meter {
429464
}
430465

431466
/// creates an instrument builder for recording a distribution of values.
467+
///
468+
/// [`Histogram`] can be cloned to create multiple handles to the same instrument. If a [`Histogram`] needs to be shared,
469+
/// users are recommended to clone the [`Histogram`] instead of creating duplicate [`Histogram`]s for the same metric. Creating
470+
/// duplicate [`Histogram`]s for the same metric could lower SDK performance.
432471
pub fn u64_histogram(
433472
&self,
434473
name: impl Into<Cow<'static, str>>,

0 commit comments

Comments
 (0)