diff --git a/tokio/src/runtime/builder.rs b/tokio/src/runtime/builder.rs index 883713e8230..abdc4475550 100644 --- a/tokio/src/runtime/builder.rs +++ b/tokio/src/runtime/builder.rs @@ -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 diff --git a/tokio/src/runtime/metrics/runtime.rs b/tokio/src/runtime/metrics/runtime.rs index 53f82648481..adf5866a95d 100644 --- a/tokio/src/runtime/metrics/runtime.rs +++ b/tokio/src/runtime/metrics/runtime.rs @@ -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 { + pub fn poll_time_histogram_bucket_range(&self, bucket: usize) -> Range { 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 { + 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 diff --git a/tokio/tests/rt_unstable_metrics.rs b/tokio/tests/rt_unstable_metrics.rs index b7dcceef85c..bfe3d7f2a68 100644 --- a/tokio/tests/rt_unstable_metrics.rs +++ b/tokio/tests/rt_unstable_metrics.rs @@ -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()); } }