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

rcoh · web-flow · commit fbfeb9a68a22 · 2024-10-22T09:21:07.000+02:00
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.
diff --git 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
@@ -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,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
         ///
@@ -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,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)
@@ -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
