Skip to content

Commit

Permalink
metrics: rename *_poll_count_* to *_poll_time_* (#6924)
Browse files Browse the repository at this point in the history 
A consistent bit of feedback I've heard is that the `poll_count_histogram` name is a little confusing since the value customers actually get out of it is `poll_times`.

This renames all public APIs from `poll_count` to `poll_time`. The existing APIs were deprecated with one exception: the newly added `poll_count_histogram_configuration` which hasn't been released yet was simply renamed.
  • Loading branch information
@rcoh
rcoh authored Oct 22, 2024
1 parent da745ff commit fbfeb9a
Show file tree
Hide file tree
Showing 3 changed files with 119 additions and 82 deletions.
51 changes: 30 additions & 21 deletions tokio/src/runtime/builder.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1099,12 +1099,12 @@ impl Builder {
///
/// The histogram uses fixed bucket sizes. In other words, the histogram
/// buckets are not dynamic based on input values. Use the
/// `metrics_poll_count_histogram_` builder methods to configure the
/// `metrics_poll_time_histogram` builder methods to configure the
/// histogram details.
///
/// By default, a linear histogram with 10 buckets each 100 microseconds wide will be used.
/// This has an extremely low memory footprint, but may not provide enough granularity. For
/// better granularity with low memory usage, use [`metrics_poll_count_histogram_configuration()`]
/// better granularity with low memory usage, use [`metrics_poll_time_histogram_configuration()`]
/// to select [`LogHistogram`] instead.
///
/// # Examples
Expand All @@ -1113,26 +1113,35 @@ impl Builder {
/// use tokio::runtime;
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap();
/// # // Test default values here
/// # fn us(n: u64) -> std::time::Duration { std::time::Duration::from_micros(n) }
/// # let m = rt.handle().metrics();
/// # assert_eq!(m.poll_count_histogram_num_buckets(), 10);
/// # assert_eq!(m.poll_count_histogram_bucket_range(0), us(0)..us(100));
/// # assert_eq!(m.poll_count_histogram_bucket_range(1), us(100)..us(200));
/// # assert_eq!(m.poll_time_histogram_num_buckets(), 10);
/// # assert_eq!(m.poll_time_histogram_bucket_range(0), us(0)..us(100));
/// # assert_eq!(m.poll_time_histogram_bucket_range(1), us(100)..us(200));
/// ```
///
/// [`Handle::metrics()`]: crate::runtime::Handle::metrics
/// [`Instant::now()`]: std::time::Instant::now
/// [`LogHistogram`]: crate::runtime::LogHistogram
/// [`metrics_poll_count_histogram_configuration()`]: Builder::metrics_poll_count_histogram_configuration
pub fn enable_metrics_poll_count_histogram(&mut self) -> &mut Self {
/// [`metrics_poll_time_histogram_configuration()`]: Builder::metrics_poll_time_histogram_configuration
pub fn enable_metrics_poll_time_histogram(&mut self) -> &mut Self {
self.metrics_poll_count_histogram_enable = true;
self
}

/// Deprecated. Use [`enable_metrics_poll_time_histogram()`] instead.
///
/// [`enable_metrics_poll_time_histogram()`]: Builder::enable_metrics_poll_time_histogram
#[deprecated(note = "`poll_count_histogram` related methods have been renamed `poll_time_histogram` to better reflect their functionality.")]
#[doc(hidden)]
pub fn enable_metrics_poll_count_histogram(&mut self) -> &mut Self {
self.enable_metrics_poll_time_histogram()
}

/// Sets the histogram scale for tracking the distribution of task poll
/// times.
///
Expand All @@ -1151,12 +1160,12 @@ impl Builder {
///
/// # #[allow(deprecated)]
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_count_histogram_scale(HistogramScale::Log)
/// .build()
/// .unwrap();
/// ```
#[deprecated(note = "use metrics_poll_count_histogram_configuration")]
#[deprecated(note = "use `metrics_poll_time_histogram_configuration`")]
pub fn metrics_poll_count_histogram_scale(&mut self, histogram_scale: crate::runtime::HistogramScale) -> &mut Self {
self.metrics_poll_count_histogram.legacy_mut(|b|b.scale = histogram_scale);
self
Expand All @@ -1175,8 +1184,8 @@ impl Builder {
/// use tokio::runtime::{HistogramConfiguration, LogHistogram};
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .metrics_poll_count_histogram_configuration(
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_time_histogram_configuration(
/// HistogramConfiguration::log(LogHistogram::default())
/// )
/// .build()
Expand All @@ -1190,8 +1199,8 @@ impl Builder {
/// use tokio::runtime::HistogramConfiguration;
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .metrics_poll_count_histogram_configuration(
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_time_histogram_configuration(
/// HistogramConfiguration::linear(Duration::from_micros(10), 100)
/// )
/// .build()
Expand All @@ -1208,8 +1217,8 @@ impl Builder {
/// use tokio::runtime::{HistogramConfiguration, LogHistogram};
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .metrics_poll_count_histogram_configuration(
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_time_histogram_configuration(
/// HistogramConfiguration::log(LogHistogram::builder()
/// .max_value(Duration::from_secs(120))
/// .min_value(Duration::from_nanos(100))
Expand All @@ -1224,7 +1233,7 @@ impl Builder {
///
/// [`LogHistogram`]: crate::runtime::LogHistogram
/// [default configuration]: crate::runtime::LogHistogramBuilder
pub fn metrics_poll_count_histogram_configuration(&mut self, configuration: HistogramConfiguration) -> &mut Self {
pub fn metrics_poll_time_histogram_configuration(&mut self, configuration: HistogramConfiguration) -> &mut Self {
self.metrics_poll_count_histogram.histogram_type = configuration.inner;
self
}
Expand All @@ -1251,12 +1260,12 @@ impl Builder {
///
/// # #[allow(deprecated)]
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_count_histogram_resolution(Duration::from_micros(100))
/// .build()
/// .unwrap();
/// ```
#[deprecated(note = "use metrics_poll_count_histogram_configuration")]
#[deprecated(note = "use `metrics_poll_time_histogram_configuration`")]
pub fn metrics_poll_count_histogram_resolution(&mut self, resolution: Duration) -> &mut Self {
assert!(resolution > Duration::from_secs(0));
// Sanity check the argument and also make the cast below safe.
Expand Down Expand Up @@ -1285,12 +1294,12 @@ impl Builder {
///
/// # #[allow(deprecated)]
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_count_histogram_buckets(15)
/// .build()
/// .unwrap();
/// ```
#[deprecated(note = "use `metrics_poll_count_histogram_configuration")]
#[deprecated(note = "use `metrics_poll_time_histogram_configuration`")]
pub fn metrics_poll_count_histogram_buckets(&mut self, buckets: usize) -> &mut Self {
self.metrics_poll_count_histogram.legacy_mut(|b|b.num_buckets = buckets);
self
Expand Down
81 changes: 56 additions & 25 deletions tokio/src/runtime/metrics/runtime.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -731,7 +731,7 @@ impl RuntimeMetrics {
///
/// Task poll times are not instrumented by default as doing so requires
/// calling [`Instant::now()`] twice per task poll. The feature is enabled
/// by calling [`enable_metrics_poll_count_histogram()`] when building the
/// by calling [`enable_metrics_poll_time_histogram()`] when building the
/// runtime.
///
/// # Examples
Expand All @@ -741,33 +741,39 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let enabled = metrics.poll_count_histogram_enabled();
/// let enabled = metrics.poll_time_histogram_enabled();
///
/// println!("Tracking task poll time distribution: {:?}", enabled);
/// });
/// }
/// ```
///
/// [`enable_metrics_poll_count_histogram()`]: crate::runtime::Builder::enable_metrics_poll_count_histogram
/// [`enable_metrics_poll_time_histogram()`]: crate::runtime::Builder::enable_metrics_poll_time_histogram
/// [`Instant::now()`]: std::time::Instant::now
pub fn poll_count_histogram_enabled(&self) -> bool {
pub fn poll_time_histogram_enabled(&self) -> bool {
self.handle
.inner
.worker_metrics(0)
.poll_count_histogram
.is_some()
}

#[deprecated(note = "Renamed to `poll_time_histogram_enabled`")]
#[doc(hidden)]
pub fn poll_count_histogram_enabled(&self) -> bool {
self.poll_time_histogram_enabled()
}

/// Returns the number of histogram buckets tracking the distribution of
/// task poll times.
///
/// This value is configured by calling
/// [`metrics_poll_count_histogram_configuration()`] when building the runtime.
/// [`metrics_poll_time_histogram_configuration()`] when building the runtime.
///
/// # Examples
///
Expand All @@ -776,21 +782,21 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let buckets = metrics.poll_count_histogram_num_buckets();
/// let buckets = metrics.poll_time_histogram_num_buckets();
///
/// println!("Histogram buckets: {:?}", buckets);
/// });
/// }
/// ```
///
/// [`metrics_poll_count_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_count_histogram_configuration
pub fn poll_count_histogram_num_buckets(&self) -> usize {
/// [`metrics_poll_time_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_time_histogram_configuration
pub fn poll_time_histogram_num_buckets(&self) -> usize {
self.handle
.inner
.worker_metrics(0)
Expand All @@ -800,15 +806,24 @@ impl RuntimeMetrics {
.unwrap_or_default()
}

/// Deprecated. Use [`poll_time_histogram_num_buckets()`] instead.
///
/// [`poll_time_histogram_num_buckets()`]: Self::poll_time_histogram_num_buckets
#[doc(hidden)]
#[deprecated(note = "renamed to `poll_time_histogram_num_buckets`.")]
pub fn poll_count_histogram_num_buckets(&self) -> usize {
self.poll_time_histogram_num_buckets()
}

/// Returns the range of task poll times tracked by the given bucket.
///
/// This value is configured by calling
/// [`metrics_poll_count_histogram_configuration()`] when building the runtime.
/// [`metrics_poll_time_histogram_configuration()`] when building the runtime.
///
/// # Panics
///
/// The method panics if `bucket` represents an invalid bucket index, i.e.
/// is greater than or equal to `poll_count_histogram_num_buckets()`.
/// is greater than or equal to `poll_time_histogram_num_buckets()`.
///
/// # Examples
///
Expand All @@ -817,25 +832,25 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let buckets = metrics.poll_count_histogram_num_buckets();
/// let buckets = metrics.poll_time_histogram_num_buckets();
///
/// for i in 0..buckets {
/// let range = metrics.poll_count_histogram_bucket_range(i);
/// let range = metrics.poll_time_histogram_bucket_range(i);
/// println!("Histogram bucket {} range: {:?}", i, range);
/// }
/// });
/// }
/// ```
///
/// [`metrics_poll_count_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_count_histogram_configuration
/// [`metrics_poll_time_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_time_histogram_configuration
#[track_caller]
pub fn poll_count_histogram_bucket_range(&self, bucket: usize) -> Range<Duration> {
pub fn poll_time_histogram_bucket_range(&self, bucket: usize) -> Range<Duration> {
self.handle
.inner
.worker_metrics(0)
Expand All @@ -851,6 +866,16 @@ impl RuntimeMetrics {
.unwrap_or_default()
}

/// Deprecated. Use [`poll_time_histogram_bucket_range()`] instead.
///
/// [`poll_time_histogram_bucket_range()`]: Self::poll_time_histogram_bucket_range
#[track_caller]
#[doc(hidden)]
#[deprecated(note = "renamed to `poll_time_histogram_bucket_range`")]
pub fn poll_count_histogram_bucket_range(&self, bucket: usize) -> Range<Duration> {
self.poll_time_histogram_bucket_range(bucket)
}

cfg_64bit_metrics! {
/// Returns the number of times the given worker polled tasks with a poll
/// duration within the given bucket's range.
Expand All @@ -872,7 +897,7 @@ impl RuntimeMetrics {
///
/// `bucket` is the index of the bucket being queried. The bucket is scoped
/// to the worker. The range represented by the bucket can be queried by
/// calling [`poll_count_histogram_bucket_range()`]. Each worker maintains
/// calling [`poll_time_histogram_bucket_range()`]. Each worker maintains
/// identical bucket ranges.
///
/// # Panics
Expand All @@ -888,26 +913,26 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let buckets = metrics.poll_count_histogram_num_buckets();
/// let buckets = metrics.poll_time_histogram_num_buckets();
///
/// for worker in 0..metrics.num_workers() {
/// for i in 0..buckets {
/// let count = metrics.poll_count_histogram_bucket_count(worker, i);
/// let count = metrics.poll_time_histogram_bucket_count(worker, i);
/// println!("Poll count {}", count);
/// }
/// }
/// });
/// }
/// ```
///
/// [`poll_count_histogram_bucket_range()`]: crate::runtime::RuntimeMetrics::poll_count_histogram_bucket_range
/// [`poll_time_histogram_bucket_range()`]: crate::runtime::RuntimeMetrics::poll_time_histogram_bucket_range
#[track_caller]
pub fn poll_count_histogram_bucket_count(&self, worker: usize, bucket: usize) -> u64 {
pub fn poll_time_histogram_bucket_count(&self, worker: usize, bucket: usize) -> u64 {
self.handle
.inner
.worker_metrics(worker)
Expand All @@ -917,6 +942,12 @@ impl RuntimeMetrics {
.unwrap_or_default()
}

#[doc(hidden)]
#[deprecated(note = "use `poll_time_histogram_bucket_count` instead")]
pub fn poll_count_histogram_bucket_count(&self, worker: usize, bucket: usize) -> u64 {
self.poll_time_histogram_bucket_count(worker, bucket)
}

/// Returns the mean duration of task polls, in nanoseconds.
///
/// This is an exponentially weighted moving average. Currently, this metric
Expand Down
Loading

0 comments on commit fbfeb9a

Please sign in to comment.