metrics: rename *_poll_count_* to *_poll_time_* (#6924)

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.
This commit is contained in:
Russell Cohen
2024-10-22 09:21:07 +02:00
committed by GitHub
parent da745ff335
commit fbfeb9a68a
3 changed files with 119 additions and 82 deletions
+30 -21
View File
@@ -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
@@ -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.
///
@@ -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
@@ -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()
@@ -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()
@@ -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))
@@ -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
}
@@ -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.
@@ -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
+56 -25
View File
@@ -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
@@ -741,21 +741,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 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)
@@ -763,11 +763,17 @@ impl RuntimeMetrics {
.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
///
@@ -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)
@@ -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
///
@@ -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)
@@ -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.
@@ -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
@@ -888,16 +913,16 @@ 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);
/// }
/// }
@@ -905,9 +930,9 @@ impl RuntimeMetrics {
/// }
/// ```
///
/// [`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)
@@ -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
+33 -36
View File
@@ -355,9 +355,9 @@ fn worker_poll_count_and_time() {
assert_eq!(Duration::default(), metrics.worker_mean_poll_time(0));
// Does not populate the histogram
assert!(!metrics.poll_count_histogram_enabled());
assert!(!metrics.poll_time_histogram_enabled());
for i in 0..10 {
assert_eq!(0, metrics.poll_count_histogram_bucket_count(0, i));
assert_eq!(0, metrics.poll_time_histogram_bucket_count(0, i));
}
let rt = threaded();
@@ -382,10 +382,10 @@ fn worker_poll_count_and_time() {
assert!(n > Duration::default());
// Does not populate the histogram
assert!(!metrics.poll_count_histogram_enabled());
assert!(!metrics.poll_time_histogram_enabled());
for n in 0..metrics.num_workers() {
for i in 0..10 {
assert_eq!(0, metrics.poll_count_histogram_bucket_count(n, i));
assert_eq!(0, metrics.poll_time_histogram_bucket_count(n, i));
}
}
}
@@ -395,8 +395,8 @@ fn log_histogram() {
const N: u64 = 50;
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.enable_metrics_poll_count_histogram()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::log(
.enable_metrics_poll_time_histogram()
.metrics_poll_time_histogram_configuration(HistogramConfiguration::log(
LogHistogram::builder()
.max_value(Duration::from_secs(60))
.min_value(Duration::from_nanos(100))
@@ -405,7 +405,7 @@ fn log_histogram() {
.build()
.unwrap();
let metrics = rt.metrics();
let num_buckets = rt.metrics().poll_count_histogram_num_buckets();
let num_buckets = rt.metrics().poll_time_histogram_num_buckets();
assert_eq!(num_buckets, 119);
rt.block_on(async {
for _ in 0..N {
@@ -414,20 +414,20 @@ fn log_histogram() {
});
drop(rt);
assert_eq!(
metrics.poll_count_histogram_bucket_range(0),
metrics.poll_time_histogram_bucket_range(0),
Duration::from_nanos(0)..Duration::from_nanos(96)
);
assert_eq!(
metrics.poll_count_histogram_bucket_range(1),
metrics.poll_time_histogram_bucket_range(1),
Duration::from_nanos(96)..Duration::from_nanos(96 + 2_u64.pow(4))
);
assert_eq!(
metrics.poll_count_histogram_bucket_range(118).end,
metrics.poll_time_histogram_bucket_range(118).end,
Duration::from_nanos(u64::MAX)
);
let n = (0..metrics.num_workers())
.flat_map(|i| (0..num_buckets).map(move |j| (i, j)))
.map(|(worker, bucket)| metrics.poll_count_histogram_bucket_count(worker, bucket))
.map(|(worker, bucket)| metrics.poll_time_histogram_bucket_count(worker, bucket))
.sum();
assert_eq!(N, n);
}
@@ -436,13 +436,13 @@ fn log_histogram() {
fn log_histogram_default_configuration() {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.enable_metrics_poll_count_histogram()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::log(
.enable_metrics_poll_time_histogram()
.metrics_poll_time_histogram_configuration(HistogramConfiguration::log(
LogHistogram::default(),
))
.build()
.unwrap();
let num_buckets = rt.metrics().poll_count_histogram_num_buckets();
let num_buckets = rt.metrics().poll_time_histogram_num_buckets();
assert_eq!(num_buckets, 119);
}
@@ -453,8 +453,8 @@ fn worker_poll_count_histogram() {
let rts = [
tokio::runtime::Builder::new_current_thread()
.enable_all()
.enable_metrics_poll_count_histogram()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::linear(
.enable_metrics_poll_time_histogram()
.metrics_poll_time_histogram_configuration(HistogramConfiguration::linear(
Duration::from_millis(50),
3,
))
@@ -463,8 +463,8 @@ fn worker_poll_count_histogram() {
tokio::runtime::Builder::new_multi_thread()
.worker_threads(2)
.enable_all()
.enable_metrics_poll_count_histogram()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::linear(
.enable_metrics_poll_time_histogram()
.metrics_poll_time_histogram_configuration(HistogramConfiguration::linear(
Duration::from_millis(50),
3,
))
@@ -482,14 +482,14 @@ fn worker_poll_count_histogram() {
drop(rt);
let num_workers = metrics.num_workers();
let num_buckets = metrics.poll_count_histogram_num_buckets();
let num_buckets = metrics.poll_time_histogram_num_buckets();
assert!(metrics.poll_count_histogram_enabled());
assert!(metrics.poll_time_histogram_enabled());
assert_eq!(num_buckets, 3);
let n = (0..num_workers)
.flat_map(|i| (0..num_buckets).map(move |j| (i, j)))
.map(|(worker, bucket)| metrics.poll_count_histogram_bucket_count(worker, bucket))
.map(|(worker, bucket)| metrics.poll_time_histogram_bucket_count(worker, bucket))
.sum();
assert_eq!(N, n);
}
@@ -501,24 +501,21 @@ fn worker_poll_count_histogram_range() {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.enable_metrics_poll_count_histogram()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::linear(us(50), 3))
.enable_metrics_poll_time_histogram()
.metrics_poll_time_histogram_configuration(HistogramConfiguration::linear(us(50), 3))
.build()
.unwrap();
let metrics = rt.metrics();
assert_eq!(metrics.poll_count_histogram_bucket_range(0), us(0)..us(50));
assert_eq!(
metrics.poll_count_histogram_bucket_range(1),
us(50)..us(100)
);
assert_eq!(metrics.poll_count_histogram_bucket_range(2), us(100)..max);
assert_eq!(metrics.poll_time_histogram_bucket_range(0), us(0)..us(50));
assert_eq!(metrics.poll_time_histogram_bucket_range(1), us(50)..us(100));
assert_eq!(metrics.poll_time_histogram_bucket_range(2), us(100)..max);
// ensure the old methods work too
#[allow(deprecated)]
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.enable_metrics_poll_count_histogram()
.enable_metrics_poll_time_histogram()
.metrics_poll_count_histogram_scale(tokio::runtime::HistogramScale::Log)
.metrics_poll_count_histogram_buckets(3)
.metrics_poll_count_histogram_resolution(us(50))
@@ -529,9 +526,9 @@ fn worker_poll_count_histogram_range() {
let a = Duration::from_nanos(50000_u64.next_power_of_two());
let b = a * 2;
assert_eq!(metrics.poll_count_histogram_bucket_range(0), us(0)..a);
assert_eq!(metrics.poll_count_histogram_bucket_range(1), a..b);
assert_eq!(metrics.poll_count_histogram_bucket_range(2), b..max);
assert_eq!(metrics.poll_time_histogram_bucket_range(0), us(0)..a);
assert_eq!(metrics.poll_time_histogram_bucket_range(1), a..b);
assert_eq!(metrics.poll_time_histogram_bucket_range(2), b..max);
}
#[test]
@@ -539,7 +536,7 @@ fn worker_poll_count_histogram_disabled_without_explicit_enable() {
let rts = [
tokio::runtime::Builder::new_current_thread()
.enable_all()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::linear(
.metrics_poll_time_histogram_configuration(HistogramConfiguration::linear(
Duration::from_millis(50),
3,
))
@@ -548,7 +545,7 @@ fn worker_poll_count_histogram_disabled_without_explicit_enable() {
tokio::runtime::Builder::new_multi_thread()
.worker_threads(2)
.enable_all()
.metrics_poll_count_histogram_configuration(HistogramConfiguration::linear(
.metrics_poll_time_histogram_configuration(HistogramConfiguration::linear(
Duration::from_millis(50),
3,
))
@@ -558,7 +555,7 @@ fn worker_poll_count_histogram_disabled_without_explicit_enable() {
for rt in rts {
let metrics = rt.metrics();
assert!(!metrics.poll_count_histogram_enabled());
assert!(!metrics.poll_time_histogram_enabled());
}
}